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

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

Deployment alignment
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 then only if there are multiple entities.

Deployment alignment
Normal practice for handling multiple NZ SAMS system entities is for each entity to simply handle its relevant metadata, i.e. only one <EntityDescriptor> element is used per entity and the <EntityDescriptor> element is the root node. This approach is more common and likely to be supported by SAML vendor implementations.

Deployment alignment
Attributes of <EntitiesDescriptor> are to be used 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 are to be used as follows:

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

Deployment alignment
Attributes of <EntityDescriptor> are to be used 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 SHOULD 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.

^{End of line 218}

<EntityDescriptor> child elements are to be used 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 used 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. Note that the precise usage of the organisation element is under submission to OASIS SSTC, as of March 2008.
• <ContactPerson>: NZ SAMS RECOMMENDS that one be included
• <AdditionalMetadataLocation>: MUST NOT be used in NZ SAMS.

Deployment alignment
Single log off is under active investigation by the All-of-government Authentication Programme architecture team.

Deployment alignment
Metadata is commonly generated by vendor products, hence limited or no control is offered over the generated metadata which may contain a default entry for <ManageNameIdService>.

Deployment alignment
All use cases to date support the use of federated identifiers. Therefore the urn:oasis:names:tc:SAML:2.0:nameid-format:persistent format must be listed if the <NameIDFormat> element is used in the metadata. This is dependent on the product implementations as not all SAML vendor implementations include supported Name Identifier Formats.

Deployment alignment
Single sign on is under active investigation by the All-of-government Authentication Programme architecture team.

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

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

Deployment alignment
In the All-of-government Authentication Programme, the proposed IVS is expected to generate attribute statements in the SSO assertions. No other use cases to date have pointed to the need for these elements in metadata and there is no specific mechanism to dynamically request from the IdP the required attributes (excluding the AttributeQuery).

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> element(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 <NameID> so it can then make a separate <AttributeQuery> request to another entity (e.g. the proposed IVS) for that mapped <NameID>.

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. Do note that the attribute set returned by the IdP, is entirely at the IdP's discretion. Hence the attributes requested initially may not be returned.

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 v2.0 Metadata Specification does not define this role (see section 5.5 of NZ SAMS for further discussion). A draft document is (at time of printing) before the OASIS SSTC that defines such a role as a metadata extension, but this is not yet standardised. This is the role descriptor where an <AttributeConsumingService> could be defined for the querying SP.

^{End of line 315}

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.

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

Signing of metadata is not supported by some SAML v2.0 implementations. Situations could also occur where vendor generated metadata will require manual alteration to interoperate with other implementations or comply with NZ SAMS. If metadata files are manually corrected the signature may no longer be valid. If either of these situations arise, 'direct' alternative means of SAML metadata is REQUIRED.

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

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

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

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