Skip to content

Authenticate User

Transaction to authenticate a user at a identity provider certified for the Swiss EPR. Primary systems shall use this transaction to retrieve a IdP assertion. The IdP assertion is required to retrieve the XUA Assertion to be used with EPR transactions.

Overview

Primary systems shall use this transaction to retrieve an IdP assertion authentication the user for the access to the Swiss EPR.

The requirements for the transaction are defined in Annex 8 of the ordinances of the Swiss EPR.

The EPR requires primary systems to implement authentication as described in the SAML 2.0 specification family, i.e.,

Primary systems do need implement all the bindings and profiles supported by the SAML 2.0 specification family.

In the Swiss EPR the following bindings are required:

  • HTTP POST Binding.
  • HTTP Artifact Binding.
  • SAML SOAP Binding.

In the Swiss EPR the following profiles are required:

  • Web Browser SSO Profile.
  • Single Logout Profile.

The usage of the profiles and binding used to authenticate user for the Swiss EPR is described in the following sections.

Transactions

The transaction to authenticate a user for the access to the Swiss EPR is a multi-step flow consisting of HTTP Post and SOAP Web Service calls, as displayed in the following figure:

Authentication Sequence

Figure 1: Authentication Sequence Diagram

The sequence consists of the following steps, each using assigned transaction messages:

  • [01 .. 04] The user (claimant) is redirected to the identity provider via the user agent (browser) with a SAML 2.0 AuthnRequest message.
  • [05] The user (claimant) authenticates at the identity provider with her authentication means.
  • [06 .. 07] The identity provider responds a SAML 2.0 artifact in a HTTP redirect to the primary system (relying party).
  • [08] The primary system sends a ArtifactResolve message to resolve the SAML artifact to the SAML 2 IdP Assertion via the SOAP backchannel.
  • [09] The IdP responds the IdP Assertion in the ArtifactResponse message.

Authentication Request

The transaction shall be performed by the primary system when the user aims to access the EPR. The primary system shall redirect the user agent (browser) to the IdP authentication endpoint with a AuthnRequest message as defined in Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0.

When the user is authenticated by the IdP, the IdP responds with a HTTP redirect to the registered endpoint of the primary system as specified in Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0.

Message Semantics

Request Message

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

The AuthnRequest conveys the following information to be set by the primary system:

  • ID: A unique ID of the request message (line 7 in the example below).
  • Issuer: A ID of the primary system as URL (line 9 in the example below).
  • SignedInfo: Signature metadata and the digest value used for the signature.
  • SignatureValue: The signature of the request (line 23 in the example below).
  • X509Certificate: The X509 certificate used to sign the request (line 26 in the example below).
04_AuthnRequest.xml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
<AuthnRequest
 xmlns="urn:oasis:names:tc:SAML:2.0:protocol"
 AssertionConsumerServiceURL="https://epdtest.mycompany.local:8549/ACS"
 IssueInstant="2020-09-24T13:19:25.208+02:00"
 Destination="https://fed.idp.ch:443/saml/3.0/idp/"
 ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
 ID="SAML-CD88202A-FE57-11EA-800A-ACB5C93CFFF0"
 Version="2.0">
 <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://epdtest.mycompany.local</Issuer>
 <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
  <SignedInfo>
   <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
   <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
   <Reference URI="#SAML-CD88202A-FE57-11EA-800A-ACB5C93CFFF0">
    <Transforms>
     <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
     <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
    </Transforms>
    <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
    <DigestValue>TdN8cZ5mvY7pOsrpOK0h+YlnvlhOOHYecaBN59yH4w0=</DigestValue>
   </Reference>
  </SignedInfo>
  <SignatureValue><!-- omitted for brevity --></SignatureValue>
  <KeyInfo>
   <X509Data>
    <X509Certificate><!-- omitted for brevity --></X509Certificate>
   </X509Data>
  </KeyInfo>
 </Signature>
 <NameIDPolicy Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" AllowCreate="true"/>
</AuthnRequest>
Response Message

The following snippet is taken from a sample request recorded during the EPR projectathon in September 2020. It conveys two parameter to be used by the primary system:

  • SAMLart: The SAML artifact to be used in the ArtifactResolve request (see section below).
  • RelayState: A unique identifier of the conversation, the primary system initially sent with the Authentication Request.
https://epdtest.mycompany.local:8549/ACS?SAMLart=AAQAAOjXNPPr%2Fr7FO5WpiZ%2B2vAl5KMFibkRaAGwIkwXh%2Bo7DgsG2LMDE58c%3D&RelayState=idp%23468

