File(s): conf/attribute-resolver.xml, idp.properties
Format: Custom Schema
Attribute resolution is about specifying how attributes are to be constructed and then encoded prior to being sent on to a relying party.
You can exercise and debug the behavior of this process using the AACLI tool or the web interface it uses. This is particularly helpful if you're making changes, performing upgrades, etc., to validate the results match in any given case.
In a typical (and default) configuration, only one configuration resource is supplied for controlling attribute resolution, a file called attribute-resolver.xml. All such resources must contain a "root" element named
> defined in the
urn:mace:shibboleth:2.0:resolver XML namespace (exactly the same as in V2).
The example below includes an
xsi:schemaLocation attribute that should allow for use of XML-aware editors, but there is no runtime dependency on the web server hosting those schemas.
Formally, this is the configuration of the "AttributeResolver" service. By default one file, attribute-resolver.xml, defines the attributes to be resolved. Multiple files can be specified by editing the bean referred to by the property
idp.service.attribute.resolver.resources (default value
shibboleth.AttributeResolverResources in the services.xml file) or changing the property to a different bean name.
The attribute-resolver.xml file can also use property replacement to externalize particular settings such as passwords. By default, these properties are defined in the idp.properties file, or you may define your own property files via the idp.additionalProperties setting. See the SpringConfiguration topic for more on property syntax.
The properties which affect the resolution process are names starting with
idp.service.attribute.resolver as described here
Most elements described in this page and its children are defined in the
urn:mace:shibboleth:2.0:resolver namespace, the schema for which is located at http://shibboleth.net/schema/idp/shibboleth-attribute-resolver.xsd
|any||Defines connections to sources of data which provide input to attribute definition. These data sources are usually external (databases or attribute stores)|
|any||Defines the actual atributes and any associated encodings into SAML or other formats|
|any||Deprecated in V3 and replaced by the mechanisms described under NameIDConsumptionConfiguration. Refer to the V2 documentation for details on the use of this legacy mechanism.|
The top level
> element has one attribute '
id' which is used purely for logging purposes. Child elements can have various attributes; these are described in the appropriate section describing that element.
The overall content and structure is identical to V2. Sematically, the V3 IdP is nearly 100% compatible with V2 attribute configuration. All regressions should be reported via our issue tracker.
Some key exceptions are noted below.
The next major version of the IdP will remove this guarantee, and indeed V2 configuration will not work unchanged in V4. It is an aim (but not a guarantee) that any configuration which loads without warning in IdP 3.4 will load in V4. See this page for details.
One exception to this compatibility is the Scripted Attribute Definition, where there are inherent limitations supporting more complex scripts, and most existing scripts will be relying on deprecated interfaces. In practice, most existing scripts doing routine things will work unchanged, but more advanced scripts may require modification.
In V2, the value collections exposed were literal object types (e.g. String) and null values in an underlying data source were represented as Java nulls (Java collections typically allow null elements). In V3, the values of an IdPAttribute are implementations of an interface, IdPAttributeValue, that wraps the underlying value. In the case of nulls or empty strings, an explicit type, EmptyAttributeValue, is used.
Identifying Source Attributes in Dependencies
The configuration language has a flaw in that the
sourceAttributeID is always optional, but is very ambiguous in different situations. It should have been placed within the
<Dependency> element but wasn't. As a result, it's either potentially ambiguous if all the depencies are themselves attribute definitions or explicitly needed if the dependencies are data connectors. Attribute definitions only produce a single attribute (so a dependency on them doesn't need further qualification), while data connectors can produce multiple attributes, with the source ID needed to disambiguate which one is meant as an input.
In V2, it was possible to omit the
sourceAttributeID attribute when using data connector dependencies. While this may behave consistently if a connector produces only one attribute, it becomes underspecified if the connector is later modified to produce more than one. As of V3.2.0, this is no longer allowed and a warning will be emitted, and the resolution process will fail. You will need to specify an appropriate
sourceAttributeID to correct the problem.
As of V3.4, all use of
sourceAttributeID is fully deprecated, and the old
<Dependency> element itself has been replaced by explicit use of
<InputDataConnector> elements. Most of the examples have been updated to reflect this syntax.
XML Namespaces 3.3
In all versions prior to V3.3, the configuration will contain elements in multiple namespaces. With V3.3, every non-deprecated feature can be defined in the main
urn:mace:shibboleth:2.0:resolver namespace (and thus defaulted to avoid the need for prefixes). The lone exception is the specification of security credentials when connecting to data sources (LDAP mainly).
Apart from the namespaces, nearly all names used have not changed. Hence, for example
can be rewritten
The two exceptions are the Scripted Data Connector and the Scripted Attribute definitions, where the name has been extended and so
xsi:type="dc:Script" should be replaced by
xsi:type="ad:Script" should be replaced by
New Capabilities for V3
- Activation Conditions on Attribute Definitions, Data Connectors and Attribute Encoders
- External Spring Configuration of LDAP, RDBMS, and StoredIdConnector connection details
A full list of configuration deprecation is available here
The use of attribute-resolver.xml to define external-to-internal subject mapping is deprecated. This function is now independent of the resolver, and is described in NameIDConsumptionConfiguration.
By default during upgrades (but not with a fresh install), any
<PrincipalConnector> elements will be parsed and handled correctly, however deployers are advised to migrate to the newer approach to simplify upgrades to future releases.
The use of attribute-resolver.xml to handle encoding attribute data into SAML subject identifiers (i.e., the encoder types
SAML2StringNameID) has been deprecated. This function is now independent of the resolver, and is described in NameIDGenerationConfiguration.
By default during upgrades (but not with a fresh install), these legacy encoders will be parsed and handled correctly, however deployers are advised to migrate to the newer approach to simplify upgrades to future releases.
Transient Identifier Attribute Definitions
The use of attribute-resolver.xml to define Transient (per-session) identifiers (and eventual encoding by the encoder types
SAML2StringNameID) is deprecated. This function is now independent of the resolver, and is described in NameIDGenerationConfiguration and NameIDConsumptionConfiguration.
By default, any
<AttributeDefinition> elements of types
ad:CryptoTransientId will be parsed but generally will be superseded by the features described in NameIDConsumptionConfiguration, and the older definitions can and should be removed.
PrincipalAuthenticationMethod Attribute Defintion
PrincipalAuthenticationMethod attribute defintion is deprecated because the support for managing multiple authenitcation methods throughout the IdP makes it impractical to expose a single method value.
Dependency Element and sourceAttributeID XML Attribute
V3.4 has corrected some ambiguities surrounding this element with the new
<InputDataConnector> elements, and replaces the old
sourceAttributeID setting. Note that
sourceAttributeID is ignored once you convert to the newer dependency element syntax, so carefully consider which input data is meant to be consumed by the containing definition.