wiki:Software/Configuration/ExtraPrincipalInfo

Version 10 (modified by smartp@…, 7 years ago) (diff)

--

How To: Configure Raptor to Gather extra information about your users

When the MUA receives events from authorised ICAs, the following additional information can be added (this is denoted Attribute Association in Raptor):

  • The name of the school (or more generally department) that the subject of the event is associated with.
  • The type of affiliation the subject of the event has with the organisation e.g. staff member, student, researcher etc.

Enabling Attribute Association

The MUA comes configured with both shibboleth and ezproxy event attribute association configurations disabled in the conf/attribute-association.xml file. To enable both configurations, the following code fragment should be uncommented.

Uncomment one or both of the shib and ezproxy attribute association definitions,e.g. from:

    <bean id="attributeAssociationEngine" class="uk.ac.cardiff.raptor.event.expansion.AttributeAssociationEngine">
        <property name="attributeAssociationDefinitions">
            <list>
               <!--  <ref bean="shibPrincipalAttributeAssociationDefinition"/>-->
               <!-- <ref bean="ezproxyPrincipalAttributeAssociationDefinition"/>-->
               <ref bean="shibResourceCategoryAttributeAssociationDefinition"/>
             </list>
        </property>
    </bean>

to

 <bean id="attributeAssociationEngine" class="uk.ac.cardiff.raptor.event.expansion.AttributeAssociationEngine">
        <property name="attributeAssociationDefinitions">
            <list>
               <ref bean="shibPrincipalAttributeAssociationDefinition"/>
               <ref bean="ezproxyPrincipalAttributeAssociationDefinition"/>
               <ref bean="shibResourceCategoryAttributeAssociationDefinition"/>
             </list>
        </property>
    </bean>

Of note here, the resource category attribute association should remain, as this attaches the internal or external resource type tag to each event, see ?? for more information.

Configuring Attribute Association Definitions

Raptor comes pre-configured with two attribute association definitions, one for attaching school and affiliation information to Shibboleth events, and the other for similarly attaching school and affiliation to Ezproxy events. In order for them to work for your organisation, you will need the following:

  • An Identity Management system that can be accessed using LDAP e.g. eDirectory, Active Directory etc. or OJDBC e.g. a relational database.
  • The principal name acquired from the log file stored in each event (often a users username) must match to their records in the Identity Management system. For example, if the principal name in the Shibboleth log file was 'bob', then the value of 'bob' must be attached to a suitable searchable attribute in your Identity Management system.
  • A suitable LDAP search filter or SQL query that can acquire users and their attributes from your Identity Management system. For example, an LDAP search filter that searches by ObjectClass and Common Name:
    (&(ObjectClass=eduPerson)(cn=[principalName]))
    
    Or, an SQL query that matches on common name:
    select * from idman.identities where cn = [principalName]
    
  • A suitable attribute in your Identity Management system that holds the users School (or department) and or the users Affiliation to your organisation.

