Attribute Resolver

Attribute Resolver is a module of Shibboleth to discover user's attributes. The resolver has various plugins to connect to different data sources such as JNDI (LDAP) or JDBC (database). Additional plugins are also supported, such as flat file connector (FileDataConnector^?) can be added to the system.

It is important to note that all attributes required to be processed by Shibboleth has to be declared and resolvable by the resolver. These attributes may not necessarily be released in the ARPs. This fact is particularly important when ShARPE's mapping functionalities are used since a set of attributes may be referenced in the mapping to form one releaseable attribute mentioned in ARPs.

It is recommended that for the Testbed Federation, institutions interested in setting up an IdP should first ensure that they have an enterprise-wide accessible LDAP. In the following section we will focus on configuring the resolver for an LDAP.

Data Connectors

A data connector, as the name suggests, provides the connection to an attribute store where the Attribute Authority can retrieve attribute(s). You can define multiple data connectors in your resolver file to represent fetching different attributes from different attribute stores.

From the Shibboleth documentation, the JNDIDirectoryDataConnector^? that is used to connect an LDAP has the following options:

   id = <string>
       Specifies a unique, textual name for the connector used by attribute definitions to refer 
       to and use it to build attributes. Contained within the JNDIDirectoryDataConnector element.

   <Property name="<name>" value="<value>"/>
        An element of the element JNDIDirectoryDataConnector. Specifies a set of name/value pairs 
        that are used to configure the JNDI Directory Context. This list of name/value pairs is defined
        by the context itself, but is specified within resolver.xml.

   <Search> 
        An element of the element JNDIDirectoryDataConnector. This element defines the DN filter 
        used to perform the LDAP search. The search string must return no more than one result.

   <Controls> 
        An element of the element Search. This element grants some fine-grained control over the LDAP API calls.

   <cacheTime "<seconds>"/> 
        An element of the element JNDIDirectoryDataConnector. Specifies an optional duration in seconds 
        for which the attribute resolver may cache information retrieved from this connector. 
        The default is zero seconds (no caching) 

For example, assume we have an LDAP directory with the following settings:

• LDAP host: idp-ldap.mams.org.au
• LDAP port: 389 (non-ssl)
• Bind DN: uid=binduser,ou=demo,dc=mams,dc=org,dc=au
• Password for binding to the LDAP: test
• Base DN to search for users: ou=demo,dc=mams,dc=org,dc=au
• Users are identified by their "uids"

A JNDIDirectoryDataConnector^? for the above would look like:

        <JNDIDirectoryDataConnector id="directory">
                <Search filter="uid=%PRINCIPAL%">
                        <Controls searchScope="SUBTREE_SCOPE" returningObjects="false" />
                </Search>
                <Property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory" />
                <Property name="java.naming.provider.url" value="ldap://idp-ldap.mams.org.au/ou=demo,dc=mams,dc=org,dc=au" />
                <Property name="java.naming.security.principal" value="uid=binduser,ou=demo,dc=mams,dc=org,dc=au" />
                <Property name="java.naming.security.credentials" value="test" />
        </JNDIDirectoryDataConnector>

Attribute Definitions

Attributes that are available to be fetched by the Attribute Authority are defined by the SimpleAttributeDefinition elements. From the Shibboleth documentation, the SimpleAttributeDefinition has the following options:

   id = <string> 
        Specifies a unique, textual name for the attribute which is used as the attribute's name
        when it is sent over the wire by Shibboleth. Contained within the !SimpleAttributeDefinition
        element.
    
   <AttributeDependency / DataConnectorDependency requires="<id>"/> 
        An element of the element !SimpleAttributeDefinition, which may contain 0 or more of either 
        AttributeDependency or DataConnectorDependency. These specify attributes and data
        connectors that can be utilized by this attribute definition. Each of these elements must 
        contain a requires statement which this attribute definition can then use to build its value.
    
   smartScope = "<domain>" 
        Specifes a domain scope to be attached to the attribute. If the value of the attribute as 
        retrieved from the data connector includes a pre-existing scope (bob@foo.edu), that scope 
        is used instead. Contained within the !SimpleAttributeDefinition element.

   <lifeTime "<seconds>"/> 
        Specifies in the attribute assertion how long the attribute should be cached and retained by 
        the target upon receipt. Federations and trust agreements may have some bearing on the 
        population and use of this field. Contained within the !SimpleAttributeDefinition element.

   sourceName = "<string>" 
       Specifies a different source attribute name to be used in calls to the data connector, 
       while the name on the wire will be the specified id. This would be useful to send a local
       UniversityID attribute as eduPersonPrincipalName. If not supplied, the connector tokenizes
       the id field and uses the section following the # to query data connectors. Contained within
       the !SimpleAttributeDefinition element.

   <cacheTime "<seconds>"/> 
       Specifies an optional duration in seconds for which the attribute resolver may cache this 
       attribute for use in additional assertions. Contained within the !SimpleAttributeDefinition element. 

An example of a SimpleAttributeDefinition for the eduPersonPrincipalName is below:

    <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonPrincipalName"
      smartScope="mams.org.au" cacheTime="600" lifeTime="3600" sourceName="universityPerson">
      <DataConnectorDependency requires="directory"/>
      <AttributeDependency requires="mqUsername"/>
    </SimpleAttributeDefinition>
    <SimpleAttributeDefinition id="mqUsername"
      smartScope="mams.org.au" cacheTime="600" lifeTime="3600">
      <DataConnectorDependency requires="oracleDB"/>
    </SimpleAttributeDefinition>

It is important to note that there must be a data connector defined with the id "directory" in order for this attribute to be resolved. Furthermore, eduPersonPrincipalName depends on the definition of "mqUsername" which will be queried on another dataconnector "oracleDB" (oracle database). The outcome of eduPersonPrincipalName is the combination of the two:

  eduPersonPrincipalName <------universityPerson <------- directory <------- datasource (i.e. LDAP)
                           ^
                           |
                           L---mqUsername <-------------- oracleDB <-------- datasource (i.e. oracle)