Digital Health Denmark
OIOIDWS for Healthcare Token Profile
for Authentication Tokens
Content
Document History ...3
Introduction ...4
Notation ... 5
Related Profiles ... 5
Authentication Token Requirements ...5
Authentication Token Processing... 6
Authentication Token Attributes... 7
WS-‐Trust Binding...8
Examples...9
Authentication Token (non-‐normative)... 9
Profile and architectural decisions...12
Allowed credential types... 12
Protocol binding... 12
Authentication token format ... 13
Claims in RequestSecurityToken messages ... 13
References ...15
Document History
Date Version Initials Changes
01-‐09-‐2009 0.9 KKJ, BVT Initial version
08-‐02-‐2010 1.0 KKJ Internal release
Introduction
This document describes the requirements for authentication tokens used in the Danish health sector federation of services.
Figure 1: End user authenticates to IdP via WSC
An authentication token is used by a Web Service Client (WSC) to convey to an Identity Provider (IdP) proof of identity on behalf of a user or system. In particular:
A WSC that needs to invoke a web service in the federation must first authenticate with an IdP. A successful authentication results in the issuance of an OIOIDWS bootstrap token signed by the IdP [OIOBOOT]. The authentication token used in the web services scenarios in the Danish health sector is a special SAML 2.0 token. This profile mandates the use of OCES digital signatures for authentication, and does not allow other credential types.
Prior to authentication, the WSC will generate the authentication token (a SAML 2.0 assertion) and have it signed by the end user (step 1 on Figure 1). Next, the WSC will embed the authentication token in a WS-‐ Trust RequestSecurityToken message and send it to the IdP for authentication (step 2 on Figure 1). Bootstrap tokens are similarly returned from the IdP to the WSC via a WS-‐Trust
RequestSecurityTokenResponse (step 3 on Figure 1).
Disclaimer: Authentication tokens are not profiled in OIOIDWS, and hence the authentication mechanism described in this document is proprietary to OIOIDWS for Healthcare. The result of authentication, the bootstrap token, however, is not proprietary to OIOIDWS for Healthcare, and it is intended that this token can be used in the context of other non-‐healthcare OIOIDWS compliant services.
Notation
Namespaces are abbreviated to commonly used monikers. The table below expands the namespaces in use by this profile to their respective URNs:
Moniker Namespace ds http://www.w3.org/2000/09/xmldsig# saml2 urn:oasis:names:tc:SAML:2.0:assertion soap http://schemas.xmlsoap.org/soap/envelope/ wsa http://www.w3.org/2005/08/addressing wsp http://schemas.xmlsoap.org/ws/2004/09/policy wst http://docs.oasis-‐open.org/ws-‐sx/ws-‐trust/200512
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" used in this document must be interpreted according to [RFC2119].
Related Profiles
The reader is assumed to be familiar with OIOIDWS for Healthcare, OIOIDWS in general and the following sub-‐profiles in particular:
• The OIO Bootstrap Token Profile [OIO-‐BOOT] describes the requirements for bootstrap tokens issued by an IdP after successful authentication.
• The OIO WS-‐Trust Profile [OIO-‐WST] describes the WS-‐Trust binding for security tokens in context of OIOIDWS and hence OIOIDWS for Healthcare.
Authentication Token Requirements
OIOIDWS for Healthcare Authentication Tokens are SAML 2.0 assertions conforming to the requirements for OIOSAML assertions for web SSO as defined in [OIO-‐SAML-‐SSO] chapters 7-‐9 unless explicitly stated otherwise below:
• The token MUST use holder-‐of-‐key semantics and be signed by the person on whose behalf the WSC attempts to obtain an authentication token.
• The <saml2:Conditions> element MUST include one <saml2:AudienceRestriction> with the entity ID of the IdP that will perform the authentication.
• The bootstrap token MUST not be encrypted (saml2:EncryptedAssertion) or contain encrypted identifiers.
• <saml2:AuthnStatement> MAY be present.
• The <saml2:AttributeStatement> MUST conform to the OCES attribute profile or the persistent pseudonym profile described in [OIO-‐SAML-‐SSO].
• The authentication token SHOULD NOT include private attributes (defined in a separate namespace). Any extra attributes sent by the WSC to the IdP may be ignored.
• The life-‐time of the authentication token SHOULD BE 5 minutes from the time of issuance as defined in the saml2:Assertion@IssueInstant attribute. Please see the discussion on time synchronization in [OIOIDWSH-‐MAIN]
• The certificate of the signing party MUST be included in the <ds:Signature> element of the <saml2:Assertion>.
Authentication Token Processing
An IdP that receives an Authentication token MUST perform at least the following validation steps: • Validate the XML for wellformedness and schema validity.
• Check that it is listed in the <saml2:AudienceRestriction> element. • Verify the signature over the <saml2:Assertion> element:
o Check that the embedded certificate has not expired
o Check that the embedded certificate has not been revoked through [OCSP] lookup or [CRL] check.
o Check that the embedded certificate is issued by the OCES certificate authority (CA) ie. that the entire certificate chain of trust is intact.
o Compute the signature digest over the <saml2:Assertion> o Decrypt the signature element
o Check that the signature digest and the decrypted signature element match.
• Validate that the supplied identity is allowed to access services in the health sector. Users that identify themselves with a valid MOCES signature may e.g. be checked via CVR-‐RID to CPR lookup followed by a check that the CPR does indeed represent a health professional.
• Validate the holder-‐of-‐key relation between the WS-‐Trust request and the contained Authentication Token.
Authentication Token Attributes
The authentication token needs to convey the identity of a health professional using a digital signature created via MOCES. Information about name and organization is already in the certificate, but these values may be overridden by also specifying such information in assertions.
Some attributes including organizational unit and it-‐system-‐name cannot be determined or validated by the IdP and must hence be provided by the WSC. The IdP has no other choice but to trust these elements and will faithfully copy them to bootstrap tokens. These attributes will later be copied to Identity Tokens via token exchange at an STS and finally be consumed by a WSP who should be aware of the fact that these attributes have not been validated and must decide whether or not to trust the WSC to supply such data. Please refer to [OIOIDWSH-‐MAIN] for details on how a WSP can determine whether or not an attribute has been verified by the IdP.
Please note that the end user’s certificate must always be present, but values taken from it (e.g. surname, CommonName, etc.) are optional. The IdP must ensure that when specified, attributes that originate from the end user certificate must match those in the supplied certificate (userCertificate attribute).
Authentication tokens leverages attributes specified in [OIO-‐SAML-‐SSO] as summarized in the table below:
Name Friendly Name Category Mandatory?
urn:oid:2.5.4.4 surname CORE No
urn:oid:2.5.4.3 CommonName CORE No
urn:oid:0.9.2342.19200300.100.1.1 Uid CORE No
urn:oid:0.9.2342.19200300.100.1.3 Email CORE No
dk:gov:saml:attribute:AssuranceLevel CORE Yes
dk:gov:saml:attribute:SpecVer CORE Yes
dk:gov:saml:attribute:CvrNumberIdentifier CORE No
dk:gov:saml:attribute:UniqueAccountKey CORE No
urn:liberty:disco:2006-‐08:DiscoveryEPR CORE No
urn:oid:2.5.4.5 serialNumber OCES No
urn:oid:2.5.4.10 organizationName OCES No
urn:oid:2.5.4.11 organizationUnit OCES No
urn:oid:2.5.4.12 Title OCES No
dk:gov:saml:attribute:IsYouthCert OCES No
urn:oid:1.3.6.1.4.1.1466.115.121.1.8 userCertificate OCES Yes
dk:gov:saml:attribute:PidNumberIdentifier OCES No
dk:gov:saml:attribute:CprNumberIdentifier OCES No
dk:gov:saml:attribute:RidNumberIdentifier OCES No
dk:healthcare:saml:attribute:UserAuthorizationCode UserAuthorizationCode HEALTH No
dk:healthcare:saml:attribute:ITSystemName ITSystemName HEALTH Yes
dk:healthcare:saml:attribute:UserEducationCode UserEducationCode HEALTH No dk:healthcare:saml:attribute:UserEducationType UserEducationType HEALTH No
The CORE and OCES categories of attributes are defined in detail in [OIO-‐SAML-‐SSO] and the HEALTH category is defined in detail in [OIOIDWSH-‐ID].
WS-Trust Binding
A WSC communicates with the IdP using the WS-‐Trust messages RequestSecurityToken and
RequestSecurityTokenResponse [OIO-‐WST]. An authentication token is added to the SOAP header of the message carrying the RequestSecurityToken element in the <soap:Body> part. Before sending the message to the IdP, the WSC signs the <soap:Body>, the <saml2:Assertion>, and various other headers with its VOCES certificate.
OIOIDWS for Healthcare complies with [OIO-‐WST] and [OIO-‐WSTDP] with the following clarifications: • A WSC MAY add claims to the RequestSecurityToken message, but cannot expect these to be
processed by the IdP. Please see the architectural issues section for a discussion of this decision and [OIO-‐WST] p. 13.
• OIOIDWS for Healthcare bootstrap tokens SHOULD currently only be obtained via an external Identity Provider, and not via an STS local to the WSC’s organization (see [OIO-‐WSTDP] p.5). • When a service is requesting a token on behalf of a user, an <wst:ActAs> element defined in WS-‐
Trust 1.4 MUST be present and include an authentication token representing the user. The token SHOULD be embedded directly and thus not be a token reference. (see [OIO-‐WST] p. 6).
• The <wsp:AppliesTo> element SHOULD contain an <wsa:EndpointReference> identifying the STS for which the bootstrap token should be issued. (see [OIO-‐WST] p. 6).
Figure 2 below illustrates the request-‐response pattern for WS-‐Trust messages in the context of OIOIDWS for Healthcare. The notation of figure 2 is described in [OIOIDWSH-‐MAIN]:
Figure 2: Requesting a bootstrap token with an authentication token via WS-‐Trust
Please notice how the SAML tokens of both messages are carried in the <soap:Body> part of the message and not in the headers as could be expected. For details of the binding, please refer to [OIO-‐WST].
Examples
Please refer to [OIO-‐WST] p. 8 and p. 10 for examples on RequestSecurityToken and RequestSecurityTokenResponse messages.
Authentication Token (non-normative)
The example below shows a minimal authentication token issued by a WSC (http://someWSC.dk) on behalf of a user who is represented by a MOCES signature.
<!-- Token compliant with OIODWS for Healthcare SAML Profile for Authentication Tokens -->
<saml:Assertion ID="_660c60a3-c490-49a4-813d-eb527e186ff5" IssueInstant="2009-12-31T12:00:00Z"
Version="2.0" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<!-- Identification of the WSC that has issued this authentication token -->
<saml:Issuer>http://SomeWSC.dk</saml:Issuer>
<!-- A signature created with the user's MOCES certificate over the entire assertion -->
<ds:Signature>
<ds:SignedInfo>
<ds:Reference URI="#_660c60a3-c490-49a4-813d-eb527e186ff5">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#envelopedsignature"/>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<ds:DigestValue>TCDVSuG6grhyHbzhQFWFzGrxIPE=</ds:DigestValue>
</ds:Reference> </ds:SignedInfo> <ds:SignatureValue>x/GyPbzmFEe85pGD3c1aXG4Vspb9V9jGCjwcRCKrtwPS6vdVNCcY5rHaFPYWkf+5 EIYcPzx+pX1h43SmwviCqXRjRtMANWbHLhWAptaK1ywS7gFgsD01qjyen3CP+m3D w6vKhaqledl0BYyrIzb4KkHO4ahNyBVXbJwqv5pUaE4=</ds:SignatureValue> <ds:KeyInfo> <ds:X509Data>
<!-- The end-user's MOCES certificate -->
<ds:X509Certificate> MIICyjCCAjOgAwIBAgICAnUwDQYJKoZIhvcNAQEEBQAwgakxCzAJBgNVBAYTAlVT MRIwEAYDVQQIEwlXaXNjb25zaW4xEDAOBgNVBAcTB01hZGlzb24xIDAeBgNVBAoT F1VuaXZlcnNpdHkgb2YgV2lzY29uc2luMSswKQYDVQQLEyJEaXZpc2l... </ds:X509Certificate> </ds:X509Data> </ds:KeyInfo> </ds:Signature>
<!-- This section identifies the web service client (WSC) on whose behalf this identity token was issued. Identification is by means of the WSC's certificate -->
<saml:Subject>
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName"> C=DK,O=Ingen organisatorisk tilknytning,CN=Hans Hansen,Serial=CVR:1234-RID:1234 </saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:holder-of-key">
<!-- Here comes a NameID indicating the ID of the sender (WSC) who must confirm with a key -->
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:entity"> https://SomeWSC.dk
</saml:NameID>
<saml:SubjectConfirmationData xsi:type="saml:KeyInfoConfirmationDataType"
NotOnOrAfter="2009-12-31T12:00:00">
<ds:KeyInfo>
<ds:X509Data>
<!-- Here comes the WSC's X.509 cert (VOCES) -->
<ds:X509Certificate> MIICyjCCAjOgAwIBA.... </ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</saml:SubjectConfirmationData>
</saml:SubjectConfirmation>
</saml:Subject>
<!-- How and when did the End-user authenticate -->
<saml:AuthnStatement AuthnInstant="2009-01-31T12:00:00Z"> <saml:AuthnContext> <saml:AuthnContextClassRef> urn:oasis:names:tc:SAML:2.0:ac:classes:X509 </saml:AuthnContextClassRef> </saml:AuthnContext> </saml:AuthnStatement> <saml:AttributeStatement>
<!-- *** Core attributes which must always be part of an authentication token *** -->
<!-- Sur Name Core Attribute -->
<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
Name="urn:oid:2.5.4.4" FriendlyName="surName">
<saml:AttributeValue xsi:type="xs:string">Jensen</saml:AttributeValue>
</saml:Attribute>
<!-- Common Name Core Attribute -->
<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
<saml:AttributeValue xsi:type="xs:string">Hans Jensen</saml:AttributeValue>
</saml:Attribute>
<!-- Uid Core Attribute this is the Subject Serial Number -->
<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
Name="urn:oid:0.9.2342.19200300.100.1.1">
<saml:AttributeValue xsi:type="xs:string">CVR:20688092-RID:1234</saml:AttributeValue>
</saml:Attribute>
<!-- Email Core Attribute -->
<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
Name="urn:oid:0.9.2342.19200300.100.1.3" FriendlyName="email">
<saml:AttributeValue xsi:type="xs:string">jens@email.dk</saml:AttributeValue>
</saml:Attribute>
<!-- SpecVer Core Attribute -->
<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
Name="dk:gov:saml:attribute:SpecVer">
<saml:AttributeValue xsi:type="xs:string">DK-SAML-2.0</saml:AttributeValue>
</saml:Attribute>
<!-- Assurance Level Core Attribute -->
<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
Name="dk:gov:saml:attribute:AssuranceLevel">
<saml:AttributeValue xsi:type="xs:string">3</saml:AttributeValue>
</saml:Attribute>
<!--- CVR Number Core Attribute -->
<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
Name="dk:gov:saml:attribute:CvrNumberIdentifier">
<saml:AttributeValue xsi:type="xs:string">20688092</saml:AttributeValue>
</saml:Attribute>
<!--- IT-System Name Attribute -->
<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
Name="dk:healthcare:saml:attribute:ITSystemName" FriendlyName="ITSystemName">
<saml:AttributeValue xsi:type="xs:string">SuperCare</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement> </saml:Assertion>
Profile and architectural decisions
Allowed credential types
Architectural Decision
Support digital signatures
Issue or Problem Statement
There is a multitude of credential types that could be used for authenticating a user, including symmetric keys, digital signatures, usernames and password, pin codes, and more. Not all credentials are of equal strength (level of authentication) and as the Danish health sector needs a high degree of confidence in the authenticity of the requester, many are not relevant. It must be determined which one(s) will at least be supported.
Possible solutions
1. Support digital signatures. 2. Support username / password. 3. Support pin-code or symmetric keys Architectural
Decision (detailed)
Use digital X.509 certificates – in particular OCES – for authentication.
Assumptions Motivation for decision
Currently digital signatures are the strongest credentials available to the health sector, and sufficient for the level of authenticity required to communicate patient information. Additionally, OIOIDWS uses OCES certificates for authentication in the public sector in general and the health sector can thus leverage existing infrastructure. Usernames and passwords, pin-codes and symmetric keys all require an a priori exchange and a registry to be kept with the authenticating party, which is not desirable as it puts additional burden on this party. Additionally usernames and pin-codes are not strong enough to be used when communicating patient information.
Implications Derived requirements Related Decisions
Protocol binding
Architectural DecisionUse WS-Trust which is also used for obtaining an identity token with an STS
Issue or Problem Statement
OIOIDWS doesn’t specify how authentication tokens are sent to the IdP, but does define a web based mechanism by which a bootstrap token ends up at a WSP. There is therefore a need to specify:
a) How authentication tokens are sent from WSC to IdP and b) How bootstrap tokens are sent from IdP to WSC.
Possible solutions
1. Use WS-Trust which is also used for obtaining an identity token with an STS 2. Use SAML AuthenticationRequest and AuthenticationResponse messages 3. Use some other means
Architectural Decision (detailed)
A WSC uses the WS-Trust RequestSecurityToken to send a SAML 2.0 authentication token to an IdP and receives a bootstrap token from the IdP via a
Assumptions Motivation for decision
WS-Trust is already used in the communication between a WSC and an STS in order to exchange a bootstrap token for an identity token. WSCs will therefore readily have the ability to communicate via WS-Trust, and since IdP and STS will likely be co-located, the IdP will also be able to receive WS-Trust messages.
Implications Derived requirements Related Decisions
Authentication token format
Architectural Decision
Use SAML 2.0 assertions signed by the end-user / WSC
Issue or Problem Statement
Rich clients that need to invoke a web service will not have retrieved a bootstrap token via web SSO as assumed by the OIO profiles and can generally not use the same protocol to obtain one. It is therefore necessary to define a token, which can be used in place of the web based signon-mechanism.
Possible solutions
4. Use SAML 2.0 assertions signed by the end-user / WSC 5. Use some other token mechanism e.g. Kerberos. Architectural
Decision (detailed)
A WSC creates a SAML 2.0 assertion, signs it and sends it to the IdP for authentication.
Assumptions Motivation for decision
SAML 2.0 assertions are used both for bootstrap tokens and for identity tokens. Using SAML 2.0 assertions for authentication tokens as well will therefore be unproblematic for all involved parties as they must already be able to create and / or process these credentials.
Implications The WSC must be able to create SAML 2.0 assertions and the IdP must be able to consume them. Derived requirements Related Decisions
Claims in RequestSecurityToken messages
Architectural Decision
Have the IdP ignore claims altogether
Issue or Problem Statement
WS-Trust allows a requester – in this case the WSC – to add a set of <Claim> elements to the RequestSecurityToken message in order to indicate which attributes it requires from the IDP.
Possible solutions
1. Allow claims in RequestSecurityToken messages and have the IdP add extra attributes to the bootstrap token when possible.
2. Have the IdP ignore claims altogether Architectural
Decision
When a WSC decides to add claims to a RequestSecurityToken message, the IdP should not be expected to process these.
(detailed) Assumptions Motivation for decision
In the Danish health sector, attributes are either provided by the WSC in the SAML authentication token or looked up by the IdP based on the WSC’s credentials. Claims are potentially useful when exchanging a bootstrap token for an identity token, but only if the STS does not leverage a priori information on what attributes a given WSP needs. In other words, claims add no value when authenticating to an IdP in the health sector scenario and hence are not needed.
Implications WSCs cannot ask for specific attributes to be added to the bootstrap token. Derived
requirements Related Decisions
“Claims in Request” [OIO-WST] p. 13
References
[CRL] Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile, The Internet Society, 2002
[OIOIDWSH-‐ID] OIOIDWS for Healthcare, Identity Token Profile, Version 1.0, SDSD 2009 [OIOIDWSH-‐MAIN] OIOIDWS for Healthcare Overview, Version 1.0, SDSD 2009
[OCSP] X.509 Internet Public Key Infrastructure Online Certificate Status Protocol – OCSP, The Internet Society, 1999
[OIO-‐BOOT] “OIO Bootstrap Token Profile”, Version 0.95, It-‐ og Telestyrelsen, 2009
[OIO-‐SAML-‐SSO] “OIO Web SSO Profile V2.0 (DK-‐SAML 2.0) -‐ Examples”, Version 1.3, November 2007, http://www.itst.dk/arkitektur-‐og-‐standarder/fora/inaktive-‐fora/oio-‐it-‐
arkitekturkomiteen/moder/mode-‐i-‐it-‐arkitekturkomiteen-‐den-‐13-‐12-‐ 07/Pkt.%203e,%20bilag%203.pdf
[OIO-‐WST] “OIO WS-‐Trust Profile”, Version 0.99, It-‐ og Telestyrelsen, 2009
[OIO-‐WSTDP] “OIO WS-‐Trust Deployment Profile”, Version 0.9, It-‐ og Telestyrelsen, 2009. [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119,
Harvard University, March 1997. http://www.ietf.org/rfc/rfc2119.txt