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
728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 The ID attribute in the <AttributeQuery> MUST be set to the same value as the ID attribute from the original <AuthnRequest> The message MUST contain one <NameID> element of type PrincipalIDType as defined in section 3.1 An attribute provider must ensure that only the required attributes are provided, one or more <Attribute> statements MUST be included in the message. This does not apply to matching services. The synchronous SOAP binding MUST be used to send the <AttributeQuery> request to the attribute provider. 2.1.6.2 <AttributeQuery> Processing Rules The attribute provider and service provider matching service SHOULD use its local identity mapping service first to determine if it already has a match for the principal based on the existence of the locally generated version of Identifier (based on the identifier in the <AttributeQuery>) mapped to a local identity. If an entry exists, then the attribute provider and service provider matching service SHOULD NOT execute a new identity match for that principal. If no entry exists in the identity mapping service for the locally-generated Identifier, the attribute provider and service provider matching service MUST attempt to uniquely match the principal in the request to a uniquely identified local principal. All of the values within the assertions received from the hub service MAY be used for this purpose. Upon finding a unique match, the attribute provider and service provider matching service SHOULD store a mapping between the locally-generated Identifier value and the local unique identifier for that principal. If no unique match is found, the attribute provider and service provider matching service SHOULD identify, from the list of results, which additional attributes would enable a unique match to be made. The attribute provider and service provider matching service MUST return a <Response> message to the hub service containing an error and MAY contain the list of required attributes. Any required attributes contained in the <Response> MUST be a subset of the matching process attributes contained in the provider s metadata already exchanged with the hub service. See section 2.1.3.16.1 for a list of status codes to use. 16 The attribute provider and service provider matching service MUST validate that the InResponseTo attribute values of all of the signed assertions in the <AttributeQuery> to ensure they match the ID value of the <AttributeQuery>. An error MUST be generated where this validation fails and the authentication forced to fail. It should be noted that the most likely cause of this error will be an attack on the attribute provider or matching service. 2.1.6.3 Attribute Query <Response> Usage The attribute provider and service provider matching service MUST return a response to the hub service. For an attribute provider, the response MAY contain one or more <AttributeValue> attributes for each of the requested attributes. If the attribute provider cannot provide an assertion with any statements satisfying the constraints expressed by the <AttributeQuery>, the <Response> element MUST NOT contain an <Assertion> element and MUST include a <StatusCode> element with a value of urn:oasis:names:tc:saml:2.0:status:success. The <Response> MUST contain an InResponseTo attribute set to the ID value contained in the original <AttributeQuery>. 16 This is not implemented in the IDAP Hub Service. Crown Copyright Page 21 of 36
770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 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> message and <Assertion> MUST be signed. The <Assertion> MUST be encrypted for the hub service by the attribute provider after it is signed. 2.2 Federation Termination In this scenario, the principal is provided with the ability to remove the stored link between their identity at an identity provider and their identity at a service provider. This would force matching to re-occur the next time the principal attempted to access a protected service at the service provider. It should be noted that this scenario does not prevent the principal from authenticating at an identity provider and accessing protected services. Instead it is designed to remove the existing link between the principal s identities at the two entities. To simplify the design, a pragmatic approach was taken to implementing federation termination. As a result the hub service profile does not define a flow based on SAML 2.0 Name Identifier Management Profile. Instead, the hub service profile RECOMMENDS that service providers SHOULD provide an administrative function that allows an administrator to remove the PersistentID<->LocalID mapping within the local mapping service in the service provider. Furthermore, processes SHOULD be implemented at the service provider to enable a principal to request that this mapping is removed from the mapping service. 2.3 Status Code Usage The IDA SAML Profile describes a number of situations where status codes are required to be returned to the hub service to describe the occurrence of specific events. All status codes MUST be returned in the SAML <Response> element as one or more nested <StatusCode> elements. SAML Core specifies 4 top-level status codes that can be returned and a range of subordinate status codes that can be returned beneath the top-level status code. For example, the IDA SAML Profile states that when a principal cancels an authentication at the IDP the IDP should respond with a status code of urn:oasis:names:tc:saml:2.0:status:noauthncontext (see section 2.1.3.5.1). This would result in the following <Status> element in the IDP <Response>: <saml:status> <saml:statuscode Value="urn:oasis:names:tc:SAML:2.0:status:Responder"> <saml:statuscode Value="urn:oasis:names:tc:SAML:2.0:status:NoAuthnContext"/> </saml:statuscode> </saml:status> Any status codes MUST be returned as specified in SAML Core with the status code values as specified in the IDA SAML Profile for a particular event. 809 Crown Copyright Page 22 of 36
810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 3 Name Identifiers This section details the policy for use and creation of persistent identifiers by the attribute providers and service provider matching services. 3.1 Persistent Identifier URI: urn:oasis:names:tc:saml2.0:nameid-format:persistent This identifier is used between the hub and identity provider, and the hub and service provider. It conforms to the [SAMLCore] specification for persistent name identifiers. The persistent identifier MUST be generated in conformance to [SAMLCore] by the identity provider and included in the assertion for a given principal. The identity provider SHOULD ensure that the persistent identifier is valid for an extended period of time, e.g. several months to avoid unnecessary re-matching occurring. To ensure privacy of the principal is maintained across providers, the persistent identifier stored for the same principal MUST be unique between each of the following entities: Identity Provider Attribute Provider Service Provider In order to ensure uniqueness of the persistent identifier and to ensure no identifiers are stored within the hub service, an algorithm will be used for generation of the persistent identifier. This will be implemented within every attribute provider and service provider (within the service provider matching service.) For a single principal, the identity provider MUST generate a different, unique persistent identifier for the unique SPNameQualifier it receives in the <AuthnRequest>. Upon receiving an <AttributeQuery>, the attribute provider and service provider matching service must obfuscate the received persistent identifier by applying a hashing algorithm. The value fed into the hashing algorithm MUST be a concatenation of the partner identifier of the identity provider (A), the partner identifier of the entity generating the identifier (B), and the received persistent identifier - originating from the identity provider (C). Therefore, the following format will be used: hash{a+b+c} The hashing algorithm to use MUST be SHA-256. The attribute providers and service providers MUST NOT locally store any persistent identifiers from any assertions, other than the identifier that they have generated using the above algorithm, which MUST be used when writing to the local mapping service. Crown Copyright Page 23 of 36
841 842 843 844 845 846 4 Conformance This profile follows the criteria for conformance defined in the SAML 2.0 document titled "Conformance Requirements for the OASIS Security Assertion Markup Language (SAML) V2.0" [SAMLConf]. This section details specific conformance criteria that must be met for the Identity Assurance Hub Service. In addition, the following sections of the [SAMLConf] document MUST be adhered to with the listed amendments: 847 848 849 850 o o o o 3.4 Implementation of Encrypted Elements 3.6 Metadata Structures 3.7 Metadata Interoperation 4 XML Digital Signature and XML Encryption 851 Amendment: MUST utilise SHA-256 instead of SHA1 852 853 854 855 856 857 858 859 860 861 862 863 864 865 o 5 Use of SSL 3.0 or TLS 1.0 17 Amendment: MUST utilise TLS 1.2 or higher and NOT SSL 3.0 or TLS 1.0 4.1 Operational Modes Within the Identity Assurance Hub Service Profile, the following operational modes have been identified that describes the roles each software components can play in conforming to this profile. These operational modes are: IdP - Identity Provider SP - Service Provider AtP - Attribute Provider HS - Hub Service 4.2 Feature Matrix In order to be conformant with the Identity Assurance Hub Service profile, each of the software components described in the Operational Modes section must provide support for the features detailed below: Feature Service Provider Identity Provider Attribute Provider Hub Service Web SSO <AuthnRequest>, HTTP MUST NOT MUST NOT N/A MUST NOT redirect Web SSO <AuthnRequest>, HTTP MUST MUST N/A MUST POST Web SSO <AuthnRequest>, HTTP MUST NOT MUST NOT N/A MUST NOT artifact Web SSO <Response>, HTTP MUST MUST N/A MUST POST Web SSO <Response>, HTTP MUST NOT MUST NOT N/A MUST NOT artifact Single Logout <LogoutRequest>, N/A N/A N/A N/A 17 Security standards such as those specified in SAML2 Conformance are subject to GDS review and may be subject to incremental change to protect the integrity and security of user data and to protect HMG services from attack. Crown Copyright Page 24 of 36
866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 HTTP Redirect Single Logout <LogoutRequest>, N/A N/A N/A N/A HTTP POST Single Logout <LogoutRequest>, N/A N/A N/A N/A SOAP Single Logout <LogoutRequest>, MUST NOT MUST NOT N/A MUST NOT HTTP Artifact Single Logout <LogoutResponse>, N/A N/A N/A N/A HTTP Redirect Single Logout <LogoutResponse>, N/A N/A N/A N/A HTTP POST Single Logout <LogoutResponse>, N/A N/A N/A N/A SOAP Single Logout <LogoutResponse>, MUST NOT MUST NOT N/A MUST NOT HTTP Artifact Attribute Query, SOAP N/A N/A MUST N/A Metadata Structures MUST MUST MUST MUST Metadata Interoperation MUST MUST MUST MUST All other SAML profiles and binding as defined in [SAMLCore], [SAMLBind] and [SAMLProf] are not used within this profile. 4.3 Implementation of SAML-Defined Identifiers All relevant operational modes MUST implement the following SAML- defined identifiers: All Attribute Name Format identifiers defined in Section 5 of this document and Section 8.2 of [SAMLCore] The name identifier Persistent Identifier defined in Section 8.3 of [SAMLCore] Implementations conforming to this Identity Assurance Hub Service Profile MUST permit the use of all identifier constants described in Sections 8.2 of [SAMLCore] as well as all identifier constants described in Section 5 of this document. Conforming implementations MUST also permit the use of the name identifier Persistent Identifier as defined in Section 8.3 of [SAMLCore]. Sections 8.3.7 (persistent name identifiers) defines normative processing rules for the producer of such identifiers. All normative processing rules in Sections 8.3.7 MUST be supported by conforming implementations. 4.4 Security Models for SOAP and URI Bindings The following security models are mandatory for meeting conformance to this profile using the SOAP binding as well as for the SAML URI binding. SAML authorities and requesters MUST implement the following method: HTTP over SSL 3.0 or TLS 1.02 (or higher) server authentication with server-side certificates to ensure the confidentiality and integrity of all messages is maintained during transport. 887 Crown Copyright Page 25 of 36
888 889 890 891 892 893 894 895 896 897 5 IDP Specific Profile Steps 5.1 Overview Identity Providers (IDPs) interact with a single service provider, the IDA hub service, which acts as a federation hub between the service wishing to complete a transaction (the service provider, SP, in the figure 2 below), and the identity provider itself. Principals are directed to the identity provider (from the hub service) via the user agent with an <AuthnRequest> describing the level of assurance required by the relying party. On receipt of the <AuthnRequest> the identity provider follows the process steps described below in order to attempt authentication of the principal at the requested level of assurance. Identity providers are free to perform registration as part of this process if required but this is not described in this profile. 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 5.2 Profile steps Figure 2 Identity Provider Authentication Flow The following profile steps are taken from the full authentication flow described in section 2.1 of this document. Step numbers have been retained to match the full process flow. The steps relating to an identity provider are shown in Figure 2 above. 5.2.1 <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. Crown Copyright Page 26 of 36
917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 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. 5.2.2 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. 5.2.2.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. 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. 5.2.2.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. 5.2.2.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. Crown Copyright Page 27 of 36
959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 5.2.2.3.1 Alternate Flow: Principal unable to reach appropriate level at this time with Identity Provider Pending State 18 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> element containing a <StatusValue> element with the value loa-pending. 5.2.3 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]). A hub service MAY indicate the specific assertion consumer service index to use in its <AuthnRequest> and the identity provider MUST honour this if set and valid. The <Response> element and any <Assertion> element in the <Response> MUST be signed. The 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 19. 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 5.2.3.1 below. On redirection to the hub service the Identity Provider MUST close any authentication session that has been created. 20 5.2.3.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 21. 18 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. 19 Additional attribute definitions will be added during the lifetime of this profile following elaboration with Identity Providers and Service Providers. 20 Version 1.2a does not include support for a Single Logout Profile or the concept of single sign- on across HMG services. Crown Copyright Page 28 of 36
997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 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. 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 22. A full definition of SAML Attributes relating to this SAML Profile can be found in Identity Assurance Hub Service Profile - SAML Attributes v1.2. 21 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. 22 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. Crown Copyright Page 29 of 36
1023 1024 1025 1026 1027 1028 1029 1030 1031 6 Service Provider Specific Profile Steps 6.1 Overview Service Providers will interact with a single logical identity provider in the form of the hub service. When the service provider wishes to authenticate an individual an <AuthnRequest> will be constructed by the service provider and sent to the hub service s identity provider interface. The hub service will orchestrate the authentication process resulting in a <Response> being sent to the requesting service provider. Service providers will also need to specify a Service Provider Matching Service (see section 7) to complete the identification of an individual. 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 6.2 Profile steps Figure 3 Service Provider Authentication Flow The following profile steps are taken from the full authentication flow described in section 2.1 of this document. Step numbers have been retained to match the full process flow. The steps relating to a service provider are shown in Figure 3 above. 6.2.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. 6.2.2 Service Provider Determines Hub Service In step 2, the service provider determines which hub service to use to broker the authentication request. 23 23 In the case of the reference architecture there is only one hub service. This may be reviewed in future iterations of the SAML profile. Crown Copyright Page 30 of 36
1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 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. 6.2.3 <AuthnRequest> issued by Service Provider 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. 6.2.4 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. 6.2.5 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]. Crown Copyright Page 31 of 36
1078 1079 1080 1081 1082 1083 1084 7 Service Provider Matching Service Specific Profile Steps 7.1 Overview Service Provider Matching Services respond to matching requests from the hub service in the form of an <AttributeQuery>. Matching services act on behalf of a service provider to obtain a match to a local identifier relevant to the service provider and enabling it to complete a transaction for the principal. 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 7.2 Profile steps Figure 4 Service Provider Matching Service Authentication Flow The following profile steps are taken from the full authentication flow described in section 2.1 of this document. Step numbers have been retained to match the full process flow. The steps relating to a service provider matching service are shown in Figure 4 above. 7.2.1 <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. 24 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. 24 In version 1.2 of the SAML Profile service providers MUST provide a Matching Service Crown Copyright Page 32 of 36
1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 The request will contain a single <SubjectConfirmationData> element within <SubjectConfirmation>. This MUST contain one or more Assertions for each assertion that the service provider needs. 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. 7.2.2 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. 7.2.3 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. 25 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 25 This has not been implemented in the IDAP Hub Service. Crown Copyright Page 33 of 36
1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 correlation between the name identifier and a local identity for the principal SHOULD be maintained (see 7.2.4). 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. 7.2.3.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. 7.2.4 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. 7.2.5 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. Crown Copyright Page 34 of 36
1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 7.2.6 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. 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 requester by signing the <Response>. Crown Copyright Page 35 of 36
1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 8 Metadata Requirements 8.1 Service Provider and Matching Service Metadata 8.1.1 SAML Metadata Service Providers and matching services will be required to provide content equivalent to standard SAML metadata elements to describe the keys, endpoints and contact details required by their services and for operation with the hub service. This metadata SHOULD be provided out of band via methods described in the GOV.UK Verify on-boarding guide. These metadata elements MAY be described as SAML metadata conforming [SAMLConf] as specified in section 4 of this document and the SAML Metadata Definition - http://docs.oasis- open.org/security/saml/v2.0/saml- metadata- 2.0- os.pdf. Service Provider Metadata will include keys, endpoints and contact elements defined in standard SAML metadata. 8.1.2 Additional Metadata (Service Providers) Service Providers MUST provide additional metadata required for connection to the hub service including Level of Assurance requirements, and matching requirements (endpoints and process steps). This additional service provider metadata will be gathered out-of-band and will be specified in the GOV.UK Verify on-boarding guide. 8.2 IDP Metadata 8.2.1 SAML Metadata Identity Providers will be required to provide content equivalent to standard SAML metadata elements to describe the keys, endpoints and contact details required for operation with the hub service. This metadata SHOULD be provided out of band via methods described in the GOV.UK Verify IDP onboarding documentation. These metadata elements MAY be described as SAML metadata conforming [SAMLConf] as specified in section 4 of this document and the SAML Metadata Definition - http://docs.oasis- open.org/security/saml/v2.0/saml- metadata- 2.0- os.pdf. Identity Provider Metadata will include keys, endpoints and contact elements defined in standard SAML metadata. 8.2.2 Additional Metadata (Identity Providers) Identity Providers MUST provide additional metadata required for connection to the hub service such as user interface elements and instructional text for the hub IDP selection process. This additional identity provider metadata will be gathered out-of-band and will be specified in the GOV.UK Verify on-boarding guide. Crown Copyright Page 36 of 36