Mapped Attribute Definition

A mapped attribute definition creates an attribute by mapping the values of another attribute definition or data connector to one or more different values. The following steps walk through creating a simple attribute definition.

1. Define the Definition

The definition is defined with the element <resolver:AttributeDefinition xsi:type="Mapped" xmlns="urn:mace:shibboleth:2.0:resolver:ad"> with the following required attribute:

id - assigns a unique, within the resolver, identifier that may be used to reference this definition

and the following optional attributes:

dependencyOnly - a boolean flag that indicates the attribute produced by this definition is used only by other resolver components and should not be released from the resolver (default value: false)
sourceAttributeID - the ID of the attribute, from the dependency connectors, used to construct this attribute (default value: ID of this attribute)

Basic Simple Attribute Definition

<resolver:AttributeDefinition xsi:type="Mapped" xmlns="urn:mace:shibboleth:2.0:resolver:ad"
                              id="UNIQUE_ID">

     <!-- Remaining configuration from the next step go here -->

</resolver:AttributeDefinition>

2. Define Dependencies

It is very common for one component, like attribute definitions, within the attribute resolver to depend on information retrieved or constructed from another component.

Dependencies are expressed by the <resolver:Dependency> with a ref attribute whose value is the unique ID of the attribute definition or the data connector that this connector depends on.

Basic Mapped Attribute Definition with Dependencies

<resolver:AttributeDefinition xsi:type="Mapped" xmlns="urn:mace:shibboleth:2.0:resolver:ad"
                              id="UNIQUE_ID">


     <resolver:Dependency ref="DEFINITION_ID_1" />
     <resolver:Dependency ref="DEFINITION_ID_2" />
     <resolver:Dependency ref="CONNECTOR_ID_3" />
     <resolver:Dependency ref="CONNECTOR_ID_4" />

     <!-- Remaining configuration from the next step go here -->

</resolver:AttributeDefinition>

3. Define Value Maps

The mapped attribute definition can contain one or more value maps which define the actual mapping to perform. Each <ValueMap> defines a many-to-one mapping of source values to a return value. Many-to-many mappings can be achieved by using multiple maps. Each <ValueMap> contains a single <ReturnValue> and one or more <SourceValue> elements. The source value strings are regular expressions that are matched against source attributes. If the source attribute matches, it is mapped to the return value. <ReturnValue> may contain regular expression back references to capturing groups in the source value.

Basic Mapped Attribute Definition with a Value Map

<resolver:AttributeDefinition xsi:type="Mapped" xmlns="urn:mace:shibboleth:2.0:resolver:ad"
                              id="UNIQUE_ID">

     <!-- Dependency and Failover information would go here -->
     
     <!-- DefaultValue configuration from the next step go here -->

     <ValueMap>
         <ReturnValue>RETURN_VALUE</ReturnValue>
         <SourceValue>SOURCE_VALUE_1</SourceValue>
         <SourceValue>SOURCE_VALUE_2</SourceValue>
         <SourceValue>SOURCE_VALUE_3</SourceValue>
     </ValueMap>

</resolver:AttributeDefinition>

Advanced Options

The <SourceValue> element also allows the following advanced configuration attributes controlling how matching is performed:

ignoreCase - boolean; if true, value matching will be case-insensitive; defaults to false. Incompatible with partialMatch.
partialMatch - boolean; if true, the <SourceValue> may match only a substring of the incoming value. Otherwise, it must match the entire value; defaults to false. This option is mutually exclusive with a regular expression based <SourceValue>.

4. Define Default Value

If a source attribute does not match any of the value maps, the <DefaultValue> will be returned if one is defined. The default value may not contain back references to regular expression capture groups. If you want the original source value to be passed through unmodified, set the <DefaultValue> attribute passThru equal to true. If no default value is defined, source values that do not match a value map will simply be dropped.

Example

Imagine the simple scenario in which you have a data store that contains an attribute myEduAffiliation. This attribute is populated with internal affiliation values for students and instructors, but you would like to map them to the controlled vocabulary used by eduPersonAffiliation. You might have a mapped attribute definition that looks something like this.

Example Mapped Attribute Definition using maps

<resolver:AttributeDefinition xsi:type="Mapped" xmlns="urn:mace:shibboleth:2.0:resolver:ad"
                              id="UNIQUE_ID"
                              sourceAttributeID="myEduAffiliation">

     <resolver:Dependency ref="myLDAP" />

     <!-- default to the generic value 'affiliate' -->
     <DefaultValue>affiliate</DefaultValue>

     <!-- map internal values like 'student-worker' and 'undergraduate' to 'student' -->
     <ValueMap>
         <ReturnValue>student</ReturnValue>
         <SourceValue>student-.+</SourceValue>
         <SourceValue>undergraduate</SourceValue>
     </ValueMap>

     <!-- map your internal 'instructor' value to 'faculty' -->
     <ValueMap>
         <ReturnValue>faculty</ReturnValue>
         <SourceValue>instructor</SourceValue>
     </ValueMap>

     <!-- students and instructors are also 'members' -->
     <ValueMap>
         <ReturnValue>member</ReturnValue>
         <SourceValue>student-.+</SourceValue>
         <SourceValue>undergraduate</SourceValue>
         <SourceValue>instructor</SourceValue>
     </ValueMap>

</resolver:AttributeDefinition>

You can also leverage the regular expression power of the mapped attribute definition without using the mapping functionality by simply defining only a single source value. For example, imagine you have a name attribute legalName that is of the form "Last, First". However, you'd like to release that attribute as displayName of the form "First Last".

Example Mapped Attribute Definition using regex

<resolver:AttributeDefinition xsi:type="Mapped" xmlns="urn:mace:shibboleth:2.0:resolver:ad"
                              id="UNIQUE_ID"
                              sourceAttributeID="legalName">

     <resolver:Dependency ref="myLDAP" />

     <!-- if the name is not in the expected format, just return it as-is -->
     <DefaultValue passThru="true" />

     <!-- convert 'LastName, FirstName' to 'FirstName LastName' -->
     <ValueMap>
         <ReturnValue>$2 $1</ReturnValue>
         <SourceValue>(.+), (.+)</SourceValue>
     </ValueMap>

</resolver:AttributeDefinition>