Legacy File(s): conf/attribute-resolver.xml
Current File(s): conf/saml-nameid.xml, idp.properties, system/conf/saml-nameid-system.xml
Format: Native Spring / Legacy Custom Schema
Formally this is the configuration of the "NameIdentifierGeneration" service.
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.
You might modify this file to:
- add support for more application-oriented NameID types, such as email addresses
The 3.0 IdP supports a new dedicated service for configuring NameID generation, and the legacy 2.x approach of encoding attributes into identifiers using attribute-resolver.xml and special attribute encoders that generate NameIdentifiers or NameIDs instead of Attributes.
The IdP should load any existing 2.x attribute-resolver.xml file and configure itself in an expected manner, but that configuration will be superseded by the content of the new saml-nameid.xml file and will fall back to the resolver only as a backstop. You can short-circuit the new functionality by commenting out the content of the two generator lists.
The use of the legacy attribute encoders is deprecated in this release, and deployers are urged to migrate their configurations to native Spring syntax after or while upgrading.
A point of note is that unlike in 2.x, the transient or persistent identifiers produced by the generation service are not treated as attributes and are not release-controlled via an attribute filter. Rather, transients are viewed as harmless (because they are merely one-time values) and persistent identifiers cannot be generated without configuring an appropriate source attribute or other properties, so cannot be generated by default.
The configuration defines two beans that must have the following names:
Each is a Spring list containing any number of generator plugins of the appropriate SAML version. 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, and then attempting each one until one is obtained. The Format determination is based on combining the SP's request, its metadata, and the
nameIDFormatPrecedence property, if set for the matching relying party configuration. Default Formats are set via idp.properties in the event that nothing else is called for.
The default configuration includes generators for transient identifiers, and for SAML 2, persistent identifiers. These plugins are configured using idp.properties that control the strategies used to generate and store the values.
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 mirrors the older approach of encoding attributes, but separates the two operations in the configuration. This plugin also has the capability, unlike the resolver-based approach, of selecting the first value from a set of possible source attributes.
The impact of this default is such that IF the source attribute ("email" in the example) were to be released to an SP, AND the Format determination were to result in the "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" Format being selected, then the assertion's subject would contain an email-based value instead of a transient. This is not deemed harmful as a default because it requires explicit non-default behavior to achieve, and the data disclosed is an attribute already released to that SP.
So in summary, if you want transients, do nothing. If you want persistent pair-wise values, set the appropriate idp.properties. If you want custom values based on an attribute, configure one or more copies of the example bean appropriately and release the underlying source attribute(s).
Properties are defined to customize various aspects of default identifier generation behavior, particularly with respect to transient and persistent identifiers. The default method for generating transient IDs is based on the use of a secret key. We do not have installation support yet for generating the random encryption key, so be aware that unless you change the key yourself, it's a dummy key.
You can switch the transient strategy to generate values tracked by server-side storage (this makes them shorter, but requires cross-node storage approaches if SOAP-based messages such as attribute queries need to be supported).
You can also toggle between a hash-based generator of persistent IDs, or a storage-backed approach that hash-generates the first value for a user/SP combination but stores the result. These are fully compatible with 2.x strategies.
Finally, you can disable legacy support for encoding identifiers out of the attribute resolver, and you can override the default Formats to use when nothing else is specified.