If you think you can satisfy the above criteria, then you can enable either one or both of the attribute association definitions. To configure them, you will need to change three fragments of XML:

  1. The searchTemplate property needs to reflect the LDAP search filter or SQL query you will use to retrieve users from your Identity Management system, e.g. for LDAP:
    <property name="searchTemplate"><value>cn=[principal]</value></property>
    
    When adding a search template, you must place the literal string [principal] where you would like the users principal name to be inserted - the substitution is then done automatically by Raptor for each event that passes through the attribute association definition. Furthermore, as the filter is written in an XML, certain special characters must be escaped using their entity name (see the Predefined entities in XML section of the Wikipedia article http://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references) . For example, the search filter (&(ObjectClass=Person)(cn=[principalName])) should be written (&amp;(ObjectClass=Person)(cn=[principalName]))
  2. Once the attribute definition has acquired attributes about a user it then maps a specified set of those attributes it receives onto the internal model attributes School and Affiliation. This mapping is achieved by configuring the lookupAttributes property on each Attribute Association Definition. For example, if your Identity Managment systems stores school information in the attribute ou, and affiliation in the eduPersonAffiliation attribute from LDAP, then the lookupAttributes property would be defined as.
    <property name="lookupAttributes">
                <list>
                    <bean class="uk.ac.cardiff.raptor.event.expansion.AttributeLookup">
                        <property name="sourceAttributeName"><value>eduPersonAffiliation</value></property>
                        <property name="internalAttributeName"><value>affiliation</value></property>
                    </bean>
                     <bean class="uk.ac.cardiff.raptor.event.expansion.AttributeLookup">
                        <property name="sourceAttributeName"><value>ou/value></property>
                        <property name="internalAttributeName"><value>school</value></property>
                    </bean>
                </list>
      </property>
    
    Of note, you can remove one of the AttributeLookup definitions if you do not required it e.g. if the affiliation attribute is not mapped, you would remove that bean definition:
    <property name="lookupAttributes">
                <list>
                     <bean class="uk.ac.cardiff.raptor.event.expansion.AttributeLookup">
                        <property name="sourceAttributeName"><value>ou/value></property>
                        <property name="internalAttributeName"><value>school</value></property>
                    </bean>
                </list>
      </property>
    

Finally, you need to setup your LDAP connection.

LDAP Connection Parameters

Toward the bottom of the conf/attribute-association.xml file the LDAP data connector is defined. In order for the connector to connect to your LDAP directory, the following properties must be set appropriately for your enviroment:

 <property name="ldapUrl"><value>LDAP_URL</value></property>
<property name="ldapBaseDn"><value>BASE</value></property>
<property name="principal"><value>PRINCIPAL</value></property>
<property name="principalCredential"><value>PASSWORD</value></property>

The property cacheResults allows you to enable or disable the LDAP cache. That is, as each LDAP query is returned, the principal name and its attributes are stored in a cache, so that future requests for that principal name are then taken from the cache, and are not re-acquired through your LDAP connection (saving time). The cacheTimeoutMs property tells the cache when it should expire (all cached entries are removed). Currently this is set at 1 day. It is important that the cache does expire, otherwise you risk associating out of date information to events e.g. the users school or department has changed, but the cached value refers to an older state of your Identity Management system.

In addition, if your directory contains Referrals (similar to an alias) you may find an error message in the mua logs: ' An error occurred when attempting to search the LDAP Unprocessed Continuation Reference(s)' . To allow these to be dereferenced by the LDAP connector, you need to configure the following property (again in the LDAP data connector bean)

<property name="linkDereferencing"><value>true</value></property>

RDBMS Connection Parameters (v1.0.0 or greater only)

If you wanted to use an RDBMS instead of LDAP (only available in version >= 1.0.0 of Raptor), you need to uncomment the bean named databaseConnector at the bottom of the attribute-association.xml file, e.g. uncomment the bean:

  <bean id="databaseConnector" class="uk.ac.cardiff.raptor.event.expansion.connector.RDBMSDataConnector">         
         <property name="cacheResults"><value>true</value></property>
         <property name="cacheTimeoutMs"><value>86400000</value></property>
         <property name="dataSource">
            <bean id="dataSourceConnectionProperties" class="org.apache.commons.dbcp.BasicDataSource">
                <property name="driverClassName" value="org.postgresql.Driver"/>
                <property name="url"  value="jdbc:postgresql://localhost/identities"/>
                <property name="username"  value="postgres"/>
                <property name="password"  value=""/>
            </bean>
         </property>
    </bean>

Then, similar to the LDAP connector above, you need to configure the properties of the data connector to suite your environment.

Once configured, the data connector must be attached to the AttributeAssociationDefinitions (e.g. shibPrincipalAttributeAssociationDefinition and or ezproxyPrincipalAttributeAssociationDefinition) by changing their property:

<property name="dataConnector"><ref bean="ldapDataConnector"/></property>

to reference the databaseConnector:

<property name="dataConnector"><ref bean="databaseConnector"/></property>