IHE ITI TF Vol2

3.40 Provide X-User Assertion [ITI-40]

This section corresponds to transaction [ITI-40] of the IHE IT Infrastructure Technical Framework.

3.40.1 Scope

Transaction [ITI-40] is used by the X-Service User to pass a claimed identity assertion to the X-Service Provider. The X-Service User and X-Service Provider use the X-Assertion Provider as the third party issuer of the claimed identity assertion.

3.40.2 Use Case Roles

Actor: X-Service User

Role: User of a transaction that requires a Cross-Enterprise User Assertion

Actor: X-Service Provider

Role: Service provider on a transaction that requires a Cross-Enterprise User Assertion

3.40.3 Referenced Standards

3.40.3.1 Normative -- required to use this transaction

OASIS http://www.oasis-open.org/committees/security/ .
SAMLCore SAML V2.0 Core standard
WSS10 OASIS Standard, "OASIS Web Services Security: SOAP Message Security 1.0 (WS-Security 2004)", March 2004.
WSS11 OASIS Standard, "OASIS Web Services Security: SOAP Message Security 1.1 (WS-Security 2004)", February 2006.
WSS:SAMLTokenProfile1.0 OASIS Standard, “Web Services Security: SAML Token Profile”, December 2004
WSS:SAMLTokenProfile1.1 OASIS Standard, “Web Services Security: SAML Token Profile 1.1”, February 2006
XSPA-SAMLv1.0 OASIS Standard, “Cross-Enterprise Security and Privacy Authorization (XSPA) Profile of the Security Assertion Markup Language (SAML) for Healthcare v1.0” , November 2009
SAML 2.0 Profile For XACML 2.0 OASIS Standard, February 2005

3.40.3.2 Informative -- assist with understanding or implementing this transaction

IHE Profiles

OASIS

SAML V2.0 Standards http://www.oasis-open.org/committees/security/.
SAML V2.0 Technical Overview
SAML Executive Overview
SAML Tutorial presentation by Eve Maler of Sun Microsystems
SAML Specifications
WS-Trust - OASIS Web Services Secure Exchange (WS-SX) TC
XSPA-XACMLv1.0 OASIS Standard, “Cross-Enterprise Security and Privacy Authorization (XSPA) Profile of XACML v2.0 for Healthcare v1.0” , November 2009

3.40.4 Messages

Figure 3.40.4-1: X-User Assertion Messages

3.40.4.1 Provide X-User Assertion

The Provide X-User Assertion is profiled to assure interoperability between an X-Service User and an X-Service Provider that need an Assertion about the entity requesting the service. There are many ways to provide an Assertion that are all acceptable and may be used by parties that have agreed to their use.

The Provide X-User Assertion transaction sets some minimal interoperability profiling for this use-case. The Provide X-User Assertion transaction shall be used when there is no other agreed upon policy that would assure User Assertion interoperability (e.g., WS-SecurityPolicy).

3.40.4.1.1 Trigger

Configuration of the X-Service Provider and X-Service User indicates when the X-User Assertion transaction is necessary.

3.40.4.1.2 Message Semantics

The X-User Assertion must be protected at all times against confidentiality exposure, malicious modification, and trust relationship between those communicating it. The IHE actors that are grouped with XUA may already require the ATNA Profile and thus TLS Mutual-Authentication, Integrity, and Confidentiality.

The X-Service User shall include the OASIS Web Services Security (WSS) Header, and shall include a SAML 2.0 Assertion as the security token.

Any ATNA Audit Messages that the X-Service User records in relationship to a transaction protected by the XUA (e.g., XDS.b Registry Stored Query, and XDS.b Retrieve Document Set), shall have the user identity recorded according to the XUA specific ATNA encoding rules (see Section 3.40.4.2 ATNA Audit encoding). This assures that the X-Service User and X-Service Provider ATNA Audit messages can be correlated at the ATNA Audit Record Repository.

Any ATNA Audit Messages recorded by actor grouped with the X-Service User Actor, shall have the user identity recorded according to the XUA specific ATNA encoding rules (see Section 3.40.4.2 ATNA Audit encoding). For example: The XDS.b Document Consumer records the Query event, this event record will include the identity provided in the XUA Identity Assertion. This assures that the X-Service User and X-Service Provider ATNA Audit messages can be correlated at the ATNA Audit Record Repository.

