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
- Create a constructor that takes an
org.w3c.dom.Elementand be sure to call
- 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
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
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
This uses the Scriplet definition as if it were a custom definition to demonstrate using additional XML information to configure the connector.
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.
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
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