11. NZ SAMS Constraints on the OASIS SAML v2.0 Bindings

Table 9 - NZ SAMS constraints on the OASIS SAML v2.0 bindings

Section Description

Subsection

Line

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

Section 2: Guidelines for specifying additional protocol bindings

187 - 220

New Zealand government agencies MUST submit any additional or new protocol bindings to the Secure Messaging working group co-ordinated by SSC in the first instance. The Working Group can work through the implications of the proposal on the existing bindings in use. See contact details in section 4.

Section 3: Protocol Bindings

3.1: General Considerations:

Section 3 describes, for each supported SAML binding, how aspects such as protocol headers, caching, error reporting, and SAML metadata should be handled. Many of these items are largely out of the control of any individual agency since they are incorporated into vendor products and implementations. All normative requirements described in these sections must be adhered to.

Deployment guidance: For NZ SAMS compliance, in the case of error reporting (refer lines 370-77, 826, 862), it is expected that errors are dealt with at the protocol level at which they occur. That is, errors that occur while establishing an SSL-secured HTTP connection (e.g. an SSL certificate problem) SHOULD return an HTTP "403 Forbidden" response. An error at a SOAP level MUST return a SOAP fault. An error while processing the internals of a SAML <Request> message SHOULD be reported by using a SAML <Response> message with an appropriate SAML status code.

3.1.2.1 Security: Use of SSL v3.0 or TLS v1.0

238 - 240

For NZ SAMS compliance, server identity will be achieved as proposed here, relying on mapping the certificate DN or the public key to the partner's identity.

3.1.2.2/3 Security: Data Origin Authentication and Message Integrity

243

Deployment guidance: "OPTIONAL" in this sentence depends on whether the message is to be transported over a private VPN or separately-secured channel. See NZ SAMS, 6.3.5 for more guidance.

245 & 254

"MAY" in these sentences becomes "SHOULD" for NZ SAMS compliance. The choice of bindings MUST be specified in agency exchange agreements.

Deployment guidance: IdP and SP applications to process the message is one example of an "environment of use".

248

"recommended" in this sentence becomes "REQUIRED" for NZ SAMS compliance.

256

"recommended" in this sentence becomes "REQUIRED" for NZ SAMS compliance.

3.1.2.4 Security: Message Confidentiality

260

"OPTIONAL" in this sentence depends on whether the message is to be transported over a private VPN or a separately-secured channel. See 6.3.5 in this Standard for more guidance.

Deployment guidance: Message confidentiality remains optional at a high level because certain messages, such as an artifact, contain no information that of itself is confidential.

3.1.2.5 Security: Security Considerations

265

"SHOULD" in this line becomes "MUST" for NZ SAMS compliance and MUST be specified in agency exchange agreements. The All-of-government Authentication Programme and IdP and SP applications to process the message are examples of a "deployment environment".

3.2: SAML SOAP Binding:

3.2.2 Protocol-Independent Aspects of the SAML SOAP Binding

Ignore this subsection.

Deployment guidance: Support for SOAP headers will be controlled by the vendor products and implementations since the SOAP implementation is bundled into it.

3.2.3 Use of SOAP over HTTP

Ignore this subsection.

Deployment guidance: The SOAP header will be under the control of the SOAP library used by the vendor product or implementation. The other aspects shown here are also largely outside of the control of agencies to control.

3.3: Reverse SOAP (PAOS) Binding

Deployment guidance: This subsection will not be prescribed in the first release of NZ SAMS. It is expected to be prescribed when a usage pattern supporting the ECP profile is presented for inclusion in later releases of NZ SAMS.

3.4: HTTP Redirect Binding

525 & 529

"MAY" in these sentences MUST be specified in agency exchange agreements; that is, the use of HTTP POST or artifact bindings in conjunction with the HTTP Redirect binding.

3.4.3 RelayState

545 - 57

Deployment guidance: See NZ SAMS, Table 8 for further details on RelayState. Integrity protection using a checksum, a pseudo-random value or similar means may be pre-configured in many vendor products.

3.4.4 Message Encoding

559 -72

Deployment guidance: Vendor products may employ methods other than metadata to indicate which encoding the binding endpoints support. Whatever method is used it needs to be one of those prescribed by SAML v2.0.