The SAML 2.0 Assertion is profiled as follows :

The Assertion shall contain a Subject. The Subject contains the logical identifier of the principal performing the original service request (person, application, etc.) and remains unchanged through operations acting on the assertion (e.g., proxying the Assertion).

The Subject shall contain a SubjectConfirmation element. The bearer confirmation method shall be supported; the holder-of-key method may be supported. These methods are defined in the SAML 2.0 Profile specification, Section 3.

The SAML Assertion Conditions are profiled as:

NotBefore shall be populated with the issue instant of the Assertion
NotOnOrAfter is not specified by XUA because reasonable time limits are not clear at the IHE Profile level. The Expiration is provided by the X-Assertion Provider and would be variable on an Affinity Domain and/or System level.
The assertion shall contain an AudienceRestriction containing an Audience whose value is a URI identifying the X-Service Provider (e.g., XDS Registry, XDS Repository). It may contain an Audience whose value is a URI identifying the Affinity Domain.
The Assertion may contain ProxyRestriction and OneTimeUser conditions but XUA actors may ignore these conditions.

The Assertion shall contain an AuthnStatement specify the AuthnContextClassRef or AuthnContextDeclRef
The Assertion may contain other statements (e.g., Attributes). The SAML specification allows for multiple AttributeStatements, and multiple Attributes within each AttributeStatement. Repetition at both levels is allowed; recipients shall support repetition at both levels. The AttributeStatement element describes a statement by the SAML authority asserting that the requesting user is associated with the specified attributes. All Attributes defined in this transaction can have multiple values within an Assertion, unless otherwise noted. Multiple values shall be represented in their own AttributeValue element. Multiple values should be repeated within a single Attribute element, but may be encoded using multiple Attributes and/or AttributeStatements. When Local Policy requires that the following attributes are carried in the SAML assertion then they should be encoded as follows:
Subject ID : The value on the Subject ID attribute shall be a plain text description of the user's name (not user ID).
This <Attribute> element shall have the Name attribute set to "urn:oasis:names:tc:xspa:1.0:subject:subject-id". (Note: This value for the Name attribute is historic and is no longer in the underlying XSPA specification.) The name of the user shall be placed in the value of the <AttributeValue> element. (Keep in mind that the term “subject” in SAML and XACML refers to the individual making the request; in this specification, the term “User” is generally used with the same meaning, but when referring to attributes defined in SAML or XACML, the naming convention of the standard is retained.) <saml:Attribute Name="urn:oasis:names:tc:xspa:1.0:subject:subject-id"> <saml:AttributeValue>Walter H.Brattain IV</saml:AttributeValue> </saml:Attribute>
Subject Organization : The value on Subject Organization attribute shall be a plain text description of the organization.
This <Attribute> element shall have the Name attribute set to "urn:oasis:names:tc:xspa:1.0:subject:organization". In plain text, the organization that the user belongs to shall be placed in the value of the <AttributeValue> element. <saml:Attribute Name="urn:oasis:names:tc:xspa:1.0:subject:organization"> <saml:AttributeValue>Family Medical Clinic</saml:AttributeValue> </saml:Attribute>
Subject Organization ID Attribute
This <Attribute> element shall have the Name attribute set to "urn:oasis:names:tc:xspa:1.0:subject:organization-id" A unique identifier for the organization that the user is representing in performing this transaction shall be placed in the value of the <AttributeValue> element. This organization ID shall be consistent with the plain-text name of the organization provided in the User Organization Attribute. The organization ID may be an Object Identifier (OID), using the urn format (that is, “urn:oid:” appended with the OID); or it may be a URL assigned to that organization. <saml:Attribute Name="urn:oasis:names:tc:xspa:1.0:subject:organization-id"> <saml:AttributeValue>http://familymedicalclinic.org</saml:AttributeValue> </saml:Attribute>
Home Community ID Attribute
This <Attribute> element shall have the Name attribute set to "urn:ihe:iti:xca:2010:homeCommunityId". The value shall be the Home Community ID (an Object Identifier) assigned to the Community that is initiating the request, using the urn format (that is, “urn:oid:” appended with the OID). <saml:Attribute Name="urn:ihe:iti:xca:2010:homeCommunityId"> <saml:AttributeValue>urn:oid:2.16.840.1.113883.3.190</saml:AttributeValue> </saml:Attribute>
National Provider Identifier (NPI) Attribute
A National Provider Identifier (NPI) is a unique identifier issued to health care providers by their national authority. (e.g., in the United States this is a 10-digit number assigned by the Centers for Medicare and Medicaid Services (CMS)). This attribute provides the ability to specify an NPI value as part of the SAML assertion that accompanies a message. When a simple string is used there needs to be a mutually agreed upon assigning authority. The Other Provider Identifier Attribute can be used to explicitly show the assigning authority (see use in the Other Provider Identifier Attribute below).
Note: Usage of a HL7 CE type in this attribute is permitted for backward compatibility.
This <Attribute> element SHALL have the Name attribute set to "urn:oasis:names:tc:xspa:1.0:subject:npi". An example of the syntax of this element follows: <saml:Attribute Name="urn:oasis:names:tc:xspa:1.0:subject:npi"> <saml:AttributeValue>1234567890</saml:AttributeValue> </saml:Attribute>
Other Provider Identifier Attribute
A unique identifier issued to health care providers by a named authority. This <Attribute> may be repeated.
This <Attribute> element SHALL have the Name attribute set to "urn:ihe:iti:xua:2017:subject:provider-identifier". The value of the <AttributeValue> element is a child element, “id”, in the namespace “urn:hl7-org:v3”, whose content is defined by the “II” (instance identifier) data type from the HL7 version 3 abstract data type specification. The “id” element must contain a “root” attribute and an “extension” attribute. It may also contain an “assigningAuthorityName” attribute and a “displayable” attribute. The “root” attribute shall contain an OID identifying the authority issuing the provider identifier. The “extension” attribute shall contain the provider identifier itself. The “assigningAuthorityName” attribute may be used to include a human readable name for the assigning authority identified by the “root” attribute. The “displayable” attribute may be included to signal that the identifier is human readable (if set to “true”) or intended for machine reading (if set to “false”). An example of the syntax of this element follows: <saml:Attribute Name="urn:ihe:iti:xua:2017:subject:provider-identifier"> <saml:AttributeValue> <id xmlns="urn:hl7-org:v3" xsi:type="II" extension="1234567890" root="2.999.1.2.3.4.5" assigningAuthorityName="Example Authority" displayable="true"/> </saml:AttributeValue> </saml:Attribute>
The Assertion may contain other statements (e.g., Attributes)
The Assertion shall be signed by the X-Assertion Provider as defined in SAML Core.

