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 name.
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.
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.
Example of a Simple String-valued Attribute with nameFormat
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.
It is rare that a decoder would need to be specified and if you don't understand why you would use one, you shouldn't waste time worrying about it or try to fix problems by using one. Something else is wrong.
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 Attribute Filter 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.