NativeSPAddAttribute
By default, the SP ignores SAML information about users provided by the IdP unless you specifically tell it how and what to process. A variety of example mappings are supplied by default, but most of them are commented out to save processing time. For efficiency, it's suggested that you enable or define mappings for only the information your applications care about.
Following these steps will configure the SP to recognize a new attribute mapping for application or access control use, assuming the default mechanisms for handling attributes are used.
Extracting/Mapping the Attribute
The SP translates attributes that it receives on the wire, typically from SAML assertions, using an attribute extractor, typically via the attribute-map.xml configuraton file. The file contains a series of mapping rules that reference the "on the wire" representation and connect it to a more convenient short-hand.
To define a new mapping, one needs to add a new <Attribute>
element. The name
property in the rule corresponds to the formal SAML name the IdP is using for the attribute, generally a URI. The id
property is the shorthand name to use, and determines the environment variable or header by which the attribute will be made available to the web application.
<Attribute name="https://example.org/myAttributes/FavoriteFruit" id="favFruit"/>
If the IdP uses an AttributeNamespace
other than urn:mace:shibboleth:1.0:attributeNamespace:uri
(SAML 1.x), or a NameFormat
other than urn:oasis:names:tc:SAML:2.0:attrname-format:uri
or urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified
(SAML 2.0) then you must also include a nameFormat
attribute with the corresponding value.
<Attribute name="https://example.org/myAttributes/FavoriteFruit" id="favFruit" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>
Custom Decoders
For most attributes, a simple rule as above is sufficient, but if the attribute's values are more than simple strings, a custom <AttributeDecoder>
needs to be supplied inside the <Attribute>
element.
The most common examples you will encounter can be seen among the default rules supplied, specifically decoding of scoped or name identifier values.
Filtering (Optional)
By default, an attribute mapping will decode and pass along any values encountered. Normally this is adequate, but for advanced scenarios, special filtering rules can be applied to the values extracted. For example, a controlled vocabulary can be defined, or specific IdPs can be prevented from asserting an attribute.
Documentation on this feature is currently limited, but see the NativeSPAttributeFilter topic.
Using the Attribute
Once a mapping is created, the attribute's values, if any, will be available in an environment variable or header corresponding to the rule's id
and/or aliases
properties. Multiple values are separated by a semicolon, and semicolons in values are escaped with a backslash. The data should be interpreted as UTF-8, which is a superset of ASCII.
Externally to an application, you can utilize mapped attributes for static access control. Included with the SP are a pair of plugins, a cross-platform XML-based mechanism and support for Apache .htaccess.