NameIDGenerationConfiguration

Current File(s): conf/saml-nameid.xml, conf/saml-nameid.properties
Format: Native Spring

1 Overview
2 Generators
- 2.1 Format Selection
- 2.2 Transient Identifier Generation
- 2.3 Persistent Identifier Generation
- 2.4 Custom Identifier Generation
3 Reference

Overview

Generation of SAML NameIdentifier/NameID content is handled by the NameIdentifierGeneration service. See the NameIdentifiers topic for a general discussion of name identifiers and a list of specific examples.

The saml-nameid.xml file is used to control the generation of SAML 1 NameIdentifier and SAML 2 NameID content. SAML assertion subjects contain a special slot for an identifier that is less commonly used in Shibboleth deployments (because SAML Attributes are more general and useful) but is very commonly used by vendors seeking to do the bare minimum necessary to support SAML.

When interoperating with Shibboleth SPs, it's rare to need to modify this file, but you might need to do so to add support for more application-oriented identifier types, such as email addresses, or less commonly to enable support for so-called "persistent" identifiers, special privacy-preserving identifiers that are targeted to specific services.

Out of the box, the system is preconfigured to support, and default to, so-called "transient" identifiers, which are per-transaction and are primarily meant for use in the SAML Logout profile.

Generators

The saml-nameid.xml configuration file defines two list beans, each one an ordered list of "generator" plugins for the two different SAML versions. Each plugin is specific to an identifier Format, a SAML constant that identifies the kind of value being expressed. The generation process involves selecting a list of Formats to try and generate (see Format Selection below), and then trying each Format until an appropriate value is obtained by running each configured generator in order.

Since assertions need not contain a name identifier, it is not an error (from the perspective of the IdP) for all the generators to fail unless the original request contained a <NameIDPolicy> element with a Format attribute other than "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified". In that situation, failure to satisy the request results in a particular SAML response status. Note that most SP's asking for this don't mean to be doing it, and even fewer will be able to handle the resulting error.

The default configuration includes generators for "transient" identifiers. These plugins are configured using saml-nameid.properties to control the strategies used to generate and reverse-map the values (the latter only being necessary to support "back-channel" attribute queries).

In the case of SAML 2, a plugin is present, but commented out, to generate "persistent" identifiers. Certain properties in saml-nameid.properties must be set in order to safely uncomment this plugin (discussed below).

The default configuration also demonstrates how to generate a custom identifier using an arbitrary Format based on an attribute from the attribute resolution process. This plugin also has the capability of selecting the first value present from a list of possible source attributes.

In summary:

Support for "transient" identifiers is automatic.
If you want "persistent" / pair-wise support, see below.
If you want custom values, see below.

If you're getting unexpected results, approach the debugging from the perspective of the algorithm: identify which Formats should be getting tried (as indicated by the log), and examine each generator in order to see if it would be expected to produce a given Format.

Format Selection

For any given request, the ordered list of Formats to try to generate is based on combining the SP's request (SAML 2 requests can include a <NameIDPolicy> element that requires a particular Format), the <NameIDFormat> element(s) in the SP's metadata, and the nameIDFormatPrecedence profile configuration property, if set for the chosen relying party configuration.

If the metadata contains nothing, or contains the "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" value, then the metadata is ignored.

If a <NameIDPolicy> element with a Format attribute (other than that "unspecified" example) is supplied, then a suitable matching identifier MUST be generated or an error will be returned to the SP.

Otherwise the formats specified in an SP's metadata are filtered against a nameIDFormatPrecedence profile configuration property, if set, and the resulting set of Formats is tried in order. That is, the first Format in the profile configuration that is also in the metadata and that results in a valid result will be used.

Default Formats for each SAML version are set via saml-nameid.properties and are used in the event that nothing else is called for. You should not alter that setting in most cases.

Transient Identifier Generation

The strategy used to generate transient identifiers is controlled with the idp.transientId.generator property in saml-nameid.properties.

The default strategy is based on the use of a secret key, discussed in the SecurityConfiguration topic (see the idp.sealer.* properties). This maintains support for attribute queries without requiring shared state between a cluster of nodes, apart from sharing the secret key.

You can set this property to "shibboleth.StoredTransientIdGenerator" to generate random values tracked by server-side storage (this makes them shorter, but requires more complex storage approaches when clustering if attribute queries need to be supported).

Persistent Identifier Generation

See the PersistentNameIDGenerationConfiguration subtopic for detailed help with this feature.

Custom Identifier Generation

See the CustomNameIDGenerationConfiguration subtopic for detailed help with this feature.