The interface between the X-Service User and the X-Assertion Provider is not specified by XUA. This interface needs to be protected against risks (e.g., exposure of the SAML Token to interception for malicious use). Assertions need to be carefully managed in the X-Service User to ensure they are not exposed in the application code or any subsequent use of the Assertion.

3.40.4.1.2.1 Subject-Role Option

When the Subject-Role Option is used the X-Service User shall encode the relevant user subject roles from a locally defined Code-Set into subject role <Attribute> element(s). The Subject-Role values communicated are assertions from the X-Service User perspective.

The subject role <Attribute> element shall have the Name attribute set to "urn:oasis:names:tc:xacml:2.0:subject:role". The value of the <AttributeValue> element is a child element, “Role”, in the namespace “urn:hl7-org:v3”, whose content is defined by the “CE” (coded with equivalents) data type from the HL7 version 3 specification. The code attribute shall contain the role code from the identified Value-Set that represents the role that the XUA user is playing when making the request. The displayName attribute may be used to include a human readable representation of the role code. The codeSystem attribute shall contain the OID of the coding system that the role code was taken from. The codeSystemName attribute shall identify the name of the coding system. No other parts of the CE data type shall be used. The following is an example of the syntax of this element:


<saml:Attribute Name="urn:oasis:names:tc:xacml:2.0:subject:role">
<saml:AttributeValue>
  <Role xmlns="urn:hl7-org:v3" xsi:type="CE" code="46255001"
    codeSystem="2.16.840.1.113883.6.96" codeSystemName="SNOMED_CT"
    displayName="Pharmacist"/>
</saml:AttributeValue>
</saml:Attribute>

3.40.4.1.2.2 Authz-Consent Option

When the Authz-Consent Option is supported and a policy identifier needs to be sent, the X-Service User shall include the document unique ID of the Patient Privacy Policy Acknowledgement Document or include the Patient Privacy Policy Identifier for a policy that has been previously published encoded as SAML attributes.

