Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Next »

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

Format: Native Spring / Deprecated Custom Schema

Legacy V2 File(s): conf/attribute-resolver.xml

Overview

Generation of SAML NameIdentifier/NameID content is handled by the NameIdentifierGeneration service. A general discussion of SAML name identifiers can be found here.

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 to enable support for so-called "persistent" identifiers, which are special privacy-preserving identifiers that are targeted to specific services.

Generators

The configuration defines two list beans, each containing "generator" plugins for 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 to generate each one until a value is obtained by running each configured generator in order.

The Format determination is based on combining the SP's request (SAML 2 requests can include a <NameIDPolicy> element), the <NameIDFormat> element(s) in the SP's metadata, and the nameIDFormatPrecedence profile configuration property, if set for the matching relying party configuration. Default Formats are set via saml-nameid.properties in the event that nothing else is called for.

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 being necessary for attribute queries, primarily).

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.

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 V2 approach of encoding attributes, but more cleanly separates the two operations in the configuration. This plugin also has the capability, unlike the resolver-based approach, of selecting the first value present from a list of possible source attributes.

In summary, supporting "transient" identifiers is automatic. If you want "persistent" / pair-wise support, see below. If you want custom values based on an attribute, uncomment one or more copies of the example bean(s) appropriately and ensure the underlying source attribute(s) are released to the applicable relying party or parties.

Transient Identifier Generation

The default method for generating transient IDs is based on the use of a secret key, discussed in the SecurityConfiguration topic (see the idp.sealer.* properties).

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).

Persistent Identifier Generation

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.

Reference

Beans

Beans defined in saml-nameid.xml and related system configuration follow:

Bean IDTypeFunction

shibboleth.SAML2NameIDGenerators

List<SAML2NameIDGenerator>

SAML 2 NameID generator plugins to use

shibboleth.SAML1NameIdentifierGenerators

List<SAML1NameIdentifierGenerator>

SAML 1 NameIdentifier generator plugins to use
shibboleth.SAML2TransientGenerator
shibboleth.SAML1TransientGenerator
SAML2NameIDGenerator
SAML1NameIdentifierGenerator
Plugins for generating transient identifiers using pluggable strategies
shibboleth.StoredTransientIdGeneratorTransientIdGenerationStrategyStrategy plugin that generates transient identifiers randomly and stores them in a server-side StorageService
shibboleth.CryptoTransientIdGeneratorTransientIdGenerationStrategyStrategy plugin that generates transient identifiers by encrypting a subject identity into a long opaque string
shibboleth.SAML2PersistentGeneratorSAML2NameIDGeneratorPlugin for generating persistent identifiers using pluggable strategy
shibboleth.ComputedPersistentIdGeneratorComputedPersistentIdGenerationStrategyStrategy plugin that generates persistent identifiers with a salted hash of an input value
shibboleth.StoredPersistentIdGeneratorStoredPersistentIdGenerationStrategyStrategy plugin that generates persistent identifiers and stores them in a database
shibboleth.SAML2AttributeSourcedGenerator
shibboleth.SAML1AttributeSourcedGenerator
SAML2NameIDGenerator
SAML1NameIdentifierGenerator
Template beans for plugins that generate custom identifiers based on resolved and released attribute values
shibboleth.LegacySAML1NameIdentifierGenerator
shibboleth.LegacySAML2NameIDGenerator
SAML2NameIDGenerator
SAML1NameIdentifierGenerator
Plugins supporting deprecated use of attribute resolver configuration to produce and encode name identifiers

Properties

Properties are defined in saml-nameid.properties to customize various aspects of default identifier generation behavior:

PropertyTypeDefaultFunction
idp.transientId.generatorBean ID  
idp.persistentId.generatorBean ID  
idp.persistentId.storeBean ID  
idp.persistentId.computedBean ID  
idp.persistentId.sourceAttributeComma-delim'd List  
idp.persistentId.saltString  
idp.persistentId.algorithmString  
idp.nameid.saml2.legacyGeneratorBean ID  
idp.nameid.saml1.legacyGeneratorBean ID  
idp.nameid.saml2.defaultURIurn:oasis:names:tc:SAML:2.0:nameid-format:transient 
idp.nameid.saml1.defaultURIurn:mace:shibboleth:1.0:nameIdentifier 

V2 Compatibility

The V3 IdP uses a new dedicated service for configuring NameID generation. The legacy V2 approach of encoding attributes into identifiers using attribute-resolver.xml and special attribute encoders that generate NameIdentifiers or NameIDs instead of Attributes is supported for compatibility purposes, but is deprecated and may be removed from a future version.

The IdP should load any existing V2 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 list beans and leaving them empty.

Note that unlike in V2, the transient or persistent identifiers produced by the new V3 generation service are not treated as attributes and are not release-controlled via an attribute filter policy. 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.

Notes

TBD

  • No labels