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, later updated to the new specifications. Some elements (like the XML Namespace declarations) 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 normal access. For other roles and situations the claims are different. Other examples may be found at XUA examples.

The request message shall be an 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.

SOAP header
<soap:Envelope>
  <soap:Header>
    <wsa:Action>http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue</wsa:Action>
    <wsa:MessageID>urn:uuid:005300f3-c686-4960-8ae8-f8c1720eda41</wsa:MessageID>
    <wsse:Security>

The Security element SHALL contain a Security Timestamp, limiting the validity of the current request to defined bounds. The Timestamp element SHALL have an Id attribute that will be later referenced in the request Signature.

Security Timestamp
      <wsu:Timestamp wsu:Id="timestamp-id">
        <wsu:Created>2026-07-22T11:57:42.052520800Z</wsu:Created>
        <wsu:Expires>2026-07-22T12:02:42.052520800Z</wsu:Expires>
      </wsu:Timestamp>

The Security element SHALL also contain a Binary Security Token, containing the X.509 Certificate that will sign this request.

Binary Security Token
      <wsse:BinarySecurityToken EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3">
        MIIF3TCCA8WgAwIBAgICAlgwDQYJKoZIhvcNAQELBQAwTjELMAkGA1UEBhMCQ0gxDTALBgNVBAgMBEJlcm4xDTALBgNVBAcMBEJlcm4xDjAMBgNV[…]
      </wsse:BinarySecurityToken>

The Security element SHALL contain the IdP Assertion taken from user authentication (see Authenticate User).

IdP Assertion
      <saml2:Assertion ID="Assertion_dbce1232740fcad9e020f927fd25a5d04779b4cc" IssueInstant="2020-09-21T13:38:43.857Z" Version="2.0">
        <!-- IdP Assertion omitted -->
      </saml2:Assertion>

The Security element SHALL finally contain an XML Signature referencing both the Security Timestamp and the SOAP Body. It SHALL specify a X509IssuerSerial containing the issuer name and serial number of the X.509 Certificate used for signing the request.

XML Signature
      <ds:Signature>
        <ds:SignedInfo>
          <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
          <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
          <ds:Reference URI="#timestamp-id">
            <ds:Transforms>
              <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            </ds:Transforms>
            <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
            <ds:DigestValue>GC+zUmb76mHBDlrkTK/SGyx7MOCQMKx8AoDGDBdIExk=</ds:DigestValue>
          </ds:Reference>
          <ds:Reference URI="#body-id">
            <ds:Transforms>
              <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            </ds:Transforms>
            <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
            <ds:DigestValue>KNXv6+h9kd5rhupXhFxUbtUDiSwwUsg1M9til9dCGm0=</ds:DigestValue>
          </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>[…]</ds:SignatureValue>
        <ds:KeyInfo>
          <wsse:SecurityTokenReference>
            <ds:X509Data>
              <ds:X509IssuerSerial>
                <ds:X509IssuerName>CN=XYZ_CA,O=Organization,L=Bern,ST=Bern,C=CH</ds:X509IssuerName>
                <ds:X509SerialNumber>1234</ds:X509SerialNumber>
              </ds:X509IssuerSerial>
            </ds:X509Data>
          </wsse:SecurityTokenReference>
        </ds:KeyInfo>
      </ds:Signature>
    </wsse:Security>
  </soap:Header>

The SOAP Body element SHALL have an Id attribute referenced by the XML Signature, and SHALL contain the RequestSecurityToken element with the following claims to be set by the primary system.

SOAP Body and RequestSecurityToken
  <soap:Body wsu:Id="body-id">
    <wst:RequestSecurityToken>
      <wst:Claims Dialect="http://www.bag.admin.ch/epr/2017/annex/5/amendment/2">

The attribute resourceID conveys the EPR-SPID of the patient EPR to access in HL7 V2.5 CX format (see PIXFeed)

        <saml2:Attribute Name="urn:oasis:names:tc:xacml:2.0:resource:resource-id">
          <saml2:AttributeValue xsi:type="xsd:token">
            761337610411353650^^^&amp;2.16.756.5.30.1.127.3.10.3&amp;ISO
          </saml2:AttributeValue>
        </saml2:Attribute>

The 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 record.

        <saml2:Attribute Name="urn:oasis:names:tc:xspa:1.0:subject:purposeofuse">
          <saml2:AttributeValue xsi:type="xsd:anyType">
            <hl7v3:PurposeOfUse 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>

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

        <saml2:Attribute Name="urn:oasis:names:tc:xacml:2.0:subject:role">
          <saml2:AttributeValue xsi:type="xsd:anyType">
            <hl7v3:Role 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>
      </wst:Claims>
      <wst:TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</wst:TokenType>
      <wst:RequestType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue</wst:RequestType>
    </wst:RequestSecurityToken>
  </soap:Body>
</soap:Envelope>

Response Message ¶

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

The response message is an XML SOAP envelope with the XUA Assertion embedded in 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: 2026-07-25