A Patient Privacy Policy Acknowledgement Document unique ID shall be encoded as a SAML attribute in the IHE ITI namespace, "urn:ihe:iti:bppc:2007:docid", with name format "urn:oasis:names:tc:SAML:2.0:attrname-format:uri". Access to the content is not specified. Access through an XDS/XCA/XDR/XDM mechanism is a potential approach. Similarly, this option does not specify how the policy documents should be used to make access control decisions. A sample attribute fragment is given in Figure 3.40.4.1.2.2-1.


<saml2:Attribute FriendlyName="Patient Privacy Policy Acknowledgement Document"
     Name="urn:ihe:iti:bppc:2007:docid"
     NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:type="xs:anyURI">urn:oid:1.2.3.xxx</saml2:AttributeValue>
</saml2:Attribute>

Figure: 3.40.4.1.2.2-1: Sample attribute holding a reference to patient acknowledgement

A Patient Privacy Policy Identifier shall be encoded as a SAML attribute in the IHE ITI namespace, "urn:ihe:iti:xua:2012:acp", with name format "urn:oasis:names:tc:SAML:2.0:attrname-format:uri". The policy identifier shall be expressed using the xs:anyURI data type. The referenced policy identifier is the OID of a published policy. Access to this policy is not specified further. A sample is given in Figure 3.40.4.1.2.2-2.


<saml2:Attribute FriendlyName="Patient Privacy Policy Identifier"
     Name="urn:ihe:iti:xua:2012:acp"
     NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"   xsi:type="xs:anyURI">urn:oid:1.2.3.yyyy</saml2:AttributeValue>
</saml2:Attribute>

Figure 3.40.4.1.2.2-2: Sample attribute holding a reference to a privacy policy

3.40.4.1.2.2.1 Patient Identifier Attribute

This attribute is optional, as it may not be needed for cases in which the data being exchanged does not pertain to a specific patient (e.g., population health data). The value of the Patient Identifier attribute is recommended when the InstanceAccessConsentPolicy attribute is specified in an Authorization Decision Statement.

This <Attribute> element shall have the Name attribute set to: “urn:oasis:names:tc:xacml:2.0:resource:resource-id”

The patient identifier of the requesting organization shall be placed in the value of the <AttributeValue> element. The patient identifier shall consist of two parts; the OID for the assigning authority and the identifier of the patient within that assigning authority. The value shall be formatted using the CX syntax ITI TF-3: Table 4.2.3.1.7-2: Data Types. As an example, a patient identifier of 543797436 for an assigning authority with an OID of 1.2.840.113619.6.197, has been encoded into the following SAML assertion snippet. Please note that the '&' character has been properly encoded in the XML content in the following example.


<saml:Attribute Name="urn:oasis:names:tc:xacml:2.0:resource:resource-id">
  <saml:AttributeValue>543797436^^^&amp;1.2.840.113619.6.197&amp;ISO</saml:AttributeValue>
</saml:Attribute>

3.40.4.1.2.3 PurposeOfUse Option

The PurposeOfUse <Attribute> element shall have the Name attribute set to "urn:oasis:names:tc:xspa:1.0:subject:purposeofuse". The value of the <AttributeValue> element is a child element, “PurposeOfUse”, in the namespace "urn:hl7-org:v3", whose content is defined by the "CE" (coded element) data type from the HL7 version 3 specification.

The PurposeOfUse element shall contain the coded representation of the Purpose for Use that is in effect for the request.

An example of the syntax of this element is as follows:


        <saml:Attribute Name="urn:oasis:names:tc:xspa:1.0:subject:purposeofuse">
          <saml:AttributeValue>
            <PurposeOfUse xmlns="urn:hl7-org:v3" xsi:type="CE" code="12"
                codeSystem="1.0.14265.1"
        codeSystemName="ISO 14265 Classification of Purposes for processing personal health information"
                displayName="Law Enforcement"/>
          </saml:AttributeValue>
        </saml:Attribute>

Codes are assigned by the local Security Domain and a Code-Set needs to be managed. A good source Vocabulary for PurposeOfUse is ISO 14265 – Health Informatics – Classification of purposes for processing personal health information. The Value-Set used may include local codes or codes drawn from formal vocabulary.

The value of the Purpose of Use attribute shall be a "urn:hl7-org:v3:CE" element, specifying the coded value representing the user's purpose in issuing the request, choosing from the value set given by local Policy. The codeSystem attribute of this element must be present, and must specify the OID of the "Purpose of Use" code system.

