9. NZ SAMS Constraints on OASIS SAML v2.0 Metadata

Table 7 - NZ SAMS constraints on OASIS SAML v2.0 metadata

Section Description

Subsection

Line

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

Metadata for SAML v2.0

2.3 Root Elements

306 - 309

A metadata XML instance document contains a SINGLE root element. That element can be <EntityDescriptor> or <EntitiesDescriptor>.

The description of multiple <EntitiesDescriptor> elements within a single metadata XML instance document MUST NOT be implemented in NZ SAMS.

Deployment guidance: Implementers can only put multiple <EntitiesDescriptor> elements in a single document by putting a "wrapper" <EntitiesDescriptor> element around ALL other <EntityDescriptor> and/or <EntitiesDescriptor> elements (so that there is only one root element). Allowing the embedding of <EntitiesDescriptor> elements within <EntitiesDescriptor> elements, creates confusion and vendor products may not support it.

NZ SAMS will only use a single <EntitiesDescriptor> element to hold multiple <EntityDescriptor> elements; and only then if there are multiple entities.

Usually, the metadata file will contain a single <EntityDescriptor> identifying all "roles" that a single NZ SAMS system supports.

If an IdP or SP website has more than one NZ SAMS system (each identified by a different entity ID), then NZ SAMS allows the metadata instance document to use a single <EntitiesDescriptor> element that has multiple <EntityDescriptor> child elements. Each <EntityDescriptor> element must identify all roles of a single system at the site.

2.3.1 Element <EntitiesDescriptor>

310 - 358

Deployment guidance:

Attributes of <EntitiesDescriptor> to be implemented as follows:

• ID: MUST be provided if the <EntitiesDescriptor> is signed (XMLSig requires it); otherwise it is optional and may be ignored
• validUntil and cacheDuration: One of these MUST be included
• Name: optional and can be ignored if present.

<EntitiesDescriptor> child elements to be implemented as follows:

• <ds:signature>: optional, but if included, a site processing the metadata MUST validate the signature
• <Extensions>: NOT RECOMMENDED and if present will be ignored
• <EntitiesDescriptor>: MUST NOT be implemented in NZ SAMS
• <EntityDescriptor>: one or more are REQUIRED for NZ SAMS compliance.

2.3.2 Element <EntityDescriptor>

359 - 1157

Deployment guidance:

Attributes of <EntityDescriptor> to be implemented as follows:

• entityID: REQUIRED for NZ SAMS compliance
• ID: MUST be provided if the <EntitiesDescriptor> is signed (XMLSig requires it); otherwise it is optional and may be ignored. NZ SAMS allows signing of individual <EntityDescriptor> elements within an <EntitiesDescriptor> that is at the root of the document
• validUntil and cacheDuration: One of these MUST be included if the <EntityDescriptor> is the root element of the metadata XML instance document. If the <EntityDescriptor> element is a child element of an <EntitiesDescriptor> element, then these attributes MUST NOT be included.

<EntityDescriptor> child elements to be implemented as follows:

• <ds:Signature>: optional, but if included, a site processing the metadata MUST validate the signature
• <Extensions>: NOT RECOMMENDED and if present will be ignored
• <RoleDescriptor>, <AuthnAuthorityDescriptor>, <PDPDescriptor>, <AffiliationDescriptor>: MUST NOT be implemented in NZ SAMS
• <IDPSSODescriptor>: From the use cases, the GLS, the proposed IVS and the education sector's proposed ESAA system are the only entities that should be an IdP for SSO
• <SPSSODescriptor>: All agency systems will act as SPs for SSO
• <AttributeAuthorityDescriptor>: From the use cases, the proposed IVS is the only Attribute Authority
• <Organization>: REQUIRED NZ SAMS compliance
• <ContactPerson>: NZ SAMS RECOMMENDS that one be included
• <AdditionalMetadataLocation>: MUST NOT be implemented in NZ SAMS.

2.4 Role Descriptor Elements

See Deployment guidance above in 2.3.1 and 2.3.2.

572 - 574

Individual metadata role descriptors MUST NOT be signed for NZ SAMS compliance. If metadata is signed it must be done at the <EntityDescriptor> or <EntitiesDescriptor> element level.

2.4.1.1 <KeyDescriptor>

611 - 642

If signing or encryption of SAML messages (i.e. not the metadata) is supported by a role, <KeyDescriptor> elements MUST be used to describe the certificates and/or keys required for the partner to deal with the cryptographic operation. That is, certificates and keys for SAML signing and encryption MUST be shared using the SAML metadata for the entities (as opposed to passing around keystore files, cert .pem files, etc. out of band).

XMLEnc is the specified encryption method. See http://www.w3.org/

2.4.2, 2.4.3, 2.4.4, SSO descriptors for IDP and SP

648 - 651

If an artifact binding is supported at the site, an <ArtifactResolutionService> element MUST be specified for NZ SAMS compliance.

652 - 654

If a Single LogoutService is supported at the site, a <SingleLogoutService> element MUST be specified for NZ SAMS compliance.

655 - 657

Ignore. Name Identifier Management MUST NOT be implemented in NZ SAMS.

658 - 661

<NameIDFormat> elements MAY be specified. If so, they must list all name identifier formats supported by the entity.

