The <AttributeDecoder> element configures the component used to process the content of a SAML element undergoing extraction.

The decoder plugin is responsible for instantiating an object that subclasses the required internal class interface, while capturing any data necessary to properly expose the extracted value(s) to the SP and protected applications. It is the decoder plugin that actually understands how to process an attribute's values.

Common Attributes

String AttributeDecoder

Indicated by xsi:type="StringAttributeDecoder", treats the SAML attribute's values as a simple string. No additional processing is done.

Scoped AttributeDecoder

Indicated by xsi:type="ScopedAttributeDecoder", treats the SAML attribute's values as a two-part relational construct consisting of a left-hand side (the "value") and a right-hand side (the "scope").

During processing, both halves are tracked independently and exposed either as a flattened string or individually, depending on how the object is being used.

Typically, an attribute's scope gives an indication of the domain in which an attribute's value applies; for example, staff@example.org represents a staff member at Example Organization, and the scope is example.org. However, it may not be desirable to allow staff@osu.edu to be asserted by the Brown University IdP. The specialized processing of this decoder facilitates these kinds of distinctions.

With Shibboleth 2.0, scoped attribute processing accomodates multiple XML syntaxes for passing scoped values, including the legacy form supported by Shibboleth 1.x and parsing strings containing an arbitrary delimiter.

Attributes

NameID AttributeDecoder

Indicated by xsi:type="NameIDAttributeDecoder", processes SAML attribute values that take the form of a <saml:NameIdentifier> or <saml2:NameID> element (or the equivalent schema type).

Since SAML identifiers are complex XML types that include XML attributes as well as content, a formatting string must be supplied to instruct the system how to represent the value internally as a flattened string, when necessary.

For historical reasons, the various parts of the XML structure are traditionally concatenated using !!, but any kind of formatting is possible.

<AttributeDecoder xsi:type="NameIDAttributeDecoder" formatter="$Name!!$NameQualifier!!$SPNameQualifier"/>

Attributes

NameIDFromScoped AttributeDecoder (Version 2.1 and Above)

Indicated by xsi:type="NameIDFromScopedAttributeDecoder", combines the features of the "Scoped" and "NameID" decoders above by processing values in "scoped" syntax, but returning a NameID-formatted value. Used for application compatibility by mapping different input syntaxes into one output format.

Attributes

KeyInfo AttributeDecoder (Version 2.2 and Above)

Indicated by xsi:type="KeyInfoAttributeDecoder", processes SAML attribute values that take the form of a <ds:KeyInfo> element (or the equivalent schema type).

Its current capability is to rely on a KeyInfoResolver plugin to transform the input data into a public key, after which it is DER-encoded into its SubjectPublicKeyInfo form and then base64-encoded.

Attributes

Child Elements

XML AttributeDecoder (Version 2.2 and Above)

Indicated by xsi:type="XMLAttributeDecoder", processes SAML attribute values by directly serializing them as XML and storing them in that form. If exported through the CGI interface, the serialized XML is base64-encoded for that purpose.

DOM AttributeDecoder (Version 2.2 and Above)

Indicated by xsi:type="DOMAttributeDecoder", processes SAML attribute values as an arbitrary XML DOM tree.

This plugin is a somewhat experimental attempt at providing limited support for "rich" XML-valued attribute information. It works best on XML structures without embedded "repeating" elements. Only limited support for accessing the iterated data is included.

The main limitation of this mechanism is that for the SP to provide a useful function, it has to be able to simplify the XML into a string. Otherwise the application might just as well parse the SAML assertion directly, and that may often be the better approach. However, if the XML structure is sufficiently simple, the decoder plugin offers the ability to pull information out of it using a quick and dirty notation as follows:

  1. XML attributes and child elements can be jointly accessed by specifying the attribute or element name (or its remapped name, see below).
  2. Nested elements can be navigated by separating parent and child with a period (.) character.
  3. Lists of repeating child elements can be indexed using the typical array notation ([n]) and the zero-based index of the child to access. Out of range accessors simply return nothing as a resulting string. A zero index is ignored if no list is present.
  4. If a list is encountered without an array index specified, the first element in the list is accessed automatically.

As an example, consider this rich SAML 1.1 attribute:

<saml:Attribute AttributeName="https://example.org/personalprofile" AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri">
    <saml:AttributeValue>
        <prof:Profile xmlns:prof="https://example.org/personalprofile">
            <prof:Name>
                <prof:First>John</prof:First>
                <prof:Last>Doe</prof:Last>
            </prof:Name>
            <prof:Email>doe@example.org</prof:Email>
            <prof:Email>jdoe@gmail.com</prof:Email>
        </prof:Profile>
    </saml:AttributeValue>
</saml:Attribute>

The following attribute declaration will produce a value of "John Doe, jdoe@gmail.com":

<Attribute name="https://example.org/personalprofile">
    <AttributeDecoder xsi:type="DOMAttributeDecoder" formatter="$Profile.Name.First $Profile.Name.Last, $Profile.Email.[1]"/>
</Attribute>

Attributes

Child Elements

Base64 AttributeDecoder (Version 2.4 and Above)

Indicated by xsi:type="Base64AttributeDecoder", processes SAML attribute values that are base64-encoded UTF-8 by decoding them back into UTF-8.

This decoder has no way to determine whether the underlying data is in fact UTF-8, so it should be used with trusted IdPs only and with caution. If the data is binary, it will be exposed to applications as raw octets up to the first null character in the decoded data.