3.40.4.1.2.3.1 ATNA encoding of PurposeOfUse

When the PurposeOfUse Option is used the X-Service User and X-Service Provider SHALL place the PurposeOfUse value into the ATNA Audit Message associated with the transaction according to the Record Audit Event [ITI-20] transaction (see ITI TF-2: 3.20.7.1.2 ).

3.40.4.1.3 Expected Actions

The X-Service Provider shall validate the Identity Assertion by processing the Web-Services Security header in accordance with the Web-Services Security Standard, and SAML 2.0 Standard processing rules (e.g., check the digital signature is valid and chains to an X-Identity Provider that is configured as trusted). If this validation fails, then the grouped Actor’s associated transaction shall return with an error code as described in WS-Security core specification Section 12 (Error Handling, using the SOAP Fault mechanism), and the ATNA Audit event for Authentication Failure shall be recorded according to ATNA rules.

Any ATNA Audit Messages recorded by actor grouped with the X-Service Provider Actor, shall have the user identity recorded according to the XUA specific ATNA encoding rules (see Section 3.40.4.2 ATNA Audit encoding). For example: The XDS.b Document Consumer performing a Registry Stored Query records the Query event; this event record will include the identity provided in the XUA Identity Assertion. This assures that the X-Service User and X-Service Provider ATNA Audit messages can be correlated at the ATNA Audit Record Repository.

The X-Service Provider may use standards transactions to communicate with the X-Assertion Provider (e.g., WS-Trust, SAML 2.0 Protocol) to obtain information not included in the assertion provided (e.g., Attributes that might be related to structural roles).

The X-Service Provider may utilize the identity in access control decisions. Appropriate error messages, not defined here, shall be returned. The X-Service Provider may ignore any other statements (e.g., Attributes).

The X-Service Provider may use the authentication class references to determine the method that was used to authenticate the user. For example the X-Service Provider may have a configurable list of authentication class references that it is willing to recognize as authentication methods that are acceptable, thus treating other authentication class references as not authorized.

Assertions need to be carefully managed inside the X-Service Provider to ensure they are not exposed in the application code or any subsequent use of the Assertion.

3.40.4.1.3.1 Subject-Role Option

When the Subject-Role Option is used, the X-Service Provider may utilize the Subject-Role values in local policy for access control decision making.

The X-Service Provider may need to bridge the Subject-Role values into local role vocabulary.

The Subject-Role may be used to populate the ATNA Audit Message.

3.40.4.1.3.2 Authz-Consent Option

When the Authz-Consent Option is used, the X-Service Provider may utilize the Authz-Consent values in local policy for access control decision making. The Authz-Consent values are offered by the X-Service User as an indicator of the specific consent or authorization that the X-Service User has determined authorizes the transaction. The values are informative to the X-Service Provider which may choose to ignore the values.

This may require the X-Service Provider to lookup the metadata by reference to the values given, and may require the X-Service Provider to retrieve the consent documents.

The Authz-Consent value may be used to populate the ATNA Audit Message.

3.40.4.1.3.3 PurposeOfUse Option

When the PurposeOfUse Option is used the X-Service Provider SHALL place the PurposeOfUse into the ATNA Audit Message associated with the transaction (see Section 3.40.4.1.2.3.1). This PurposeOfUse in the audit log can be used at the Audit Record Repository to inform reporting such as Accounting of Disclosures or Breach Notifications. The X-Service Provider MAY use the PurposeOfUse value in Access Control decisions.

3.40.4.2 ATNA Audit encoding

When an ATNA Audit message needs to be generated and the user is authenticated by way of an X-User Assertion, the ATNA Audit message UserName element shall record the X-User Assertion using the following encoding:

alias<user@issuer>

where:

alias is the optional string within the SAML Assertion's Subject element SPProvidedID attribute
user is the required content of the SAML Assertion's Subject element
issuer is the X-Assertion Provider entity ID contained with the content of SAML Assertion's Issuer element
The “<” and “>” represent XML control characters

Example: JD<John.Doe@example.com>

3.40.4.3 Informative Material on WS-Trust

If the X-Service Provider uses WS-Trust in order to obtain a SAML assertion from an X-Identity Provider, it is suggested to use the version 1.3 of the WS-Trust specification, as described in [WS-Trust].