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

This html page contains lines 355-662 from the PDF version of NZ SAMS v1.0

Deployment alignment:
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 IdP’s 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.

Deployment alignment:
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.

Deployment alignment:
Refer also to [GLSMS] for specific details on the structure and content of these messages.

Deployment alignment:
Refer also to [GLSMS] for specific details on the structure and content of these messages.

Deployment alignment:
The SPs MAY use the RelayState mechanism and it is expected to be supported by the All-of-government Authentication Programme. 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.

Deployment alignment:
It is RECOMMENDED that ForceAuthn be mandatory in product selection. Do note that current SAML v2.0 certification does not test ForceAuthn. ForceAuthn SHOULD only be specified with 'XML True' (i.e. true or 1) and should only be enforced when business rules mandate re-authentication. I.e. some SPs may want to ensure the service user authentication is 'fresh' (has occurred recently), or there may also be situations where SAML applications want the service user to log in again before performing higher risk transactions. Omission of ForceAuthn SHOULD be used to indicate 'false'.

Deployment alignment:
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, or extraneous circumstances rendering it impossible to produce an HTTP <Response> (e.g. if a browser session is cancelled), 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 [GLSMS] and retain integrity in the New Zealand Government authentication systems. See NZ SAMS, Table 9 for more information on error handling.

^{End of line 428}

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 EntityID 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, it parses the artifact to extract the <SourceID>. The SP consults all known IdPs in its metadata store to locate the IdP whose SHA1(EntityID) == SourceID-from-artifact. 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.

The salient point is that if you do not already know the list of possible entity IDs, then you have no way to extract the EntityID from the <SourceID>.

Deployment alignment:
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 used in order to remain compliant with the [GLSMS].

Deployment alignment:
<RequestedAuthnContext> is used for conveying the required method of authentication to an authentication provider i.e. GLS. The default for the authentication context is 'basic'. Further details on NZ government authentication contexts can be obtained in [GLSMS].

Deployment alignment:
ForceAuthn can be utilised when the service agency requires knowledge of a successful authentication within a reasonable time period. See deployment advice located in the entry related to 4.1.3.4 above.

<ProviderName> can be used to communicate branding information in selected cases across igovt. An example of potential usage for <ProviderName> is when the IVS is communicating with the GLS on behalf of the service agency and the service agency identifier is needed to identify and control desired behaviour, i.e. the service agency brand needs to be displayed on IVS and GLS generated pages.

ProtocolBinding is a mechanism of communication between the SP and IdP (i.e. POST or Artifact). It is required when a SAML implementation uses AttributeConsumerServiceURL instead of the RECOMMENDED AttributeConsumerServiceIndex in the metadata. This attribute in the <AuthnRequest> allows service providers to determine the binding i.e. POST may be used for low risk services (or in circumstances where replay attacks are prevented) and Artifact for high risk services.

Deployment alignment:
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 [SAMLProf], and below in the entry related to line 589, and elsewhere and which 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.

Deployment alignment:
It is anticipated in most cases that attributes will get returned in the <Response> (which contains the <AttributeStatement>). It is still possible to obtain further attribute information using an <AttributeQuery>. But the <AttributeQuery> MUST NOT be used when user consent is required. The proposed IVS will utilise the <AttributeStatement>. This requirement is driven by the 'Assert Identity' use case (see Appendix A for further details) which mandates user consent of attribute release.

Deployment alignment:
The processing rules here say that for solicited responses, 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.

Deployment alignment:
Many products use SAML v2.0 Web SSO to establish a local security session that is controlled by another product, e.g. Web Access Management vendor products. While many of these products have local session time-out features, they typically do not have a means to say that the session must end at a specific time independent of time-outs.

Deployment alignment:
Unsolicited responses MAY be required when an identity provider is acting as an asserting portal, i.e. a user agent accesses the GLS to logon and utilises a link to gain access to a configured service provider. The user agent will be transported to the service provider.

Deployment alignment:
Other conditions (and other <Audience> elements) MAY be used by an IdP for NZ SAMS compliance and if present, they MUST be processed in accordance with the SAML v2.0 Specifications. However, since the <Conditions> element is not permitted by NZ SAMS, it is unlikely that other <Audience> elements will be supplied to the IdP. See subsection 4.1.4.1.

Deployment alignment:
While asynchronous bindings SHOULD be specified (to support the use cases and the SAML v2.0 Specifications' 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).

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

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

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

Deployment alignment:
When using an attribute authority with the Name Identifier Mapping profile the following guidance should be considered. See 'Figure 5 – SP initiated with Name Identifier Mapping profile', for reference.

Deployment alignment:
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 NZ SAMS sections 5.6, 'Overarching business and design rules for NZ SAMS' and 6.3.4, 'Encryption and digital signature considerations'.

Deployment alignment:
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 NZ SAMS sections 5.6 'Overarching business and design rules for NZ SAMS' and 6.3.4 'Encryption and digital signature considerations'.

Deployment alignment:
Metadata MUST be used and confirmed between the exchanging parties prior to implementation.

Deployment alignment:
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:oasis:names:tc:SAML:2.0: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:oasis:names:tc:SAML:2.0: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:oasis:names:tc:SAML:2.0:nameid-format:persistent for the decrypted identifiers. Refer to additional information on this issue in the SAML v2.0 Errata document.

Deployment alignment:
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.

This html page contains lines 355-662 from the PDF version of NZ SAMS v1.0