10. NZ SAMS Constraints on the OASIS SAML v2.0 Web Browser SSO Profile

Table 8 - NZ SAMS constraints on the OASIS SAML v2.0 web browser SSO profile

Section Description

Subsection

Line

What is excluded or altered from the SAML v2.0 Profile Specification

Section 3: Confirmation Method Identifiers

3.2 Sender Vouches

354 - 358

Ignore. Sender Vouches is NOT REQUIRED for NZ SAMS. The current uses cases have no requirement for the use of Sender Vouches.

Section 4: SSO Profiles of SAML

4.1.2 -2 Profile Overview - Service Provider determines Identity Provider

407 - 411

Deployment guidance: NOTE - All-of-government Authentication Programme identifiers will be known through exchange of metadata. Since, from the perspective of SAML v2.0 the use cases indicate that so far there are probably only three entities taking the role of an IdP (the GLS, the proposed IVS and the education sector's proposed ESAA system) they will be known to each SP through the IdPs metadata. The service user will not need to choose an IdP or use IdP Discovery so the IdP selection can be done automatically without service user interaction.

4.1.2 - 3 Profile Overview - <AuthnRequest> issued by Service Provider to Identity Provider

412 - 415

See section 6 of this Standard to determine which binding is most applicable for the security of the message being transported.

Deployment guidance: Refer also to the Shared Logon Messaging Specification for NZ SAMS available on request from authentication@ssc.govt.nz (not yet written) for specific details on the structure and content of these messages.

4.1.2 - 4 Profile Overview - Identity Provider identifies Principal

416 - 419

Deployment guidance: In the All-of-government Authentication Programme, the service user is presented with a "challenge-response" process; the GLS logon page is presented for the service user to enter his/her username and password.

Refer also to the Shared Logon Messaging Specification for NZ SAMS available on request from authentication@ssc.govt.nz (not yet written) for specific details on the structure and content of these messages.

4.1.2 - 5 Profile Overview - Identity Provider identifies Principal

420 - 425

See section 6 of this Standard to determine which binding is most applicable for the security of the message being transported.

Deployment guidance: Refer also to the Shared Logon Messaging Specification for NZ SAMS available on request from authentication@ssc.govt.nz (not yet written) for specific details on the structure and content of these messages.

4.1.2 - 6 Profile Overview - Identity Provider identifies Principal

426 - 429

Refer also to the Shared Logon Messaging Specification for NZ SAMS available on request from authentication@ssc.govt.nz (not yet written) for specific details on the structure and content of these messages.

430 - 431

This technical approach SHOULD NOT be used. The agreed usage pattern is SP initiated, not IdP initiated.

4.1.3: Profile Description

4.1.3.1 Profile Description -HTTP Request to Service Provider

445

The RelayState mechanism MAY be used.

Deployment guidance: The decision to use the <RelayState> element depends on whether the SP needs to maintain some (session) state across the SP to IdP interaction. SAML v2.0 just declares that if the SP needs to use it, the IdP must return it back to them. The IdP does not ever look at its contents or try to interpret them in any way. In some applications, the information carried in the <RelayState> element could also be used to further associate information that the SP had placed in a session cookie in the service user's browser.

4.1.3.2 Profile Description - Service Provider Determines Identity Provider

448 - 454

In the initial release of this Standard, this step is implemented by always selecting the GLS as per (4.1.2 - 2) above.

4.1.3.3 Profile Description - Service Provider Determines Identity Provider

458

The SAML v2.0 Metadata Specification MUST be used to comply with NZ SAMS.

468

See section 6 of this Standard to determine which binding and security option is most applicable for the security of the message being transported.

4.1.3.4 Profile Description - Identity Provider Identifies Principal

475 - 482

The ForceAuthn attribute in an <AuthnRequest> message MAY be specified as a mechanism for the SP to require the IdP to force the service user to log in, regardless of the session state.

Deployment guidance: Some SPs may want to ensure the service user authentication is "fresh" i.e. has occurred recently. There may also be situations where SAML applications want the service user to log in again before performing higher risk transactions.

4.1.3.5 Identity Provider issues <Response> to Service Provider

484

The IdP SHOULD produce an HTTP <Response> to the browser in the All-of-government Authentication Programme.

Deployment guidance: The reason why this element is not mandated is that if an error occurs at an underlying protocol level, then the responder will not have the context for building an appropriate <Response> message i.e. it will not be possible to send a <Response> message. At this level, if an error occurs within the SAML processing engine, then a SAML Response should be returned with an appropriate SAML status code. In all other circumstances, except in the instance of an error in an underlying protocol rendering it impossible to produce an HTTP <Response>, an HTTP <Response> must be produced. In the event of a failure the SP will need to process an error (or similar) message in order to remain compliant with the Shared Logon Messaging Specification NZ SAMS available on request from authentication@ssc.govt.nz (not yet written) and retain integrity in the New Zealand government authentication systems. See NZ SAMS, Table 9 for more information on error handling.

Clarification on how the IdP identifies itself to SP with the HTTP Artifact binding:

When the IdP Redirects the browser back to the SP's AssertionConsumerServiceURL (in an SSO use case) with the artifact representing the desired Response message, the IdP's ID is not directly included in the URL parameters. There is a "?SAMLart=xxxx" parameter that passes the artifact (and if the SP had sent a RelayState parameter in the initial transfer to the IdP, then the "RelayState=xxx" parameter would be returned intact). Once the artifact is received at the SP, if parses the artifact to extract the "SourceID". This tells the SP which IdP to now send an ArtifactResolve SOAP message to in order to retrieve the SAML message associated with the artifact. In SAML v2.0, the SourceID is a SHA-1 hash of the IdP's entity ID, which is how the SP knows which IdP to contact.

495

Deployment guidance: During SAML v2.0 interoperability testing in 2005, it was RECOMMENDED that vendors specify the AssertionConsumerServiceIndex attribute in the <AuthnRequest> message. Alternatively, the SAML binding used could be retrieved from the metadata and thus preconfigured. One option MUST be implemented in order to remain compliant with the Shared Logon Messaging Specification for NZ SAMS available on request from authentication@ssc.govt.nz (not yet written) and retain integrity in the New Zealand government authentication systems.

497 - 500

RECOMMENDED in line 497 becomes REQUIRED for NZ SAMS compliance.

4.1.3.6 Service Provider grants or denies access to user agent

503 - 508

SPs MUST specify HTTPS over SSL v3.0 or TLS v1.0 to establish a security context with the user agent (web browser).

4.1.4: Use of the Authentication Request Protocol

4.1.4.1 <AuthnRequest> Usage

515

Note the mandatory requirement for the <Issuer> element.

The following content from the <AuthnRequest> message from SAMLCore section 3.4.1, SHOULD be specified for NZ SAMS compliance:

• NameIDPolicy
• AssertionConsumerServiceIndex (since most vendor products support this rather than the alternative AssertionConsumerService URL and ProtocolBinding pair).

The following elements and attributes MAY be specified for NZ SAMS compliance dependent on specific use cases:

• <Scoping> (in use cases implementing IdP Proxy)
• RequestedAuthnContext attribute (and MUST be sent if the SP has a need for some stronger authentication key than the "basic" key that the IdP (e.g. the GLS) would normally use to authenticate the service user. The basic key is username/password over a protected transport (the authn class is called "PasswordProtectedTransport"). If RequestedAuthnContext is specified in the < AuthnRequest > , then the IdP should attempt to authenticate the service user using the requested key/credential (e.g. a hardware t oken ).

The following attributes SHOULD NOT be specified for NZ SAMS compliance:

• AttributeConsumingServiceURL
• ProtocolBinding, ProviderName.

The following elements and attributes MUST NOT be specified for NZ SAMS compliance since no use cases have been proposed to include them:

• <Subject>
• <Conditions>
• IsPassive.

525

<subject> MUST NOT be specified in an <AuthnRequest> for NZ SAMS compliance.

4.1.4.2 <Response> Usage

541

<Issuer> MUST be specified for NZ SAMS compliance.

557

The Address attribute MAY be specified for NZ SAMS compliance.

The NotOnOrAfter attribute MUST be specified for NZ SAMS compliance.

Deployment guidance: NotOnOrAfter refers to an acceptable time limit for using the assertion to authenticate the service user. The NotOnOrAfter attribute of the <SubjectConfirmationData> element has to be constrained to the lifetime of the assertion (which itself is constrained by the NotOnOrAfter attribute of the <Assertion> element). The NotOnOrAfter attributes only deal with when the SP can initially create the session for the service user.

NOTE - This is NOT related to the SessionNotOnOrAfter attribute in an AuthnStatement discussed in line 558 and elsewhere and MUST NOT be specified. SessionNotOnOrAfter is used to establish a limit on the duration of a service user's session at the SP - that if the SP uses the assertion to create a session for the service user, then it must end the session at the indicated time.

561 - 565

The <AttributeStatement> elements and attributes MUST NOT be implemented in the assertion of the response for NZ SAMS compliance.

568 - 572

Deployment guidance: Other conditions (and other <Audience> elements) MAY be implemented by an IdP for NZ SAMS compliance and if present, they MUST be processed in accordance with the SAML v2.0 Specifications.

4.1.4.3 <Response> Message Processing Rules

581 - 582

Deployment guidance: The processing rules here say that for solicited response, the InResponseTo value MUST match the ID of the corresponding <AuthnRequest> message. This is a security check important to SAML since it deals with compromise of the SSO exchange between systems and MUST not be ignored for NZ SAMS compliance.

Ignore reference to unsolicited responses in this release of NZ SAMS. To date, no use case has indicated a need for an unsolicited response.

586

While invalid assertions "SHOULD" be discarded as per the Specification, recording of the event SHOULD take place for audit and reporting purposes for NZ SAMS compliance.

589

The SessionNotOnOrAfter attribute MUST NOT be specified for NZ SAMS compliance. SessionNotOnOrAfter is used to establish a limit on the duration of a service user's session at the SP - that if the SP uses the assertion to create a session for the service user, then it must end the session at the indicated time). See comment on line 557.

Deployment guidance: Many products use SAML v2.0 web SSO to establish a local security session that is controlled by another product (e.g. a Web Access Management product such as RSA ClearTrust, Oracle SiteMinder, etc.). While many of these products have local session timeout features, they typically do not have a means to say that the session must end at a specific time independent of timeouts.

4.1.4.4 Artifact-Specific <Response> Message Processing Rules

593 - 594

See NZ SAMS, Table 6 for further information on conditions requiring encryption and/or digital signatures.

4.1.4.5 POST-specific Processing Rules

602 - 604

Time length for the validity of the ID values is subject to agency data exchange agreements and/or the Shared Logon Messaging Specification. This specification is available on request from authentication@ssc.govt.nz (not yet written). The requirement is to retain integrity in the authentication systems operated by New Zealand government agencies.

4.1.5 Unsolicited Responses

605 - 616

This subsection MUST NOT be implemented for NZ SAMS compliance. Ignore reference to unsolicited responses in the first release of NZ SAMS. To date, no use case has indicated a need for an unsolicited response.

4.1.6 Use of Metadata

617 - 650

Metadata is REQUIRED for NZ SAMS compliance. See Table 7, NZ SAMS constraints on SAML v2.0 Metadata, (subsections 2.4.2-4).

Section 4.4: Single Logout Profile

4.4.3.1 <LogoutRequest> issued by Session Participant to Identity Provider

1211 - 13

Deployment guidance: While asynchronous bindings SHOULD be specified (to support the use cases and the SAML v2.0 Specification's preference to use an asynchronous binding of some type as opposed to a synchronous binding for logout) implementers still might need the synchronous binding to do an administrator-initiated logout of a service user session, for example (i.e. the service user browser session may be active at a different site at the time of the logout request).

1222

"RECOMMENDED" in this sentence becomes REQUIRED for message integrity and security.

1227

See line 445 above regarding the <RelayState> element.

4.4.3.4 Session Participant/Authority Issues <LogoutResponse> to Identity Provider

1270 & 1289

"MAY" in this subsection is subject to data exchange agreements concluded between exchanging parties.

1275

"RECOMMENDED" in this sentence becomes REQUIRED for NZ SAMS compliance to achieve message integrity and security.

4.4.4 Use of the Single Logout Protocol

1303

Deployment guidance: The MAY in this subsection indicates that the service user might have requested a global logout as opposed to logging out a single session.

Section5: Artifact Resolution Profile

5.3.1 <ArtifactResolve> issued by Requesting Entity

1468

SAMLMeta MUST be specified for NZ SAMS compliance to locate the artifact issuer.

1471

"SHOULD" in this sentence becomes MUST for audit and reporting purposes for NZ SAMS compliance.

5.4.1 <Artifact Resolve> Usage

1491 - 3

Deployment guidance: See section 6.3.5 of NZ SAMS, Encryption and Digital Signature Considerations for guidance on when signing of messages going over the SOAP channel is necessary.

5.4.2 <ArtifactResponse> Usage

1498 - 9

Deployment guidance: See section 6.3.5 of NZ SAMS, Encryption and Digital Signature Considerations for guidance on when signing of messages going over the SOAP channel is necessary.

Section 6: Assertion Query/Request Profile

6.2 Profile Overview

1522 - 24

NZ SAMS specifies the use of only the <AttributeQuery> message since, in the All-of-government Authentication Programme, that is the only feature required by the use case (SP initiated with NameIDMapping) where the service user needs to authenticate to two entities, (one in the role of an IdP and one in the role of an Attribute Authority), and the SP in one single session.

Deployment guidance: If implementers need to use any of the other messages shown as:

• <AssertionIDRequest>
• SubjectQuery>
• <AuthnQuery>
• <AuthzDecisionQuery>

then the "roles" supported in metadata probably need to be changed by agreement with all parties implementing this Standard. Authorisation is out of scope of the first release of NZ SAMS.

6.3.1 Query/Request issued by SAML Requester

1536

For NZ SAMS compliance, SAMLMeta MUST be used to locate the authority's service endpoint for the query/request.

1539 - 40, 1548

Deployment guidance: For NZ SAMS compliance "SHOULD" in this sentence becomes MUST in that the requester MUST authenticate itself to the identity provider. To achieve this either messages MAY be signed or other processes are used for audit and reporting purposes. See 5.6, Overarching business and design rules for NZ SAMS and 6.3.5, Encryption and digital signature considerations.

6.4.1 Query/Request Usage

6.4.2 <Response> Usage

1554 -5,

1561 - 2

Deployment guidance: For NZ SAMS compliance "SHOULD" in this sentence becomes MUST in that the requester MUST authenticate itself to the identity provider. To achieve this either messages MAY be signed or other processes are used for audit and reporting purposes. See 5.6 Overarching business and design rules for NZ SAMS and 6.3.5 Encryption and Digital signature considerations.

6.5 Use of Metadata

1567 - 74

Prescription of SAMLMeta for this profile is subject to an initial implementation.

Section 7: Name Identifier Mapping Profile

1575-79

NZ SAMS specifies the use of only the <AttributeQuery> message since that is the only feature required by the use case, SP initiated with NameIDMapping, where one SP acts as an Attribute Authority for another SP based on a previously successful authentication with a service user.

7.3.1 <NameIDMappingRequest> issued by Requesting Entity

1605

SAMLMeta MUST be used to comply with NZ SAMS. See NZ SAMS, Table 7.

7.4.2 <NameIDMappingResponse> Usage

1633

Encryption MUST be used to comply with NZ SAMS, to protect the privacy of the principal. Note that because the name identifier must be encrypted, the <NameIDPolicy> element in the <NameIDMappingRequest> MUST indicate a NameID format of urn:...:nameid-format:encrypted. SAML cannot indicate both that the identifier must be encrypted AND that once decrypted, the NameID has a particular format (e.g. urn:...:nameid-format:persistent). Thus, the request should indicate that an encrypted identifier is desired and the decrypted identifier format must be agreed to out of band. In NZ SAMS, the decrypted identifier is a federated identifier and thus the agreement is to use urn:...:nameid-format: persistent for the decrypted identifiers. Refer to additional information on this issue in the SAML v2.0 Errata document.

1636 - 42

Ignore this subsection.

Deployment guidance: The NZ SAMS uses the approach of obtaining the encrypted identifier as a simple NameID because it is much simpler to implement. The approach of applying additional limits as shown in this subsection requires that the encrypted identifier must actually be a full SAML assertion with a Subject, but no statements. There are no known vendor products supporting this.