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.