Deployment guidance: All use cases to date support the use of federated identifiers. Therefore the urn:...:nameid-format:persistent format must be listed if the <NameIDFormat> element is used in the metadata.

690 - 693

If a Single Sign On Service is supported at the site, a <SingleSignOnService> element MUST be specified for NZ SAMS compliance.

694 - 697

If Name ID Mapping is supported at the site, a <NameIDMappingService> element MUST be specified for NZ SAMS compliance.

698 - 701

<AssertionIDRequestService> element MUST NOT be specified in all SAML message instances in NZ SAMS.

702 - 704

The <AttributeProfile> element MAY be specified in applicable SAML metadata instances in NZ SAMS.

Deployment guidance: Only the Basic Attribute Profile is to be used in NZ SAMS when applicable. Many SAML products do not put their supported attribute profiles in their generated metadata, contrary to best practice.

705 - 709

The <saml:Attribute> element SHOULD NOT be specified in applicable SAML metadata instances in NZ SAMS.

Deployment guidance: Very few, if any, products include this in their metadata. An Attribute Authority might support thousands or millions of attributes that could be retrieved, rendering listing as impractical.

748 - 751

<AssertionConsumerService> element MUST be specified in all Service Provider agency initiated SAML metadata instances for NZ SAMS compliance.

752 - 756

777 - 817

<AttributeConsumingService> element MUST NOT be specified for NZ SAMS.

Deployment guidance: In the All-of-government Authentication Programme, the GLS will NOT be generating attribute statements in the SSO assertions. No other use cases to date have pointed to the need for these elements in metadata since the IdP would not be able to return them as part of the SSO exchange. The usage patterns supporting the need for NameIDMapping (involving attribute exchange) calls for the use of the SOAP binding. Therefore the SP will never need a service for receiving attributes by way of other bindings such as HTTP POST.

The <AttributeConsumingService> element within an <SPSSODescriptor> is only used to indicate to an IdP that when creating a web SSO assertion for that SP, the IdP (e.g. GLS) should/must include SAML AttributeStatement(s) in the web SSO assertion it sends to the SP. But the GLS will NOT actually provide identity attributes for the service user. Even in the usage pattern requiring the use of NameIDMapping, after a service user logs in at the GLS, the querying SP will ask GLS for a mapped name ID so it can then make a separate <AttributeQuery> request to another entity (e.g. the proposed IVS) for that mapped name ID. In this role the IVS acts in the role of an Attribute Authority. But the querying SP's <SPSSODescriptor> has nothing to do with the attribute query it makes to the IVS.

When a querying SP makes the attribute query to another entity (e.g. the proposed IVS), it is operating in the role of a "query client". However, the SAML 2.0 Metadata Specification does not define this role (see section 5.5 of NZ SAMS for further discussion). A draft document is currently before the OASIS SSTC that defines such a role as a metadata extension, but it is not yet standardised. This is the role descriptor where an <AttributeConsumingService> could be defined for the query SP.

In a query/response use case, however, the client's metadata information is not all that useful anyway. It is useful in the web SSO case since an attribute consuming service "index" can be attached to the service and then the SP can use the index in an <AuthnRequest> to an IdP. The IdP then looks at the SP's metadata for the index to determine the specific set of SAML attributes that the SP wants returned in the SSO assertion. In the query case, the SAML <AttributeQuery> does not support the use of an index. The client query must explicitly list the attributes it needs from the Attribute Authority in the actual query. Local policy at the Attribute Authority then determines whether the authority will honour the query.

2.5 Element <AffiliationDescriptor>

Ignore. This element MUST NOT be specified in NZ SAMS (at least in the first release) since there are many misconceptions about the use of this element.

Signature Processing

1170 - 1171

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

Deployment guidance: Only the root element (<EntitiesDescriptor> or <EntityDescriptor>) of the metadata XML instance document can be signed in NZ SAMS implementations.

1194

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

Deployment guidance: Exclusive Canonicalisation is the only mechanism that has received any interoperability testing. It is supported by all products. There are few, if any, interoperable solutions that use standard canonicalisation.

3.1.4 Transforms

1203

"MAY" in this sentence becomes "SHOULD".

3.1.5 KeyInfo

1208 - 1211

This element MUST be specified in NZ SAMS.

Deployment guidance: Most vendor products expect <KeyInfo> to be present in the metadata file if the metadata is signed. Some vendor products can deal with it being exchanged out of band, but not all.

Metadata Publication and Resolution

1229 - 1241

Ignore this section. As noted in the introduction to this section, Metadata Publication and Resolution MUST NOT be specified in NZ SAMS.

Deployment guidance: Metadata Publication Resolution is NOT universally supported in vendor products (especially the DNS DDDS-style of publication). Metadata Publication/Resolution is most useful for automatic/dynamic establishment of associations between the partners. It is unlikely to attract significant numbers of SAML v2.0 deployments. Instead, metadata files are typically created and exchanged out of band between co-operating partners and then imported into the local system to configure interaction with the partner. This provides significantly better administrative control over system configuration and prevents partners from making a change that breaks interoperability. When published Metadata is not used, the cacheDuration attribute is unnecessary; validUntil might still be useful (e.g. to remind an administrator to check a partner's configuration), although systems may not check it after the partner's configuration is locally established.