Changes between Version 7 and Version 8 of Software/Configuration/ExtraPrincipalInfo


Ignore:
Timestamp:
12/12/11 21:53:39 (9 years ago)
Author:
smartp@…
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Software/Configuration/ExtraPrincipalInfo

    v7 v8  
    4141Raptor 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: 
    4242 
    43 * An Identity Management system that can be accessed using LDAP e.g. eDirectory, Active Directory etc. - although future releases will include other data connectors. 
     43* An Identity Management system that can be accessed using LDAP e.g. eDirectory, Active Directory etc. or OJDBC e.g. a relational database. 
    4444* 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. 
    45 * A suitable LDAP search filter that can acquire users and their attributes from your Identity Management system. For example, a filter that searches by !ObjectClass and Common Name: 
     45* 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: 
    4646{{{ 
    4747(&(ObjectClass=eduPerson)(cn=[principalName])) 
     48}}} 
     49 Or, an SQL query that retrieves attributes by a field that stores principal name: 
     50{{{ 
     51select * from idman.identities where cn = [principalName] 
    4852}}} 
    4953* A suitable attribute in your Identity Management system that holds the users School (or department) and or the users Affiliation to your organisation.   
    5054 
    5155If 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: 
    52 1. The {{{searchFilterTemplate}}} property needs to reflect the LDAP search filter you will use to retrieve users from your Identity Management system: 
     561. 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: 
    5357{{{ 
    54 <property name="searchFilterTemplate"><value>cn=[principal]</value></property> 
     58<property name="searchTemplate"><value>cn=[principal]</value></property> 
    5559}}} 
    56  When adding a search filter, you must place the literal string {{{[principal]}}} where you would like the users principal name to be inserted - where 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]))}}} 
    57 2. Once the attribute definition has acquired attributes about a user (via LDAP search) 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, then the {{{lookupAttributes}}} property would be defined as.   
     60 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]))}}} 
     612. 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.   
    5862{{{ 
    5963<property name="lookupAttributes"> 
     
    107111 
    108112The 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.  
     113 
     114=== RDBMS Connection Parameters (v1.0.0 or greater only) === 
     115 
     116If 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: 
     117{{{ 
     118  <bean id="databaseConnector" class="uk.ac.cardiff.raptor.event.expansion.connector.RDBMSDataConnector">          
     119         <property name="cacheResults"><value>true</value></property> 
     120         <property name="cacheTimeoutMs"><value>86400000</value></property> 
     121         <property name="dataSource"> 
     122            <bean id="dataSourceConnectionProperties" class="org.apache.commons.dbcp.BasicDataSource"> 
     123                <property name="driverClassName" value="org.postgresql.Driver"/> 
     124                <property name="url"  value="jdbc:postgresql://localhost/identities"/> 
     125                <property name="username"  value="postgres"/> 
     126                <property name="password"  value=""/> 
     127            </bean> 
     128         </property> 
     129    </bean> 
     130}}} 
     131Then, 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 {{{AttributeAssociationDefinition}}}s (e.g. {{{shibPrincipalAttributeAssociationDefinition}}} and or {{{ezproxyPrincipalAttributeAssociationDefinition}}}) by changing their property: 
     132{{{ 
     133<property name="dataConnector"><ref bean="ldapDataConnector"/></property> 
     134}}} 
     135to reference the databaseConnector: 
     136{{{ 
     137<property name="dataConnector"><ref bean="databaseConnector"/></property> 
     138}}}