README.txt

Shibboleth IdP User Agent Attribute Extension
=============================================
This plugin captures the user agent IP address at authentication and then 
allows that information to trigger the association of certain attributes/values
during attribute resolution time.

Requirements
=============================================
This plugin requires Shibboleth IdP v2.3.x


Installation/Upgrade Instructions
=============================================
The following steps must be performed during the initial installation of this
plugin and at every IdP upgrade.

1. Shutdown the container running the IdP.

2. Place the ua-attribute-idp-ext JAR file, located in this bundle, in to the 
   IdP distribution's lib directory
   
3. Edit the web.xml file, located in the src/main/webapp/WEB-INF directory of the
   IdP distribution, as follows:
   - locate the definition for the Servlet named 'UsernamePasswordAuthHandler'
     this is found around line 100 of the default web.xml file
   - replace the value of the <servlet-class> element with:
     uk.org.ukfederation.uaattribute.authn.UserAgentUsernamePasswordLoginServlet

4. Run the IdP's install script

5. Configure the attribute resolver as described below.  This step is only performed
   during initial installation.

6. Restart the container running the IdP

Configuration Instructions
=============================================
The following changes to the IdP's attribute-resolver.xml configuration file 
only need to be performed the first time you install the plugin, after that they 
will carry over through upgrades.

1. Add the following namespace declaration to the root AttributeResolver element:
   xmlns:uadc="http://ukfederation.org.uk/schemas/uaattribute/resolver"
   
2. Add the following schema locations to the existing whitespace-separated list:
   http://ukfederation.org.uk/schemas/uaattribute/resolver classpath:/schema/ua-attribute-resolver.xsd
   
3. Define a new data connector as follows, filling in the UNIQUE_ID and Mapping
   elements (described in the following section):
   <resolver:DataConnector id="UNIQUE_ID" xsi:type="uadc:UserAgentMappedAttributes">
      <uadc:Mapping cidrBlock="...." attributeId="..." attributeValue="..." />
   </resolver:DataConnector>

4. Create one attribute definition per attribute generated by the data 
   connector.  Only attributes created by attribute definitions may be
   released to a service provider.

CIDR Block -> Attribute Mappings
=============================================
This plugin creates attributes by checking if the IP address of the user agent,
at the time of authentication, matches a given range of IP addresses identified
by CIDR blocks.  The Mapping element noted in step 3, in the section above,
requires, and only accepts, following XML attributes:
* cidrBlock - the CIDR block (IPv4 or IPv6) that triggers the mapping
* attributeId - the ID of the IdP attribute generated if the mapping is triggered
* attributeValue - the value added to the IdP attribute if the mapping is triggered

You can have more than one mapping rule with the same CIDR block.  This allows
you to create multiple attributes for the given CIDR block.  You can also specify
a given attribute ID more than once in order to generate multiple values
for the ID.