Get X-User Assertion ¶

Transaction to retrieve a SAML 2.0 assertion for authorization of transactions in the Swiss EPR. Primary systems shall use this transaction to retrieve a SAML 2 assertions to be used with EPR transactions, which require authorization.

Overview ¶

Primary systems shall use this transaction to retrieve a SAML 2 assertions to be used with the Provide X-User Assertion with XDS.b transactions as defined in the IHE XUA profile with Swiss specific extensions defined in
Amendment 1 to Annex 5.

The primary system shall provide claims (e.g., user role, purpose of use) with the request as defined in Amendment 1 to Annex 5.

The community verifies the claims and responds with a XUA compliant SAML 2.0 Assertion defined in Amendment 1 to Annex 5.

Transaction ¶

Message Semantics ¶

Messages are encoded as described in the WS Trust standard, with restrictions defined in the IHE profile and the ordinances to the Swiss EPR.

Request Message ¶

The following snippet is taken from a sample request recorded during the EPR projectathon in September 2020. Some elements are omitted to increase readability. The raw request file may be found here.

The snippet shows a request performed by a healthcare professional performing a the normal access. For other roles and situations the claims are different. Other examples may be found at XUA examples.

The request message shall be a XML SOAP envelope with the query embedded in the Body element of the SOAP envelope. The SOAP Header element conveys the following information:

MessageID element: a UUID of the message.
Action element: The SOAP action identifier of the query as defined in the IHE ITI Technical Framework.
Security element: The Web Service Security header as defined in the WS Security specification. This element must contain the IdP Assertion taken from user authentication (see Authenticate User).

SOAP header
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
 <env:Header>
  <wsa:Action xmlns:wsa="http://www.w3.org/2005/08/addressing">http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue</wsa:Action>
  <wsa:MessageID xmlns:wsa="http://www.w3.org/2005/08/addressing">urn:uuid:005300f3-c686-4960-8ae8-f8c1720eda41</wsa:MessageID>
  <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
   <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="Assertion_dbce1232740fcad9e020f927fd25a5d04779b4cc" IssueInstant="2020-09-21T13:38:43.857Z" Version="2.0">
   <!-- IdP Assertion omitted -->
   </saml2:Assertion>
  </wsse:Security>
 </env:Header>

The SOAP Body element contains the RequestSecurityToken element with the following claims to be set by the primary system. It's child element read:

AppliesTo the URL of the community endpoint the XUA assertion shall be used for authorization, whose value is set in the Address child element.

   <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
    <wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
     <wsa:Address>https://sp.communilty.ch</wsa:Address>
    </wsa:EndpointReference>
   </wsp:AppliesTo>

resourceID conveying the EPR-SPID of the patient EPR to access in CX format (see see PIXFeed)

    <saml2:Attribute xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" Name="urn:oasis:names:tc:xacml:2.0:resource:resource-id">
     <saml2:AttributeValue xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:token">761337610411353650^^^&amp;2.16.756.5.30.1.127.3.10.3&amp;ISO</saml2:AttributeValue>
    </saml2:Attribute>

purposeOfUse conveying the purpose of use of the request, which must be taken from the EPR value set defined in Annex 3 of the ordinances of the Swiss electronic patient dossier.

    <saml2:Attribute xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" Name="urn:oasis:names:tc:xspa:1.0:subject:purposeofuse">
     <saml2:AttributeValue xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:anyType">
      <PurposeOfUse xmlns="urn:hl7-org:v3" code="NORM" codeSystem="2.16.756.5.30.1.127.3.10.5" codeSystemName="eHealth Suisse Verwendungszweck" displayName="Normalzugriff" xsi:type="CE"/>
     </saml2:AttributeValue>
    </saml2:Attribute>

role conveying the EPR role of the user, which must be taken from the EPR value set defined in Annex 3.

    <saml2:Attribute xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" Name="urn:oasis:names:tc:xacml:2.0:subject:role">
     <saml2:AttributeValue xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:anyType">
      <Role xmlns="urn:hl7-org:v3" code="HCP" codeSystem="2.16.756.5.30.1.127.3.10.6" codeSystemName="eHealth Suisse EPR Akteure" displayName="Behandelnde(r)" xsi:type="CE"/>
     </saml2:AttributeValue>
    </saml2:Attribute>

Response Message ¶

The following snippet is taken from a sample response recorded during the EPR projectathon in September 2020. Some elements were ommitted to increase readability. The raw file may be found here.

The response message is a XML SOAP envelope with the XUA Assertion embedded in the the Body element of the SOAP envelope (see example below, lines 21 to 23). Primary systems shall extract the XUA Assertion to use the im the security header of the XDS.b transactions, which require authorization. For primary systems, there is no need to extract information from the XUA assertion.

The XUA Assertion is omitted in the snippet below. For examples of see here.

GetXAssertion_response.xml
<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
 <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
  <wsa:Action>http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTRC/IssueFinal</wsa:Action>
  <wsa:RelatesTo>urn:uuid:005300f3-c686-4960-8ae8-f8c1720eda41</wsa:RelatesTo>
 </soapenv:Header>
 <soapenv:Body>
  <wst:RequestSecurityTokenResponseCollection xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
   <wst:RequestSecurityTokenResponse>
    <wst:TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</wst:TokenType>
    <wst:Lifetime>
     <wsu:Created xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">2020-09-21T13:39:23.200Z</wsu:Created>
     <wsu:Expires xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">2020-09-21T13:54:23.200Z</wsu:Expires>
    </wst:Lifetime>
    <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
     <wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
      <wsa:Address>https://sp.communilty.ch</wsa:Address>
     </wsa:EndpointReference>
    </wsp:AppliesTo>
    <wst:RequestedSecurityToken>
     <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xsd="http://www.w3.org/2001/XMLSchema" ID="_96189571-c72c-4a10-8f1c-6d5b27efa797" IssueInstant="2020-09-21T13:39:23.200Z" Version="2.0">
      <!-- assertion omitted for brevity -->
     </saml2:Assertion>
    </wst:RequestedSecurityToken>
    <wst:RequestedAttachedReference>
     <wsse:SecurityTokenReference xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <wsse:Reference URI="_96189571-c72c-4a10-8f1c-6d5b27efa797" ValueType="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0"/>
     </wsse:SecurityTokenReference>
    </wst:RequestedAttachedReference>
   </wst:RequestSecurityTokenResponse>
  </wst:RequestSecurityTokenResponseCollection>
 </soapenv:Body>
</soapenv:Envelope>

Transport Protocol ¶

The primary system shall send the request messages to the X-Assertion Provider of the community using the http POST binding as defined in the W3C SOAP specification. It may look like:

POST /RegistryStoredQueryService HTTP/1.1
Host: company.example.org
Accept-Encoding: gzip, deflate
Connection: Keep-Alive
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn  

Audit Log ¶

Primary systems shall protocol the request and response for traceability. There are no further requirements on protocols defined in the ordinances of the Swiss EPR.

Security Requirements ¶

To ensure privacy the transaction must be secured using https with mutual authentication, using X.509 certificates (extended validation required) and client and server side certificate validation.

The retrieval of a XUA assertion requires user authentication by providing the IdP assertion in the Security header of the SOAP envelope (see Message Semantics). The IdP assertion shall be retrieved by the primary system by using the Authenticate User transaction.

Test Opportunity ¶

The transaction can be tested with the test suite of the EPR reference environment or the test systems of the EPR communities.

Last update: 2025-01-27