Transport Protocol

The transaction uses front channel HTTP communication via the user agent (browser).

Security Requirements

The transactions shall use TLS secured transports (HTTPS) to ensure data privacy and with server authentication.

Artifact Resolve

The transaction shall be performed by the primary system to exchange the artifact to a SAML 2.0 IdP Assertion.

The primary system shall use the SOAP backchannel with an ArtifactResolve request message as defined in Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0.

The IdP server responds the SAML 2.0 IdP Assertion of the authenticated user.

Message Semantics

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 ArtifactResolve conveys the following information to be set by the primary system:

  • Issuer: A ID of the primary system as URL (line 4 in the example below).
  • SignedInfo: Signature metadata and the digest value used for the signature.
  • SignatureValue: The signature of the request (line 18 in the example below).
  • X509Certificate: The X509 certificate used to sign the request (line 21 in the example below).
  • Artifact: The artifact as retrieved from the Authentication Request transaction (line 25).
08_ArtifactResolve_raw.xml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Body>
   <ArtifactResolve xmlns="urn:oasis:names:tc:SAML:2.0:protocol" ID="SAML-D76F77F0-FE57-11EA-8007-9DB4CDFD82EF" Version="2.0" IssueInstant="2020-09-24T13:19:41.822+02:00" Destination="https://fed.idp.ch/nevisauth/services/artifactresolution">
    <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">https://epdtest.mycompany.local</Issuer>
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
     <SignedInfo>
      <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
      <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
      <Reference URI="#SAML-D76F77F0-FE57-11EA-8007-9DB4CDFD82EF">
       <Transforms>
        <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
        <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
       </Transforms>
       <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
       <DigestValue>R+bMs3semvJBgae/3wnNVZp0eTpIhQQK4+S2KqRj1bM=</DigestValue>
      </Reference>
     </SignedInfo>s
     <SignatureValue> <!-- omitted for brevity --> </SignatureValue>
     <KeyInfo>
      <X509Data>
       <X509Certificate> <!-- omitted for brevity --> </X509Certificate>
      </X509Data>
     </KeyInfo>
    </Signature>
    <Artifact>AAQAAOjXNPPr/r7FO5WpiZ+2vAl5KMFibkRaAGwIkwXh+o7DgsG2LMDE58c=</Artifact>
   </ArtifactResolve>
  </Body>
 </Envelope>
Response Message

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

The ArtifactResponse conveys the following information which shall be evaluated by the primary system:

  • Issuer: A ID of the primary system as URL (line 6 in the example below).
  • SignedInfo: Signature metadata and the digest value used for the signature.
  • SignatureValue: The signature of the request (line 26 in the example below) which shall be validated by the primary system.
  • X509Certificate: The X509 certificate used to sign the request (line 29 in the example below).
  • assertion: The IdP assertion conveying the attributes of the authenticated user.
09_ArtifactResponse_raw.xml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Body>
    <saml2p:ArtifactResponse
      xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
      xmlns:xs="http://www.w3.org/2001/XMLSchema"
      ID="ArtifactResponse_bf738b81c935d2c2f47604e01388553c2407ac40"
      InResponseTo="SAML-D76F77F0-FE57-11EA-8007-9DB4CDFD82EF"
      IssueInstant="2020-09-24T11:19:42.030Z"
      Version="2.0">
      <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">fed.idp.ch</saml2:Issuer>
      <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
          <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
          <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
          <ds:Reference URI="#ArtifactResponse_bf738b81c935d2c2f47604e01388553c2407ac40">
            <ds:Transforms>
              <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
              <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
                <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="xs"/>
              </ds:Transform>
            </ds:Transforms>
            <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
            <ds:DigestValue>1RZPbh508clAQoKhxnQZEenNFyg=</ds:DigestValue>
          </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue><!-- omitted for brevity --></ds:SignatureValue>
        <ds:KeyInfo>
          <ds:X509Data>
            <ds:X509SKI>gYMVdgdR5LG/983GRTJIch0a+zU=</ds:X509SKI>
          </ds:X509Data>
        </ds:KeyInfo>
      </ds:Signature>
      <saml2p:Status>
        <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
      </saml2p:Status>
      <saml2p:Response
        xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
        Destination="https://epdtest.mycompany.com"
        ID="Response_ef5597568f1bc48233cac63c5a51ca3026566d59"
        InResponseTo="SAML-CD88202A-FE57-11EA-800A-ACB5C93CFFF0"
        IssueInstant="2020-09-24T11:19:41.634Z"
        Version="2.0">
        <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">fed.idp.ch</saml2:Issuer>
        <saml2p:Status>
          <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
        </saml2p:Status>
        <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="Assertion_4f962f0ff6d14c9ea77726da3c2c88bb76fcae67" IssueInstant="2020-09-24T11:19:41.633Z" Version="2.0">