3.4.4.1 DEFLATE Encoding

582

"SHOULD NOT" in this sentence becomes "MUST NOT" for NZ SAMS compliance.

599 - 615

XML signatures and the encoding mechanisms specified MUST be used for NZ SAMS compliance.

3.4.5 Message Exchange

636 - 46

Deployment guidance: Controlling additional info when the redirect binding is used to carry a SAML message may not be possible in many vendor products.

645

"SHOULD" in this sentence becomes "MUST" for NZ SAMS compliance.

3.4.5.1 HTTP and Caching Considerations

652

Deployment guidance: These rules are usually pre-configured in most vendor products.

3.4.5.2 Security Considerations

659

Deployment guidance: See 6.3.5 of this Standard (Encryption and digital signature considerations) for further guidance on integrity protection via signatures.

668

"SHOULD" in this sentence becomes "MUST" for NZ SAMS compliance.

673

"SHOULD" in this line becomes "MUST" for NZ SAMS compliance and MUST be specified in agency exchange agreements. The All-of-government Authentication Programme and IdP and SP applications to process the message are examples of a "deployment environment".

3.4.6 Error Reporting

679

"SHOULD" in this sentence becomes "MUST" for NZ SAMS compliance.

3.4.7 Metadata Considerations

687

"SHOULD" in this line becomes "MUST" for NZ SAMS compliance and MUST be specified in agency exchange agreements.

3.5: HTTP POST Binding

754 - 8

"MAY" in these sentences MUST be specified in agency exchange agreements; that is, the use of HTTP Redirect or Artifact bindings in conjunction with the HTTP POST binding.

3.5.3 RelayState

775 - 87

Deployment guidance: See NZ SAMS, Table 8 for further details on RelayState. Integrity protection using a checksum, a pseudo-random value or similar means may be pre-configured in many vendor products

3.5.4 Message Encoding

793

Deployment guidance: With respect to the line wrapping value or range, the base46-encoding of the SAML message is handled by packages bundled with the vendor products and are usually not configurable.

803 - 6

The encoding technique MUST be specified in agency exchange agreements. The All-of-government Authentication Programme will prescribe the approach in the Shared Logon Messaging Specification for NZ SAMS available on request from authentication@ssc.govt.nz (not yet written).

3.5.5 Message Exchange

821 - 2

"MAY" in this sentence MUST be specified in agency exchange agreements. The All-of-government Authentication Programme will prescribe the approach in the Shared Logon Messaging Specification for NZ SAMS available on request from authentication@ssc.govt.nz (not yet written).

826

The rationale for "SHOULD" in this sentence is given above at the beginning of this section (section 3 Protocol Bindings) for NZ SAMS compliance.

3.5.5.1 HTTP and Caching Considerations

833

Deployment guidance: These rules are usually pre-configured in most vendor products.

3.5.5.2 Security Considerations

842

See NZ SAMS, 6.3.5 for further guidance on integrity protection via signatures.

Deployment guidance: NZ SAMS rules are as for the redirect binding. Certain messages carried via the POST binding might not really be important to sign (e.g. POST could be used for an <AuthnRequest> message (instead of a redirect binding) and it might not need signing). Extra signatures are a significant overhead.

858 - 60

Deployment guidance: SPs deploying the RelayState mechanism should note the comment on associating sensitive state values with the RelayState value. See NZ SAMS, Table 8 for further details on RelayState.

3.5.6 Error Reporting

862

The rationale for "SHOULD" in this sentence is given above at the beginning of this section (section 3 Protocol Bindings).

3.5.7 Metadata Considerations

870

"SHOULD" in this line becomes "MUST" for NZ SAMS compliance and MUST be specified in agency exchange agreements.

3.6: HTTP Artifact Binding

986

"MAY" in this sentence MUST be specified in agency exchange agreements; that is, the use of HTTP Redirect or HTTP POST binding may be used to compose this binding.

3.6.2 Overview:

996 - 1005

Deployment guidance: Most usage patterns that use services delivered by the All-of-government Authentication Programme are required to be supported by the HTTP Artifact binding.

3.6.3 Message Encoding:

1007 - 10

