1 2 3 4 Identity Assurance Hub Service SAML 2.0 Profile v1.2a Identity Assurance Programme, 07 August 2015 5 6 7 8 9 10 11 12 13 14 15 16 17 18 Document identifier: IDAP/HubService/Profiles/SAML Editors: Mike Pegman, Department for Work and Pensions Adam Cooper, Government Digital Service Stephen Dunn, Government Digital Service Previous Contributors: Paul Toal, Oracle UK Ltd Brandon Murdoch, Microsoft UK Ltd Additional review and contributions were made by CESG. Abstract: This specification defines a profile for the use of SAML assertions and request-response messages to be used between participants in the Identity Assurance federation architecture. 19 Crown Copyright Page 1 of 36
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 48 49 50 51 52 53 54 55 56 Table of Contents 1 Introduction... 5 1.1 Notation... 5 1.2 Important Information: using this document... 5 2 Hub Service Profile of SAML... 6 2.1 Web Browser SSO Profile... 6 2.1.1 Required Information... 6 2.1.2 Profile Overview... 6 2.1.3 Profile Description... 7 2.1.3.1 HTTP Resource Request to Service Provider... 8 2.1.3.2 Service Provider Determines Hub Service... 8 2.1.3.3 <AuthnRequest> issued by Service Provider to Hub Service... 8 2.1.3.4 Hub Service presents Identity Provider choices to principal... 8 2.1.3.5 Principal selects Identity Provider with which to authenticate... 8 2.1.3.5.1 Alternate Flow: Principal cancels Identity Provider Selection... 9 2.1.3.6 <AuthnRequest> issued by Hub Service to the Identity Provider... 9 2.1.3.7 Identity Provider successfully identifies Principal... 9 2.1.3.7.1 Error Case: Principal fails authentication with Identity Provider... 9 2.1.3.7.2 Error Case: Principal fails authentication at the appropriate level with Identity Provider. 10 2.1.3.7.3 Alternate Flow: Principal cancels authentication attempt... 10 2.1.3.7.4 Alternate Flow: Principal unable to reach appropriate level at this time with Identity Provider Pending State... 10 2.1.3.8 Identity Provider issues <Response> to Hub Service... 10 2.1.3.8.1 Fraud Event Response: Identity Provider identifies actual or potentially fraudulent activity 11 2.1.3.9 Hub service refers to policy for attribute enrichment requirement... 12 2.1.3.10 Hub Service checks attribute requirements... 13 2.1.3.11 Hub Service determines Attribute Providers to use... 13 2.1.3.12 Principal grants or denies permission... 13 2.1.3.13 Principal provides user- entered attributes... 13 2.1.3.14 Removed from profile v1.2: <AttributeQuery> issued by Hub Service to Attribute Provider 14 2.1.3.15 Removed from profile v1.2: Attribute Provider generates Persistent Identifier... 14 2.1.3.16 Removed from profile v1.2: Attribute Provider matches Name Identifier... 14 2.1.3.16.1 Removed from profile v1.2: Error Case: Attribute Provider Fails to Uniquely Match Principal... 14 2.1.3.17 Removed from profile v1.2: Attribute Provider updates local mapping service... 14 Crown Copyright Page 2 of 36
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 2.1.3.18 Removed from profile v1.2: Attribute Provider retrieves requested attributes... 14 2.1.3.18.1 Removed from profile v1.2: Error Case: Attribute Provider Fails to retrieve requested attributes... 14 2.1.3.19 Removed from profile v1.2: Attribute Provider issues <Response> message to the Hub Service 14 2.1.3.20 <AttributeQuery> issued by Hub Service to Matching Service... 14 2.1.3.21 Matching Service generates Persistent Identifier... 15 2.1.3.22 Matching Service matches Name Identifier... 15 2.1.3.22.1 Error Case: Matching Service Fails to Uniquely Match Principal... 16 2.1.3.23 Matching Service updates local mapping service... 16 2.1.3.24 Matching Service extracts required attributes... 16 2.1.3.25 Matching Service issues <Response> message to the Hub Service... 16 2.1.3.26 Hub Service combines response and re- asserts... 17 2.1.3.27 Hub Service issues <Response> to Service Provider... 17 2.1.3.28 Service Provider grants or denies access to Principal... 17 2.1.4 Use of Authentication Request protocol... 17 2.1.4.1 <AuthnRequest> Usage... 18 2.1.4.2 <Response> Usage... 19 2.1.4.3 <Response> Message Processing Rules... 20 2.1.4.4 POST- Specific Processing Rules... 20 2.1.5 Unsolicited Responses... 20 2.1.6 Use of Attribute Query protocol... 20 2.1.6.1 <AttributeQuery> Usage... 20 2.1.6.2 <AttributeQuery> Processing Rules... 21 2.1.6.3 Attribute Query <Response> Usage... 21 2.2 Federation Termination... 22 2.3 Status Code Usage... 22 3 Name Identifiers... 23 3.1 Persistent Identifier... 23 4 Conformance... 24 4.1 Operational Modes... 24 4.2 Feature Matrix... 24 4.3 Implementation of SAML- Defined Identifiers... 25 4.4 Security Models for SOAP and URI Bindings... 25 5 IDP Specific Profile Steps... 26 5.1 Overview... 26 5.2 Profile steps... 26 Crown Copyright Page 3 of 36
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 5.2.1 <AuthnRequest> issued by Hub Service to the Identity Provider... 26 5.2.2 Identity Provider successfully identifies Principal... 27 5.2.2.1 Error Case: Principal fails authentication with Identity Provider... 27 5.2.2.2 Error Case: Principal fails authentication at the appropriate level with Identity Provider... 27 5.2.2.3 Alternate Flow: Principal cancels authentication attempt... 27 5.2.2.3.1 Alternate Flow: Principal unable to reach appropriate level at this time with Identity Provider Pending State... 28 5.2.3 Identity Provider issues <Response> to Hub Service... 28 5.2.3.1 Fraud Event Response: Identity Provider identifies actual or potentially fraudulent activity 28 6 Service Provider Specific Profile Steps... 30 6.1 Overview... 30 6.2 Profile steps... 30 6.2.1 HTTP Resource Request to Service Provider... 30 6.2.2 Service Provider Determines Hub Service... 30 6.2.3 <AuthnRequest> issued by Service Provider Hub Service... 31 6.2.4 Hub Service issues <Response> to Service Provider... 31 6.2.5 Service Provider grants or denies access to Principal... 31 7 Service Provider Matching Service Specific Profile Steps... 32 7.1 Overview... 32 7.2 Profile steps... 32 7.2.1 <AttributeQuery> issued by Hub Service to Matching Service... 32 7.2.2 Matching Service generates Persistent Identifier... 33 7.2.3 Matching Service matches Name Identifier... 33 7.2.3.1 Error Case: Matching Service Fails to Uniquely Match Principal... 34 7.2.4 Matching Service updates local mapping service... 34 7.2.5 Matching Service extracts required attributes... 34 7.2.6 Matching Service issues <Response> message to the Hub Service... 35 8 Metadata Requirements... 36 8.1 Service Provider and Matching Service Metadata... 36 8.1.1 SAML Metadata... 36 8.1.2 Additional Metadata (Service Providers)... 36 8.2 IDP Metadata... 36 8.2.1 SAML Metadata... 36 8.2.2 Additional Metadata (Identity Providers)... 36 128 Crown Copyright Page 4 of 36
129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 1 Introduction The Identity Assurance Hub Service SAML v2.0 Profile describes how service providers offering online government services can use any number of Hub Services for the brokering of a citizen authentication and enrichment of citizen attributes. This profile describes the interactions between the providers, the protocol semantics and attributes required. The subsequent sections describe how to interpret this profile. 1.1 Notation The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in IETF RFC 2119 [RFC 2119]. Schema listings appear like this. Example code listings appear like this. 1.2 Important Information: using this document This document describes the full SAML profile for the Identity Assurance Hub Service including identity provider, attribute provider and service provider interactions with the hub service. For specific documentation regarding your implementation please refer to the following sections of the document. If you are an Identity Provider please refer to section 5, Identity Provider Interface Specification. If you are a Service Provider please refer to section 6, Service Provider Interface Specification. If you are implementing a Matching Service (for a service provider) please refer to section 7, Service Provider Matching Service Interface Specification 150 151 152 Crown Copyright Page 5 of 36
153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 2 Hub Service Profile of SAML This hub service profile is defined to support federated authentication to government services and the future support of single sign-on (SSO). The current profile is based on the SAML Web Browser SSO Profile (see section 2.1). This version of the profile is a reflection of the current IDAP Hub Service and is simplified from version 1.0 removing elements not currently required for government services. Features that have been removed from the profile may be reintroduced in future versions as requirements evolve. 2.1 Web Browser SSO Profile In the scenario supported by the Hub Service profile a principal attempts to access a resource at a service provider that requires a security context. The principal is authenticated by an identity provider and has additional attributes asserted by an attribute provider(s) which is then combined by the Hub Service and an assertion produced for consumption by the service provider. On consumption of the assertion the service provider may establish a security context for the principal. The Single Logout Profile is not supported by this profile. On redirection to the hub service following a successful authentication Identity Providers MUST close any authentication session that has been created (see 2.1.3.8). This profile is implemented using the SAML Authentication Request protocol and the SAML Attribute Query protocol. It uses several of the existing SAML profiles, namely the Web SSO Profile and Assertion Query/Request Profile. It is assumed that the principal is using a standard commercial browser and can authenticate to the identity provider by some means outside the scope of SAML. By default all user agent exchanges MUST utilise TLS 1.2 or higher. Message integrity and confidentiality will be maintained through the use of asymmetric key signing and encryption. 2.1.1 Required Information Identification: urn:uk:gov:cabinet-office:saml:2.0.profiles:hubservice:sso SAML Confirmation Method Identifiers: The SAML V2.0 bearer confirmation method identifier, urn:oasis:names:tc:saml:2.0:cm:bearer, is used by this profile. Description: A profile in which a central Hub Service provides brokering of authentication requests between Service Providers and Identity Providers; as well as attribute enrichment through the use of Attribute Providers. 2.1.2 Profile Overview Figure 1 below illustrates the authenticating of a principal using a hub service. Each step in the figure is described by this profile. Crown Copyright Page 6 of 36
185 186 187 188 189 190 191 192 2.1.3 Profile Description Figure 1 - Authentication Flow In this profile the hub service has two distinct roles. When processing authentication requests from a service provider the hub service acts as an identity provider. When sending authentication requests to identity providers and attribute providers the hub service acts as a relying party. In the descriptions below the following are referred to: Crown Copyright Page 7 of 36
193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 Single Sign-On Service This is the authentication request protocol endpoint at the identity provider and at a hub service to which the <AuthnRequest> message is delivered by the user agent. Assertion Consumer Service This is the authentication request protocol endpoint at the service provider and at a hub service to which the <Response> message is delivered by the user agent. Attribute Query Service This is the attribute query protocol endpoint at the attribute provider and at the service provider to which the <AttributeQuery> message is sent by the hub service. Asserting Entity This is a hub service (when acting as an IdP with respect to a SP), an identity provider, an attribute provider or a service provider that can issue a SAML assertion or an asserted attribute. 2.1.3.1 HTTP Resource Request to Service Provider In step 1, the principal, via a HTTP User Agent, makes a HTTP request for a secured resource at service provider without a security context. The service provider is free to use any means it wishes to associate the subsequent interactions with the original request. SAML provides a RelayState mechanism that a service provider MAY use to associate the profile exchange with the original request. The service provider MUST reveal as little of the request as possible in the RelayState value. 2.1.3.2 Service Provider Determines Hub Service In step 2, the service provider determines which hub service to use to broker the authentication request. 1 This step is implementation-dependent. The hub service uri for authentication requests will be supplied by the hub service itself. There will only be a logical instance of the hub service. 2.1.3.3 <AuthnRequest> issued by Service Provider to Hub Service In step 3, an <AuthnRequest> message is delivered to the hub service s single sign-on service by the user agent. See 2.1.3.2. above for discovery of the hub service s single sign-on service. The <AuthnRequest> message MUST be signed. See section 4 for a list of SAML profiles and bindings that MUST be supported. 2.1.3.4 Hub Service presents Identity Provider choices to principal In step 4, the hub service selects identity providers to display to the principal based upon relying party [supplied] metadata and describes the requirements for IdPs for each relying party transaction. This step is necessary to make sure that the principal is presented with a user interface where all identity providers shown are able to satisfy the requirements of the service provide. Metadata defining the service provider s policy is used to provide a list of identity providers and their capabilities. This metadata will be provided out of band. The hub service MUST process the <AuthnRequest> message as described in [SAMLCore]. 2.1.3.5 Principal selects Identity Provider with which to authenticate In step 5, the principal is presented with a list of identity providers that can provide an asserted identity at the level required by the service provider. The principal selects the identity provider they want to use. 1 In the case of the IDAP Hub Service there is only one hub service. This may be reviewed in future iterations of the SAML profile. Crown Copyright Page 8 of 36
233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 This step is implementation-dependent. 2 2.1.3.5.1 Alternate Flow: Principal cancels Identity Provider Selection At this point in the flow the principal MAY indicate (for example by selecting a cancel button available on the Identity Provider selection page) that they do not wish to proceed with the authentication operation. If this occurs then the hub service MUST generate a <Response> containing a status code of urn:oasis:names:tc:saml:2.0:status:responder with a sub-status code of urn:oasis:names:tc:saml:2.0:status:noauthncontext. The hub service must then execute step 26 within the flow to issue this response to the service provider, without executing any intermediary steps. 2.1.3.6 <AuthnRequest> issued by Hub Service to the Identity Provider In step 6, the location of the identity provider's single sign-on service is retrieved from the identity provider s metadata and a new <AuthnRequest> message is produced and delivered to the identity provider via the user agent using HTTP-POST. The <AuthnRequest> message MUST be signed by the hub service and MUST define any specific elements that were included in the <AuthnRequest> it received from the service provider, such as ForceAuthn. The value of <ID> within the <AuthnRequest> MUST be set to the same value as the ID from the original <AuthnRequest> received from the service provider. The value of <ID> MUST NOT reveal the source of the request or the type of service operated by the requestor. Within the <AuthnRequest>, the Format attribute within <NameIDPolicy> MUST be set to urn:oasis:names:tc:saml:2.0:nameid-format:persistent and SPNameQualifier MUST be set to a value representing the overall hub services. The hub service MUST NOT pass the RelayState received from the service provider to the identity provider. Where the principal has explicitly selected to Register rather than Sign-In with an Identity Provider the hub service SHOULD append an additional parameter to the HTTP-POST binding of registration=true. This parameter alerts the Identity Provider to the principal s intention allowing for the optional delivery of a more appropriate user experience. 2.1.3.7 Identity Provider successfully identifies Principal In step 7, the identity provider identifies the principal by some means outside the scope of this profile. This may require a new act of authentication, or it may reuse an existing authenticated session. The identity provider MUST establish the identity of the principal or return an error to the hub service (see following sub-sections for details of error types). The ForceAuthn attribute, if present with a value of true, obligates the identity provider to freshly establish this identity, rather than relying on an existing session it may have with the principal. Otherwise the identity provider may use any means to authenticate the user as dictated by standards (e.g. GPG 44 / 45), subject to any requirements included in the <AuthnRequest> and specifically the <RequestedAuthnContext> element 3. 2.1.3.7.1 Error Case: Principal fails authentication with Identity Provider At this point in the flow, the principal may fail to successfully authenticate to the identity provider. For example, if the principal enters incorrect credentials beyond the maximum number of attempts permitted. 2 User experience testing will determine the user interface design in the hub service. This is currently in process. 3 In the IDAP Hub Service only the level of assurance will be included in <RequestedAuthnContext> Crown Copyright Page 9 of 36
273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 If the principal fails to authenticate then the identity provider MUST generate a <Response> containing a status code of urn:oasis:names:tc:saml:2.0:status:responder with a sub-status code of urn:oasis:names:tc:saml:2.0:status:authnfailed. It is recognised that additional error codes will be required as dictated by user experience research. These additional error codes will appear in future iterations of the SAML profile. 2.1.3.7.2 Error Case: Principal fails authentication at the appropriate level with Identity Provider At this point in the flow the identity provider may be unable to authenticate the user to the level specified in the <RequestedAuthnContext> within the <AuthnRequest>. For example, this could be because the principal doesn't have an account with the identity provider or that the principal doesn't have an account that can authenticate to the required level. If this occurs then the identity provider MUST generate a <Response> containing a status code of urn:oasis:names:tc:saml:2.0:status:responder with a sub-status code of urn:oasis:names:tc:saml:2.0:status:noauthncontext. In the event of an error case, the identity provider MUST also display an explanation message to the principal before issuing the response to the hub service. The contents of this message is implementation dependent but should explain to the principal, why they are being sent back to the hub service. 2.1.3.7.3 Alternate Flow: Principal cancels authentication attempt At this point in the flow, the principal may indicate (for example by selecting a cancel button available on the identity provider login page) that they do not wish to proceed with the authentication operation. If this occurs then the identity provider MUST generate a <Response> containing a status code of urn:oasis:names:tc:saml:2.0:status:responder with a sub-status code of urn:oasis:names:tc:saml:2.0:status:noauthncontext and MUST include a <StatusDetail> element containing a <StatusValue> element with the value authn-cancel. 2.1.3.7.4 Alternate Flow: Principal unable to reach appropriate level at this time with Identity Provider Pending State 4 In this case the principal is able to authenticate with the identity provider but not at the level of assurance requested by the hub service due to a system failure out of control of the principal or due to a step-out process during identity verification and proofing. Where this occurs an identity provider MAY continue to issue a <Response> to the hub service (as per step 8) at a lower level of assurance but that <Response> MUST contain a status code of urn:oasis:names:tc:saml:2.0:status:success and MUST include a <StatusDetail> containing a <StatusValue> element with the value loapending. 2.1.3.8 Identity Provider issues <Response> to Hub Service In step 8, the identity provider issues a <Response> message delivered via the user agent to the hub service. The message MUST contain either an error or an authentication assertion. Regardless of the success or failure of the authentication process, the identity provider MUST produce a HTTP response to the user agent containing a <Response> message that is delivered to the hub service s assertion consumer service. The location of the assertion consumer service MUST be one of the services registered in the metadata (as in [SAMLMeta]). If a specific assertion consumer service index is specified by the hub service in the <AuthnRequest> the identity provider MUST honour this. 4 Note that pending state is not currently implemented and will be subject to elaboration with identity providers and service providers during the lifespan of v1.2a of this profile. Crown Copyright Page 10 of 36
315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 The <Response> element and any <Assertion> element in the <Response> MUST be signed. An assertion MUST be encrypted for the hub service after it has been signed. There will be 2 <Assertion> elements sent from the IDP to the hub service via the user agent for a successful authentication event: one assertion containing the Matching DataSet (MDS), and one containing contextual information related to the authentication event. The assertion containing the authentication event will also include the <AuthnContext> element. The contextual information may include data items such as level of authentication, authentication type, and IP address. In version 1.2 this information will initially comprise of IP Address and LoA 5. A full definition of SAML Attributes relating to this SAML Profile can be found in Identity Assurance Hub Service Profile - SAML Attributes v1.2. In the case of a fraud event being identified the Identity Provider MUST return a Fraud Event Response as described in 2.1.3.8.1 below. On redirection to the hub service the Identity Provider MUST close any authentication session that has been created. 6 2.1.3.8.1 Fraud Event Response: Identity Provider identifies actual or potentially fraudulent activity Notification of a fraud event to the hub service by an identity provider MUST be via a SAML <Response> using the same basic pattern as for a normal identity provider <Response> to an authentication request. In the case of a fraud event notification the payload of the 2 <Assertion> elements required in an identity provider <Response> will vary from the normal authentication <Response> message by describing the fraud event rather than an assertion of identity 7. Where a fraud has been detected by the Identity Provider during the registration process, the Identity Provider MUST issue a <Response> to the hub service which includes a fraud event identity assertion and a fraud event contextual information assertion. These assertions are issued using the same <Response> pattern as for a normal authentication response but MUST include a specific fraud event related payload in the assertions. The fraud event identity assertion MUST include the following elements: The assertion MUST contain a <NameID> element. The Format MUST be set to urn:oasis:names:tc:saml:2.0:nameid-format:persistent. The value of this element MUST be the persistent identifier (PID) associated with the principal. A Matching Data Set attribute statement that MUST contain dummy or anonymous values as placeholders. This is to prevent statistical analysis of the assertion payload. The fraud event contextual information assertion MUST include the following elements: An <AttributeStatement> for the fraud event: o Where a contra- indicator has been identified according to GPG45 the corresponding GPG45 status code MUST be included as an attribute value o An attribute MUST be included denoting the unique IDP specific fraud event reference code. This attribute value MUST be derived from the IDP name, a date- time stamp, and a sequence number for the event. 5 Additional attribute definitions will be added during the lifetime of this profile following elaboration with Identity Providers and Service Providers. 6 Version 1.2 does not include support for a Single Logout Profile or the concept of single sign- on across HMG services. 7 Additional information relating to the detailed fraud event for fraud reporting purposes will be sent via an out- of- band process e.g. secure email. Crown Copyright Page 11 of 36
352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 An <AuthnContext> that MUST include an <AuthnContextClassRef> denoting a fraud event, and the fact that a level of assurance has not been achieved, with the value of urn:uk:gov:cabinet-office:tc:saml:authn-context:levelx The <Response> MUST contain an InResponseTo attribute set to the value contained in the original <AuthnRequest>. The <Response> MUST contain a status code of value urn:oasis:names:tc:saml:2.0:status:success 8. A full definition of SAML Attributes relating to this SAML Profile can be found in Identity Assurance Hub Service Profile - SAML Attributes v1.2. 2.1.3.8.2 Error Case: Hub Service receives an error Response from Identity Provider If the identity provider responds to the hub service with a <Response> containing either status code defined in 2.1.3.7.1, 2.1.3.7.2 or 2.1.3.7.3, then the hub service MUST handle the error as follows: For a status code urn:oasis:names:tc:saml:2.0:status:noauthncontext,the hub service MUST execute step 5 (2.1.3.5) in the SSO flow and re-present the list of identity providers to the principal to allow them select a new identity provider. The screen SHOULD contain a reason explaining why the identity selector is being displayed again. 9 For a status code urn:oasis:names:tc:saml:2.0:status:authnfailed, or for any other nonsuccess status codes (except NoAuthnContext, see above), the hub service MUST execute step 26 in the SSO flow without executing any of the intermediate steps. The status code from the identity provider MUST be sent in the <Response> message to the service provider. 2.1.3.8.3 Error Case: Hub Service receives a fraud event response from Identity Provider In the case of a Fraud Error Response (see 2.1.3.8.1) being received the hub service MUST generate a <Response> containing a status code of urn:oasis:names:tc:saml:2.0:status:responder with a sub-status code of urn:oasis:names:tc:saml:2.0:status:authnfailed and a <StatusDetail> element containing a <StatusValue> element with a value equal to the GPG45 status code as sent by the identity provider in the Fraud Error Response. 2.1.3.9 Hub service refers to policy for attribute enrichment requirement Attribute enrichment is not currently implemented in the GDS Hub Service although it is acknowledged that this functionality will be required in future iterations of the hub service. Sections 2.1.3.9 to 2.1.3.11 (steps 9 to 11 in the process flow, v1.1a) are simplified in the GDS implementation, as there are currently no available attribute providers. Sections 2.1.3.14 to 2.1.3.19 (steps 14 to 19 in the process flow, v1.1a) have been removed from the profile as they directly concern attribute provision the method for which is yet to be elaborated fully. In step 9, the hub service determines whether attribute enrichment and/or service provider matching is required, or, whether the asserted identity containing the Matching DataSet meets service provider policy. 8 For v1.2a the hub service will return an AuthnFailed response to the service provider (step 26 in the SSO flow) on receipt of a Fraud Event Response. This response will include a GPG45 status code as provided in the Fraud Event Response. 9 User experience testing is currently exploring how this will be presented. This has not been implemented in the IDAP Hub Service. Crown Copyright Page 12 of 36
389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 This will be determined based upon a set of reserved values in <RequestedAttributes> within the service provider metadata. Further details regarding metadata extensions are provided in Section 7, Metadata Requirements. 2.1.3.10 Hub Service checks attribute requirements In step 10, the hub service uses the <Issuer> of the original <AuthnRequest> to examine its policy and determine the list of attributes required. This will be contained in the metadata [SAMLMeta]. Further details regarding metadata extensions are provided in Section 8, Metadata Requirements. These attributes may be used to send to service provider or attribute provider matching services for matching purposes, or for inclusion in the <Assertion> to the service provider, for use by the service. As stated above, these attributes will only be requested if dictated by service provider policy (described in metadata) and will not be stored by the hub service. 2.1.3.11 Hub Service determines Attribute Providers to use In step 11, the hub service uses policy to determine which attribute providers to send <AttributeQuery> messages to and which attributes to request from each attribute provider. The details of how this step is implemented are implementation dependent. The details of the attributes that are available from each attribute provider will be contained within the metadata [SAMLMeta]. See section 4 for details on exchange of attribute policy. 2.1.3.12 Principal grants or denies permission In step 12, if the set of attributes required by the service is beyond the Matching DataSet, then the principal's consent is requested and obtained by the hub service. The details of how this step is implemented are implementation dependent. 2.1.3.13 Principal provides user-entered attributes In step 13, if the required attributes, as identified in 2.1.3.10 are not available from any of the attributes providers, then the principal MAY be requested to enter these attributes directly into a form presented by the hub service 10. The decision as to whether the principal should be asked to enter attributes will be determined based on the <MatchingProcess> as defined in the service provider policy as recorded in the Service Catalogue 11. If the user is prompted to enter attributes, then steps 14-16 MUST not be executed during that particular attribute request iteration (steps 10-17). The details on how the step of collecting user-entered attributes is implemented are implementation dependent. The hub service MUST create an <Assertion> containing all of the user-entered attributes. This <Assertion> MUST be signed by the hub service and MUST contain the persistent identifier value contained in the identity provider s assertion. The value of the ID attribute within the <Assertion> MUST be the same as the value of the ID attribute contained in the original <AuthnRequest> from the service provider. Note: This is in addition to setting the InResponseTo attribute when the hub service constructs a <Response> element for return to the service provider (see section 2.1.4.2 for <Response> Usage). 10 In v1.2a of the profile there will be no available attribute providers meaning that all additional attributes must be requested from the principal. 11 The service catalogue will be maintained manually by GDS for v1.2a Crown Copyright Page 13 of 36
428 429 430 2.1.3.14 Removed from profile v1.2: <AttributeQuery> issued by Hub Service to Attribute Provider 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 2.1.3.15 Removed from profile v1.2: Attribute Provider generates Persistent Identifier 2.1.3.16 Removed from profile v1.2: Attribute Provider matches Name Identifier 2.1.3.16.1 Removed from profile v1.2: Error Case: Attribute Provider Fails to Uniquely Match Principal 2.1.3.17 Removed from profile v1.2: Attribute Provider updates local mapping service 2.1.3.18 Removed from profile v1.2: Attribute Provider retrieves requested attributes 2.1.3.18.1 Removed from profile v1.2: Error Case: Attribute Provider Fails to retrieve requested attributes 2.1.3.19 Removed from profile v1.2: Attribute Provider issues <Response> message to the Hub Service 451 452 453 454 455 456 457 458 459 460 461 462 463 464 2.1.3.20 <AttributeQuery> issued by Hub Service to Matching Service To enable a service provider to obtain a match to a local identifier the <AttributeQuery> construct is used to initiate a local matching process. In step 20, the location of the service provider's matching service is determined via metadata and the hub service delivers an <AttributeQuery> message to the matching service using the SAML SOAP binding. 12 This step MUST include an <AttributeQuery> message sent to the matching service of the original request's service provider to enable the matching process to be executed. The value of the ID attribute within the <AttributeQuery> MUST be the same as the value of the ID attribute contained in the original <AuthnRequest> from the service provider. The <AttributeQuery> message MUST be signed. The request will contain a single <SubjectConfirmationData> element within <SubjectConfirmation>. This MUST contain one or more Assertions for each assertion that the matching service needs. 12 In version 1.2 of the SAML Profile service providers MUST provide a Matching Service Crown Copyright Page 14 of 36
465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 At a minimum the <AttributeQuery> MUST contain the identity provider assertion. The value of NameID contained with the <AttributeQuery> MUST be the PersistentID extracted from the identity provider assertion The <AttributeQuery> message MUST contain the identity provider assertion as well as sufficient attribute provider assertions in order to satisfy the list of required attributes for the service the principal is accessing. The <Assertion> element containing the identity provider assertion for the principal MUST be included in the attribute query and it MUST be encrypted for the matching service. This identity provider assertion MUST include the original signature from the identity provider. The hub service MUST use the synchronous SAML SOAP binding and MUST authenticate itself to the service provider by signing the message. 2.1.3.21 Matching Service generates Persistent Identifier In step 21, the matching service will hash the PersistentID in order to generate a persistent identifier to optimise subsequent matching and lookup. This identifier will be used to lookup the local identifier in the local mapping service and will be used in the <Response> to the hub service. The non-hashed PersistentID SHOULD NOT be stored. This locally generated PersistentID is mathematically derived from the PersistentID contained in the identity provider assertion. The PersistentID MUST be generated in accordance with the details provided in section 3.1 2.1.3.22 Matching Service matches Name Identifier In step 22, the service provider matching service attempts to uniquely match the principal contained in the identity provider assertion (and optionally attribute provider and hub service assertions) sent from the hub service in the <AttributeQuery> message, with a principal in the service provider. Using the attributes provided in the identity provider assertion, the service provider matching service MUST attempt to match the name identifier against previously matched principals contained in its local mapping service. If a previous match does not exist the service provider matching service MUST attempt to match the principal to a principal for which it holds attributes (i.e. a local identifier recognised by the service provider). The service provider matching service MAY decide whether to use any user-entered attributes contained in the signed hub service assertion and the level of trust it places on those values. The details of the steps taken to perform the match against the local identity repository are implementation dependent. If a previous match exists (i.e. there is a match of principal to persistent identifier a the matching service), then a <Response> containing a status code of urn:oasis:names:tc:saml:2.0:status:success and a sub-status code of urn:uk:gov:cabinet-office:tc:saml:statuscode:match MUST be returned. If a match to persistent identifier cannot be achieved the matching service MUST attempt to match the principal to a local identifier using the provided matching data set (MDS). Where a match is achieved a correlation between the name identifier and a local identity for the principal SHOULD be maintained (see 2.1.3.23). The matching service MUST process the <AttributeQuery> message as defined in [SAMLCore]. The details of the steps taken to perform the match against the local identity repository are implementation dependent. Crown Copyright Page 15 of 36
508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 2.1.3.22.1 Error Case: Matching Service Fails to Uniquely Match Principal There are a number of status codes that MAY be generated during the match process. The first failure scenario during the match is when the matching service is unable to uniquely match the principal to a local identity. In this scenario, the matching service may either have no matches for the principal or multiple matches. Where the matching service has found no matches for the principal, then it MUST return a <Response> containing a status code urn:oasis:names:tc:saml:2.0:status:responder and a sub-status code of urn:uk:gov:cabinet-office:tc:saml:statuscode:no-match. Where the matching service has found multiple matches for the principal, then it MUST return a <Response> containing a status code urn:oasis:names:tc:saml:2.0:status:responder and a sub-status code of urn:uk:gov:cabinet-office:tc:saml:statuscode:multiple-match. The second failure scenario during the match is when the matching service is unable to uniquely match the name identifier to a local identity but determines that no further matching is required. Where the matching service has found no match for the principal but does not require further matching, then it MUST return a <Response> containing a status code urn:oasis:names:tc:saml:2.0:status:success and a sub-status code of urn:uk:gov:cabinet-office:tc:saml:statuscode:no-match. 2.1.3.23 Matching Service updates local mapping service In step 23, the matching service MUST update its local mapping service to store the link between the locally generated PersistentID generated in 2.1.3.21 and the local identifier for that principal. If the matching service matches the principal contained in the <AttributeQuery> name identifier to a local identity, then the mapping service MUST store the link between the locally generated PersistentID and the local identifier for that principal. The matching service MUST NOT store any of the persistent identifiers contained in the inbound <AttributeQuery>. If the matching service is unable to match the name identifier to a local identity, through any of the configured data match escalations then an entry COULD be written into the mapping service containing a link between the locally generated PersistentID generated in 2.1.3.21 and a local, temporary identifier. This is to enable local account mapping within the service provider as well as avoid the need for the matching service to perform a match each time a request is received for a returning principal. The details of how the matching service updates its local mapping service is implemented are implementation dependent. However, the recommended approach is that the matching service SHOULD maintain a correlation between the name identifier (persistent identifier) and a local identity (local identifier) as part of the matching process (i.e. when a match is achieved), resulting in a mapping table that could be used by the service provider during its principal lookup. The details of how the local, temporary identifier are generated and updated are outside the scope of this specification and are implementation dependent. 2.1.3.24 Matching Service extracts required attributes In step 24, the matching service MUST extract any provided attribute values from the assertions contained in the <AttributeQuery> from the hub service. 2.1.3.25 Matching Service issues <Response> message to the Hub Service In step 25, the matching service issues a <Response> message to the hub service. The <Response> message must contain a name identifier of type urn:oasis:names:tc:saml:2.0:nameid-format:persistent and contain the value for locally generated persistent identifier generated in step 2.1.3.21. Crown Copyright Page 16 of 36
552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 In addition the status code MUST contain one of the status codes and sub-status codes defined in 2.1.3.22.1 or contain a status code of urn:oasis:names:tc:saml:2.0:status:success and a sub-status code of urn:uk:gov:cabinet-office:tc:saml:statuscode:match. The <Response> MUST contain all attributes extracted in 2.1.3.24, defined as standard SAML <Attribute>. The <Response> MUST include a copy of the <AuthnContext> as provided in the IDP authentication event assertion <AuthnStatement>. This information will allow the service to act upon the level of assurance reached by the principal during authentication if this has not met the minimum required level. The <Response> and <Assertion> must be signed. The <Assertion> contained in the response MUST also be encrypted for the hub service after it is signed. The matching service MUST authenticate itself to the hub service by signing the <Response>. 2.1.3.26 Hub Service combines response and re-asserts In step 26, the hub service MUST extract the <Assertion> returned in 2.1.3.25 and create a new <Response> to issue to the service provider. This <Response> MUST be signed by the hub service. 2.1.3.27 Hub Service issues <Response> to Service Provider In step 26, the hub service issues a <Response> message delivered by the user agent to the service provider. The response message MUST contain an error in the form of a status code (and any relevant sub-status code), OR contain an authentication assertion. Regardless of the success or failure of the <AuthnRequest>, the hub service MUST produce a HTTP response to the user agent containing a <Response> message which is delivered to the service provider's assertion consumer service. The location of the assertion consumer service MAY be determined using metadata (as in [SAMLMeta]). In its <AuthnRequest>, a service provider MAY indicate the specific assertion consumer service to use and the hub service SHOULD honour it if it can. The <Response> element MUST be signed. The <Assertion> element will already be signed by the service provider matching service. To ensure that the assertion is for the specific target SP the <Assertion> must also be encrypted by the hub service after it is signed using the service provider s public key. 2.1.3.28 Service Provider grants or denies access to Principal In step 27, having received the response from the hub service, the service provider processes the <Response> and <Assertion> and grants or denies access to the resource. The service provider MAY establish a security context with the user agent using any session mechanism it chooses. Any subsequent use of the <Assertion> provided is at the discretion of the service provider and other relying parties, subject to restrictions on use contained within it. The service provider MAY respond to the principal s user agent with its own error if it fails to establish a security context for the principal. The service provider MUST process the <Response> message and the enclosed <Assertion> element as described in [SAMLCore]. 2.1.4 Use of Authentication Request protocol The steps between the service provider (authentication steps), hub service and identity provider in this profile are based on the Authentication Request protocol defined in [SAMLCore]. In the nomenclature of Crown Copyright Page 17 of 36
594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 actors enumerated in Section 3.4 of that document, the service provider is the request issuer and the relying party, and the principal is the presenter, requested subject, and confirming entity. 2.1.4.1 <AuthnRequest> Usage All processing rules are as defined in [SAMLCore]. If the asserting entity cannot or will not satisfy the request, it MUST respond with a <Response> message containing an appropriate error status code or codes. The <AuthnRequest> MUST be signed. The <Issuer> element MUST be present and MUST contain the unique identifier of the requesting entity (either a service provider or hub service); the Format attribute MUST be omitted or have a value of urn:oasis:names:tc:saml:2.0:nameid-format:entity. In the case of an <AuthnRequest> from the hub service to an IdP, the <RequestedAuthnContext> element MUST be set to indicate the requested and minimum level of assured identity the service provider requires for this principal as provided in relying party (SP) metadata. For further details on the valid authentication context values refer to the accompanying document Identity Assurance Hub Service Profile - Authentication Contexts v1.2. If the <NameIDPolicy> is included, then it MUST contain the Format attribute and it MUST be set with a value of urn:oasis:names:tc:saml:2.0:nameid-format:persistent. The <Scoping> element MUST NOT be present in the <AuthnRequest> message issued by the service provider. The <Scoping> element MUST be present in the <AuthnRequest> message issued by the hub service and MUST have the ProxyCount attribute set to ProxyCount=0. There will be occasions when a service provider will have no record of the identity being asserted but may wish to create a new local account for the user in order to continue to transact. If the service provider wishes to permit the asserting entity to establish a new identifier for the principal if none exists, it MUST include a <NameIDPolicy> element with the AllowCreate attribute set to true. Otherwise, only a principal for whom the asserting entity has previously established an identifier usable by the service provider can be authenticated successfully. The hub service MUST specify the SPNameQualifier attribute and it MUST have a value. The service provider and the hub service MUST NOT include an AssertionConsumerServiceURL attribute. Instead the service provider MAY use the AssertionConsumerServiceIndex attribute for specifying where the response should be sent. The asserting entity (e.g. identity provider) MUST ensure that any AssertionConsumerServiceIndex attribute in the request is validated against the known range of service indexes belonging to the requesting entity. The service provider MAY specify the ProtocolBinding attribute and if it does it MUST have a value of urn:oasis:names:tc:saml:2.0:bindings:http-post. Metadata for the service provider issuing the <AuthnRequest> MUST contain at least one <AssertionConsumingService>. The service provider MUST define at least one <AssertionConsumingService> with an attribute isdefault set to "true". If required, the service provider MAY specify an AssertionConsumerServiceIndex attribute to override the default index. This value MUST match a correct attribute index for that service as defined and exchanged in metadata. The hub service MAY define a <Conditions> element within the <AuthnRequest> that includes a NotOnOrAfter attribute specifying time limits on the validity of any resulting assertion within the context Crown Copyright Page 18 of 36
637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 of this profile. If the time window specified in any NotOnOrAfter attribute expires the IdP MUST return a response including the status NoAuthnContext to the hub service. This will allow the hub service to provide assistance to the user where possible. Following a timeout the hub service may issue a new request to the IdP with the same Request ID as the original expired request; the IdP MUST treat this as a new authentication request. The IsPassive attribute MUST NOT be set. 2.1.4.2 <Response> Usage If the attesting entity wishes to return an error, it MUST NOT include any assertions in the <Response> message. Otherwise if the request is successful the <Response> element must conform to the following statements: The <Issuer> element MUST be present and it MUST contain the unique identifier of the issuing attesting entity. The Format attribute MUST be omitted or have a value of urn:oasis:names:tc:saml:2.0:nameid-format:entity. The <Response> message MUST contain at least one <Assertion>. An identity provider <Response> message MUST contain two <Assertion> elements. The <Response> MUST contain an InResponseTo attribute set to the value contained in the original <AuthnRequest>. Each assertion MUST contain a <Subject> element with at least one <SubjectConfirmation> element containing a Method of urn:oasis:names:tc:saml:2.0:cm:bearer. Each assertion MUST contain a <NameID> element. The Format MUST be set to urn:oasis:names:tc:saml:2.0:nameid-format:persistent. The bearer <SubjectConfirmation> element for the assertion described above MUST contain a <SubjectConfirmationData> element. Within the <SubjectConfirmationData> element, the Recipient MUST contain the value from <Issuer> in the associated <AuthnRequest>, as well as the NotOnOrAfter attribute that limits the window during which the assertion can be delivered. It MAY contain an Address attribute limiting the client address from which the assertion can be delivered. It MUST NOT contain a NotBefore attribute. The InResponseTo attribute MUST be provided and match the <AuthnRequest> ID. The bearer assertion MUST NOT contain an <AudienceRestriction>. The assertion containing the matching data MUST contain an <AuthnStatement> that reflects the level of assurance (LoA) being asserted by the identity provider. No other <AuthnStatement> should be provided in the authentication context associated with the matching data assertion. The assertion containing contextual information related to the authentication event MUST contain at least one <AuthnStatement> that reflects the authentication of the principal to the attesting entity. The assertion containing contextual information related to the authentication event MUST contain at least one <SubjectLocality> element containing the DNS name and the IP address of the system from which the SAML subject was authenticated 13. 13 Session monitoring requirements will be elaborated during the lifetime of v1.2a to be included in the authentication event assertion. <SubjectLocality> is included for compatibility with COTS products. Crown Copyright Page 19 of 36
685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 The <AuthnStatement> MUST contain an <AuthnContext> element which itself MUST contain an <AuthnContextClassRef> element with one of the SAML 2.0 defined authentication context classes. The assertion containing matching data MUST contain an <AttributeStatement> with at least one <Attribute> element. For requests that have included attribute enrichment, the <Attribute> and <AttributeValue> elements MUST contain the service provider specific identifier for the principal. For requests that have not included attribute enrichment, the <Attribute> and <AttributeValue> elements MUST contain the matching dataset attributes. A full definition of SAML Attributes relating to this SAML Profile can be found in Identity Assurance Hub Service Profile - SAML Attributes v1.2. The entire assertion MUST be encrypted for the hub. This is the case for all assertions to the hub. Where a NotOnOrAfter attribute is specified in the <Conditions> element provided in the <AuthnRequest>, validity of the assertion MUST be limited accordingly. Other conditions MAY be included as requested by the service provider, the hub service, or at the discretion of the attesting entity. (Of course, all such conditions MUST be understood by and accepted by the service provider in order for the assertion to be considered valid.) The attesting entity is not obligated to honour the requested set of <Conditions> in the <AuthnRequest>, if any. 14 Where the attesting entity wishes to return an error, it MUST NOT include any assertions of identity in the <Response> message. An Identity Provider MUST return an authentication event assertion where this is available regardless of the error condition. Details of the error must be returned in the form of a status code and any associated sub-status code as specified in the relevant process step. 2.1.4.3 <Response> Message Processing Rules The service provider MUST process the <Response> message and the enclosed <Assertion> element as described in [SAMLCore] and [SAMLProfile]. 2.1.4.4 POST-Specific Processing Rules The service provider and the hub service MUST ensure that bearer assertions are not replayed, by maintaining the set of used ID values for the length of time for which the assertion would be considered valid based on the NotOnOrAfter attribute in the <SubjectConfirmationData>. 15 2.1.5 Unsolicited Responses An attesting entity MUST NOT initiate this profile by delivering an unsolicited <Response> message to a service provider. 2.1.6 Use of Attribute Query protocol The steps between the hub service and the attribute providers, and the hub service and matching service in this profile are based on the Assertion Query and Request Protocol, specifically, the AttributeQuery definition within [SAMLCore]. 2.1.6.1 <AttributeQuery> Usage All processing rules are as defined in [SAMLCore]. The <AttributeQuery> message MUST be signed by the hub service and MUST contain the <Issuer> element. 14 This is not implemented in the IDAP Hub Service. 15 Thus is not implemented in the IDAP Hub Service. Crown Copyright Page 20 of 36