The following snippet shows an example of a IdP Assertion conveyed with the response.

The primary system must keep the IdP Assertion in memory to use it to authenticate the Get X-User Assertion transaction.

The primary system is not required to analyze the IdP Assertion further, but may extract the following information from the assertion:

  • NameID : This element conveys the user ID assigned by IdP. Primary systems may use it to locally authenticate the user in the primary system.
  • NotBefore and NotOnOrAfter: The lifetime of the IdP assertion.
  • AttributeStatement: IdP shall provide user attributes in the AttributeStatement child elements. At least the givenname, surname, gender and dateofbirth must be provided. Optional fileds may be provided. The optional fields cover the GLN of the healthcare professional and other attributes, the primary system may use internally to identify the authenticated user.
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
        <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="Assertion_4f962f0ff6d14c9ea77726da3c2c88bb76fcae67" IssueInstant="2020-09-24T11:19:41.633Z" Version="2.0">
          <saml2:Issuer>fed.idp.ch</saml2:Issuer>
          <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <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="#Assertion_4f962f0ff6d14c9ea77726da3c2c88bb76fcae67">
                <ds:Transforms>
                  <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                  <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
                    <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="xs"/>
                  </ds:Transform>
                </ds:Transforms>
                <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                <ds:DigestValue>P/I9Ym+p/Zzs0ANXHmAjqZcuBp2FJ75j6oCM6Gd0bVg=</ds:DigestValue>
              </ds:Reference>
            </ds:SignedInfo>
            <ds:SignatureValue><!-- omitted for brevity --></ds:SignatureValue>
            <ds:KeyInfo>
              <ds:X509Data>
                <ds:X509Certificate><!-- omitted for brevity --></ds:X509Certificate>
              </ds:X509Data>
            </ds:KeyInfo>
          </ds:Signature>
          <saml2:Subject>
            <saml2:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">pjtt31</saml2:NameID>
            <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
              <saml2:SubjectConfirmationData InResponseTo="SAML-CD88202A-FE57-11EA-800A-ACB5C93CFFF0" NotOnOrAfter="2020-09-24T12:19:41.634Z" Recipient="https://epdtest.mycompany.com"/>
            </saml2:SubjectConfirmation>
          </saml2:Subject>
          <saml2:Conditions NotBefore="2020-09-24T11:19:41.633Z" NotOnOrAfter="2020-09-24T12:09:41.633Z">
            <saml2:AudienceRestriction>
              <saml2:Audience>https://epdtest.mycompany.com</saml2:Audience>
            </saml2:AudienceRestriction>
          </saml2:Conditions>
          <saml2:AuthnStatement AuthnInstant="2020-09-24T11:19:41.633Z" SessionNotOnOrAfter="2020-09-24T13:19:41.633Z">
            <saml2:AuthnContext>
              <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml2:AuthnContextClassRef>
            </saml2:AuthnContext>
          </saml2:AuthnStatement>
          <saml2:AttributeStatement>
            <!-- other vendor specific attributes omitted for brevity -->
            <saml2:Attribute Name="GLN" NameFormat="urn:oasis:names:tc:ebcore:partyid-type:DataUniversalNumberingSystem:0060">
             <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:token">9801000050702</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
              <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Martina</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
              <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Musterarzt</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="gender" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
              <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:token">F</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="dateofbirth" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
              <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:date">1990-09-06</saml2:AttributeValue>
            </saml2:Attribute>
          </saml2:AttributeStatement>
        </saml2:Assertion>

Transport Protocol

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

1
2
3
4
5
6
POST /IdPAuthenticationService HTTP/1.1
Host: idp.example.org
Accept-Encoding: gzip, deflate
Connection: Keep-Alive
Content-Type: application/soap+xml; charset="utf-8"
Content-Length: nnnn

Security Requirements

The Artifact Resolve transaction shall be secured by using the SOAP backchannel with TLS and mutual authentication with client and server certificate validation. The certificates shall be exchanged during the client registration process.

Audit Log

Primary systems shall protocol the transaction in their logs to ensure traceability. No further requirements are defined in the ordinances of the Swiss EPR.

Test Opportunity

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

Last update: 2024-08-09