Writing a Custom Attribute Definition

If the current attribute definitions do not meet your needs you may write a custom one. This is a fairly simple process:

Create a class that extends edu.internet2.middleware.shibboleth.aa.attrresolv.provider.BaseAttributeDefinition
Create a constructor that takes an org.w3c.dom.Element and be sure to call super(Element)
Implement the logic to fetch attribtues in the resolve(ResolverAttribute, Principal, String, String, Dependencies) method
Deploy your new definition within the !IdP; the extension mechanism provides a simple means to do this

By extending the BaseAttributeDefinition and calling its constructor it will take care of processing id, cacheTime, propagateErrors, and sourceName attributes as well as any DataConnectorDependency and AttributeDependency elements within your connector's configuration.

Attribute Definition Basics

All attribute definitions are configured in the IdP's resolver.xml file.

Basic Attributes

Each attribute definition supports the following basic XML attributes in their definition:

id - (required) used by the definition to determine its source, or input, attribute and by other definitions and data connectors to refer to this definition
sourceName - (optional) used to explicitly specify the name of the source, or input, attribute used by the definition

Source Attributes

Most attribute definitions transform other attributes. A definition will determine the name of its source attribute in the following way:

If sourceName is present use an attribute whose name exactly matches the given source name
Use an attribute whose name exactly matches the definitions id
Use an attribute whose name exactly matches the last token of the definitions id split on / or :

Configuring the Definition

Create a CustomAttributeDefinition element, with its id attribute, and the following attribute:
- class - the fully qualified name of your custom connector class
Define any additional XML attributes or elements required to configure your class

Example Configuration

This uses the Scriplet definition as if it were a custom definition to demonstrate using additional XML information to configure the connector.

< CustomAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonAffiliation"
    class="edu.internet2.middleware.shibboleth.aa.attrresolv.provider.ScriptletAttributeDefinition">
	 <DataConnectorDependency requires="directory"/>
	 <Scriptlet>
		  <![CDATA[
				Attributes attributes = dependencies.getConnectorResolution("directory");
				Attribute affiliation = attributes.get("eduPersonAffiliation");
				if (affiliation.size() > 0) {
					 resolverAttribute.addValue("affiliate");
				}
		  ]]>
	 </Scriptlet>
</CustomAttributeDefinition >

Attribute Definition Dependencies

In order to use attributes from data connectors or other definitions you need to make sure those dependencies are resolved before this definition is called.

If your definition depends on a data connector create a child element, of the main definition element, called DataConnectorDependency and give it an attribute of requires whose value is the id of the data connector this definition depends on.

If your definition depends on another definition create a child element, of the main definition element, called AttributeDependency and give it an attribute of requires whose value is the id of the definition this definition depends on.

Error Propagation

Not every attribute definition may, or need, work for every user in the system. However, the definition may emit an error if it is unable to find any entries for the user or if it depends on another data connector or definition that didn't apply to the current user.

To suppress these errors, so that they don't stop the attribute lookup process, add the follow attribute and value to the main definition element:

propagateErrors - with a value of false

Data Caching

Attribute definitions cache their information for the length of one attribute request; until all data connectors and definitions have been evaluated and their information retrieved. You may optionally have the definition cache its data for a fixed period of time. This can increase performance but will result in a lead time for frequently changing data.

To enable this longer-lived cache add the following attribute to the main connector element:

cacheTime - the length of time, in seconds, to cache the attributes fetched by this definition