Deployment guidance: Some vendor products implement the GET method and not the FORM POST method for passing the artifact. (This is not the same as the POST Binding.) The choice of which method to used to encode the artifact MUST be specified in agency exchange agreements. The All-of-government Authentication Programme will prescribe the approach in the Shared Logon Messaging Specification for NZ SAMS available on request from authentication@ssc.govt.nz (not yet written).

3.6.3.1 RelayState

1012 - 25

Deployment guidance: See NZ SAMS, Table 8 for further details on RelayState. Integrity protection using a checksum, a pseudo-random value or similar means may be pre-configured in many vendor products.

3.6.3.2 URL Encoding

1027 - 30

Deployment guidance: See NZ SAMS, Table 8 for further details on RelayState.

3.6.3.3 Form Encoding

1040 - 1

"MAY" in this sentence MUST be specified in agency exchange agreements.

3.6.4 Artifact Format

1058 - 66

Any deviation from the RECOMMENDED practices defined in the Specification MUST be specified in agency exchange agreements. The All-of-government Authentication Programme will prescribe the approach in the Shared Logon Messaging Specification for NZ SAMS available on request from authentication@ssc.govt.nz (not yet written).

3.6.4.2 Format Details

1082 - 3

Note that the use of the SAMLMeta is REQUIRED for NZ SAMS compliance.

1087 - 90

Deployment guidance: The principles governing SourceID and MessageHandle values MUST be specified in agency exchange agreements. Artifact creation is typically under the control of the vendor product and may not be configurable.

3.6.5 Message Exchange

1091 - 1108

Deployment guidance: An Artifact/Artifact binding set is not prescribed for NZ SAMS. However, this section describes a SAML message exchange (e.g. AuthnRequest/Response) using the Artifact binding, for information purposes only.

Both halves of the <AuthnRequest> and <Response> (with assertion) exchange could use the artifact binding. In this case, the 1st half of the exchange (the <AuthnRequest> message) is built by the SP and an artifact referring to it is created. The artifact is sent via an HTTP redirect to the IdP. The IdP calls over SOAP to the SP's ArtifactResolutionService endpoint with an <ArtifactResolve> request and the SP sends the real <AuthnRequest> back over the SOAP channel to the IdP. It can now process the <AuthnRequest>, build an assertion in a <Response> message and create an artifact that refers to it. The browser is redirected back to the SP with the artifact to begin the 2nd half of the original exchange. The SP now sends an <ArtifactResolve> message to the IdP to retrieve the real response.

NOTE -

• An Artifact binding would almost never be used for an < AuthnRequest > (which is why it has not arisen in the use cases for NZ SAMS). Use a Redirect Binding or perhaps POST binding if the < AuthnRequest > includes a large amount of message content.
• No risk is assumed in the discarding of the artifact at this point in the process but MAY be specified in agency exchange agreements.

1109 - 1141

Deployment guidance: These rules are usually pre-configured in most vendor products.

3.6.5.1 HTTP and Caching Considerations

1144

Deployment guidance: These rules are usually pre-configured in most vendor products.

3.6.5.2 Security Considerations

1153 & 1159

"MAY" in these sentences becomes "MUST" for NZ SAMS compliance.

1157 - 58

"SHOULD" in this sentence MUST be specified in agency exchange agreements, since agencies using the Government Shared Network (for example) may not need additional protection of the transmission.

1163 - 73

Deployment guidance: The directives in this paragraph MUST be specified in agency exchange agreements. Vendor product implementations are expected to reflect this approach but deployers are advised to check for it and provide an effective means to address this issue. The All-of-government Authentication Programme will prescribe the approach in the Shared Logon Messaging Specification for NZ SAMS available on request from authentication@ssc.govt.nz (not yet written). Any deviation from "SHOULD" in these sentences MUST be specified in agency exchange agreements.

3.6.6 Error Reporting

1175 - 86

"SHOULD" in this sentence becomes "MUST" for NZ SAMS compliance.

3.6.7 Metadata Considerations

"SHOULD" and "MAY" in these sentences become "MUST" for NZ SAMS compliance and MUST be specified in agency exchange agreements.

3.7 SAML URI Binding

Ignore this subsection. To date no use cases require the use of this very specialised binding.