uApprove Manual

This document contains the uApprove deployment guide and the general manual. uApprove is an extension for the Shibboleth Identity Provider 2.x. It allows to make users authenticating at an Identity Provider to accept terms of use and to give attribute release consent. More information about the concept of uApprove.

Table of contents

No entry yet.

Installation

Prerequisites

Shibboleth Identity Provider 2.3 or greater.
Database which supports JDBC.

Assumptions

The Shibboleth Identity Provider is unpacked at $IDP_INSTALL$ (e.g., /opt/shibboleth-identity-provider-#version#).
The Shibboleth Identity Provider is installed at $IDP_HOME$ (e.g., /opt/shibboleth-idp).
uApprove is downloaded and unpacked at $UAPPROVE_INSTALL$ (e.g., /tmp/uApprove-#version#).

Library Installation

Copying the libraries to the IdPs library directory:

cp $UAPPROVE_INSTALL$/lib/*.jar $IDP_INSTALL$/lib
cp $UAPPROVE_INSTALL$/lib/jdbc/*.jar $IDP_INSTALL$/lib
Provide the JDBC connector for your database to the classpath of the IdP. You might use one of the provided MySQL or HSQL JDBC connector:
cp $UAPPROVE_INSTALL$/lib/jdbc/optional/#jdbc-connector#.jar $IDP_INSTALL$/lib

Assure that only one version of each library is present in $IDP_INSTALL$/lib.

Configuration Template

Copying the configuration template to the IdPs configuration directory:

cp $UAPPROVE_INSTALL$/manual/configuration/uApprove.properties $IDP_HOME$/conf
cp $UAPPROVE_INSTALL$/manual/configuration/uApprove.xml $IDP_HOME$/conf

Webapp files

Copying of the web application files like the JSPs, CSS files and images to the IdPs webapp directory:

mkdir $IDP_INSTALL$/src/main/webapp/uApprove
cp $UAPPROVE_INSTALL$/webapp/* $IDP_INSTALL$/src/main/webapp/uApprove

Database Preparation

The following database parameters are examples.

Create a database with the name “uApprove”.
Create a database user with the username “uApprove” and password “uApprove”.
Grant INSERT, SELECT, UPDATE, DELETE rights for the user.
Create the initial table structures using the schemas:
- $UAPPROVE_INSTALL$/manual/storage/terms-of-use-schema.sql.
- $UAPPROVE_INSTALL$/manual/storage/attribute-release-schema.sql.

Basic Deployment

Web Application Deployment Descriptor

Extend the IdP web application deployment descriptor ( $IDP_INSTALL$/src/main/webapp/WEB-INF/web.xml):

<web-app ... >

    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>file:$IDP_HOME$/conf/internal.xml; file:$IDP_HOME$/conf/service.xml; file:/$IDP_HOME$/conf/uApprove.xml</param-value>
    </context-param>

    <!-- IdP Listeners, Filters and Servlets -->
    <!-- ...                                 -->
    
    
    <!-- uApprove Filter and Servlets -->
    
    <filter>
        <filter-name>uApprove</filter-name>
        <filter-class>ch.SWITCH.aai.uApprove.Intercepter</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>uApprove</filter-name>
        <url-pattern>/profile/Shibboleth/SSO</url-pattern>
        <url-pattern>/profile/SAML1/SOAP/AttributeQuery</url-pattern>
        <url-pattern>/profile/SAML1/SOAP/ArtifactResolution</url-pattern>
        <url-pattern>/profile/SAML2/POST/SSO</url-pattern>
        <url-pattern>/profile/SAML2/POST-SimpleSign/SSO</url-pattern>
        <url-pattern>/profile/SAML2/Redirect/SSO</url-pattern>
        <url-pattern>/profile/SAML2/Unsolicited/SSO</url-pattern>
        <url-pattern>/Authn/UserPassword</url-pattern>
    </filter-mapping>

    <servlet>
        <servlet-name>uApprove - Terms Of Use</servlet-name>
        <servlet-class>ch.SWITCH.aai.uApprove.tou.ToUServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>uApprove - Terms Of Use</servlet-name>
        <url-pattern>/uApprove/TermsOfUse</url-pattern>
    </servlet-mapping>

    <servlet>
        <servlet-name>uApprove - Attribute Release</servlet-name>
        <servlet-class>ch.SWITCH.aai.uApprove.ar.AttributeReleaseServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>uApprove - Attribute Release</servlet-name>
        <url-pattern>/uApprove/AttributeRelease</url-pattern>
    </servlet-mapping>

</web-app>

Custom Configuration

In $IDP_HOME$/conf/uApprove.xml change:

<context:property-placeholder location="classpath:/configuration/uApprove.properties" />

to:

<context:property-placeholder location="file:$IDP_HOME$/conf/uApprove.properties" />

Customize $IDP_HOME$/conf/uApprove.properties according your database environment and required features. See inline documentation of uApprove.properties for configuration options.

Deployment

To activate uApprove the IdP must be re-deployed:

$IDP_INSTALL$/install.sh

Upgrade

There are different update procedures depending on the version that is updated.

Upgrade from uApprove < 2.3

If your upgrading from uApprove < 2.3 you have to completly remove this old version first and perform a clean install. Please have a look at the installation instructions above for further information on how to install uApprove..

Legacy uApprove (< 2.3) deployment: Please remove it.
Configuration files: Please use the new configuration file and tailor them to your needs. Note: The new ToU is an HTML file, which you can customize, just copy the content from your lecacy ToU lang-xml to a plain HTML file.
JSP: Please use the new provided JSP files. If you use Reset Attribute Release Consent, please adjust your login.jsp.
Database Migration: It is possible to migrate ToU acceptance and attribute release consent data using the provided data migration script.

If Terms Of Use Content Comparison and/or Attribute Value Comparison feature will be used,
the lecacy database entries can not be used and must not be migrated.

Database Migration

Migrate lecacy database to the new database with:

java -cp "$UAPPROVE_INSTALL$/scripts/lib/*.jar:$UAPPROVE_INSTALL$/lib/jdbc/optional/*.jar" groovy.ui.GroovyMain \
  $UAPPROVE_INSTALL$/scripts/StorageMigration.groovy /opt/uApprove/conf/database.properties $IDP_HOME$/conf/uApprove.properties

Upgrade from uApprove 2.3 to 2.4

In version 2.4 c3p0 is used as the connection pooling library (instead of boneCP in uApprove 2.3). The reason was, that some deployers reported connection repairing issues with remote databases. c3p0 offers also an easier deployment, because this library is used by the IdP as well. Please assure following upgrade steps:
- Adjust the uApprove.dataSource bean in $IDP_HOME$/conf/uApprove.xml (i.e., replace the bonecp.BoneCPDataSource with the c3p0.ComboPooledDataSource, see $UAPPROVE_INSTALL$/manual/configuration/uApprove.xml). Please refer to JDBC Connection Pool Tuning for advanced configuration properties.

Upgrade from uApprove > 2.4

The general upgrade procedure unless otherwise mentioned above is:

rm $IDP_INSTALL$/lib/uApprove-#old-version#.jar
cp $UAPPROVE_INSTALL$/lib/uApprove-#new-version#.jar $IDP_INSTALL$/lib

Optionally update the JDBC dependencies:

cp $UAPPROVE_INSTALL$/lib/jdbc/*.jar $IDP_INSTALL$/lib

Optionally update the JDBC connector for your database. You might use one of the provided MySQL or HSQL JDBC connector:

cp $UAPPROVE_INSTALL$/lib/jdbc/optional/#jdbc-connector#.jar $IDP_INSTALL$/lib

Verify that only one version of each library is present in $IDP_INSTALL$/lib.

Optionally update the web application and configuration files if you do not have any customizations.
It is recommended to backup the old files first.

To finish the upgrade of uApprove the IdP must be re-deployed:

$IDP_INSTALL$/install.sh

Advanced Deployment

This sections contains advanced configuration topics.

Reset Attribute Release Consent

It is a good practice to allow users to clear For providing the feature that a user is able to clear their attribute release consent. This means delete all attribute release consents for the current relying party and/or delete general consent. To allow users to clear their attribute release consent during the login flow, add a checkbox like below to $IDP_INSTALL$/src/main/webapp/login.jsp:

<form action="<%=request.getAttribute("actionUrl")%>" method="post">
  ...
  <input type="checkbox" name="uApprove.consent-revocation" value="true"/>
  <label for="uApprove.consent-revocation">Clear data release consent for this service</label>
  ...
</form>

Storage

File-only

For a simple deployment a file only database can be used. HSQL provides such an option.
Define the according database properties in uApprove.properties:

database.driver             = org.hsqldb.jdbcDriver
database.url                = jdbc:hsqldb:file:/var/opt/uApprove/hsql.db
database.username           = SA
database.password           =

Initializing the database with the provided schemas:

echo "SHUTDOWN;" > /tmp/shutdown
java -jar $HSQLDB_HOME$/lib/sqltool.jar \
  --inlineRC=url=jdbc:hsqldb:file:/var/opt/uApprove/hsql.db,user=SA,password= \
  $UAPPROVE_INSTALL$/manual/storage/terms-of-use-schema.sql /tmp/shutdown
java -jar $HSQLDB_HOME$/lib/sqltool.jar \
  --inlineRC=url=jdbc:hsqldb:file:/var/opt/uApprove/hsql.db,user=SA,password= \
  $UAPPROVE_INSTALL$/manual/storage/attribute-relase-schema.sql /tmp/shutdown

$HSQLDB_HOME$ defines the location where the downloaded HSQL distribution is extracted.

Assure that the user running the container (e.g., Jetty) has write permission to the db directory.

Custom SQL Statements

Copy the provided $UAPPROVE_INSTALL$/manual/storage/sql-statements.properties to $IDP_HOME$/conf/uApprove.sql-statements.properties.
Adjust $IDP_HOME$/conf/uApprove.sql-statements.properties according your needs.
Enable your custom sql-statements.properties in $IDP_HOME$/conf/uApprove.xml:

    <bean class="ch.SWITCH.aai.uApprove.tou.ToUModule" ... >
        <!-- ... -->
        <property name="storage">
            <bean class="ch.SWITCH.aai.uApprove.tou.storage.JDBCStorage" ...
                p:sqlStatements="file:/$IDP_HOME$/conf/uApprove.sql-statements.properties" ... />
        </property>
    </bean>
    
    <!-- ... -->
    
    <bean class="ch.SWITCH.aai.uApprove.ar.AttributeReleaseModule" ... >
        <!-- ... -->
        <property name="storage">
            <bean class="ch.SWITCH.aai.uApprove.ar.storage.JDBCStorage" ...
               p:sqlStatements="file:/$IDP_HOME$/conf/uApprove.sql-statements.properties" ... />
        </property>
    </bean>

Graceful JDBC Connection Handling

The JDBC storage can be configured to act graceful in case of a tempory database issue (e.g., communication link is not available). Instead throwing exceptions and display the error page, no persistent actions are applied.
This implies that the users, idenpently of former ToU accetances and/or attribute release consents have to accept/consent again (if they already had) or have to do it during the next login (if it was the first time).

N.B. It might make sense to set checkoutTimeout to an appropiate low value – so as the user has not bothersome latency.

The settings are defined in $IDP_HOME$/conf/uApprove.xml:

    <bean class="ch.SWITCH.aai.uApprove.tou.ToUModule" ... >
        <!-- ... -->
        <property name="storage">
            <bean class="ch.SWITCH.aai.uApprove.tou.storage.JDBCStorage" ...
                p:graceful="true" ... />
        </property>
    </bean>
    
    <!-- ... -->
    
    <bean class="ch.SWITCH.aai.uApprove.ar.AttributeReleaseModule" ... >
        <!-- ... -->
        <property name="storage">
            <bean class="ch.SWITCH.aai.uApprove.ar.storage.JDBCStorage" ...
               p:graceful="true" ... />
        </property>
    </bean>

JDBC Connection Pool Tuning

Cf. c3p0 configuration for further details on configuration options.

The settings are defined in $IDP_HOME$/conf/uApprove.xml:

    <bean class="com.mchange.v2.c3p0.ComboPooledDataSource" ...
        ...
        p:idleConnectionTestPeriod="300" ... />

N.B. You are free to use another JDBC connection pooling library (e.g., BoneCP). Just provide the right data source class name in the bean definition as well the required libraries in the classpath.

NOP Storage

The NOP storage basically retrieves users ToU acceptance and/or attribute release consent without requiring any JDBC storage.
This implies alwaysRequireToUAcceptance and/or alwaysRequireConsent.

You might enable NOP storage for the ToU and/or attribute release module in $IDP_HOME$/conf/uApprove.xml:

    <bean ... >
        ...
        <property name="storage">
            <bean class="ch.SWITCH.aai.uApprove.tou.storage.NOPStorage" />
        </property>
    </bean>
    
    <bean ... >
        ...
        <property name="storage">
            <bean class="ch.SWITCH.aai.uApprove.ar.storage.NOPStorage" />
        </property>
    </bean>

Other Storage Implementations

Custom storage implementations might be provided in future. Some ideas are:

Cookie based Storage: This will remember users consent within a cookie. It could stored for just the session or some defined period (e.g., 10 days).

Templates

Custom Templates

It is recommended to customize the JSP, CSS and image files located in $UAPPROVE_INSTALL$/webapp/.
uApprove uses the JSP Standard Tag Library (JSTL) to render the consent web pages. Please refer to this JSTL tutorial for a quick overview.

Localization

Custom Messages

You might adjust/extend the provided resource bundles in $UAPPROVE_INSTALL$/manual/examples/messages and copy them into the IdPs classpath (e.g., $IDP_INSTALL$/src/main/webapp/WEB-INF/classes/uApprove/messages).
Specify your bundles base in $IDP_HOME$/conf/uApprove.xml:

<bean class="ch.SWITCH.aai.uApprove.ViewHelper" ...
      p:messagesBase="uApprove.messages" />

Attribute Names and Descriptions

See $UAPPROVE_INSTALL$/manual/examples/attribute-descriptions.xml for an example how to configure the localized attribute names and descriptions.

Relying Party Names and Descriptions

Currently only the attribute consumin service descriptors in metadata are supported, toe retrieve localized relying arty names and descriptions.
For providing such names and descriptions extend the metadata for the SP like:

<EntityDescriptor entityID="https://sp.example.org/shibboleth">
    <!-- ... -->
    <SPSSODescriptor>
        <!-- ... -->
        <AttributeConsumingService index="1">
            <ServiceName xml:lang="en">Example SP</ServiceName>
            <!-- Service names in other languages -->
            <ServiceDescription xml:lang="en">Some description of Example SP</ServiceDescription>
            <!-- Service descriptions in other languages -->
        </AttributeConsumingService>
    </SPSSODescriptor>
</EntityDescriptor>

Strict Comparison

Terms Of Use Content Comparison

In the default configuration, only the ToU version is compared to evaluate if a user accepted the ToU. You might enable that the ToU content is compared too in $IDP_HOME$/conf/uApprove.xml:

<bean ... p:compareContent="true" ... >

Attribute Value(s) Comparison

In the default configuration, only the attribute ID is compared to evaluate if a user consented attibute release. You might enable that attribute value(s) are compared too in $IDP_HOME$/conf/uApprove.xml:

<bean ... p:compareAttributeValues="true" ... >

Audit Logging

uApprove allows (faciliating the IDP’s audit log) to enable audit logging to $IDP_HOME$/logs/idp-audit.log.

Enable Terms Of Use Audit Log

You might enable ToU audit log in in $IDP_HOME$/conf/uApprove.xml:

<bean ... p:auditLogEnabled="true" ... >

Example:

20120101T010000Z|ch.SWITCH.aai.uApprove|||tou.acceptance|null|null|null|student1||1.0,5b2ee897c08c79...77c36b5c78644b2b3,|

Enable Attribute Release Audit Log

You might enable attribute release audit log in in $IDP_HOME$/conf/uApprove.xml:

<bean ... p:auditLogEnabled="true" ... >

Examples:

20120101T010000Z|ch.SWITCH.aai.uApprove||https://sp.example.org/shibboleth|ar.consent|null|null|null|student1||uid,surname,givenName,|
20120101T010000Z|ch.SWITCH.aai.uApprove||https://sp.example.org/shibboleth|ar.clearConsent|null|null|null|student1|||
20120101T010000Z|ch.SWITCH.aai.uApprove|||ar.generalConsent|null|null|null|student1|||

Attribute In Attribute Requester’s Metadata Plugin

Installation

The plugin is installed by default with uApprove ( uApprove-#version#.jar).

Configuration Attribute In Requester’s Metadata Matching Rule

This rule allows the release of an attribute if, via its metadata, the SP indicates a need/desire for the attribute. The attributes are indicated by means of <AttributeConsumingService> elements within the <SPSSODescriptor> element. See SAML metadata for more information.

While this rule does have some minor support for dealing with attribute values within the metadata it is limited and should be considered experimental.
Please be aware of the following:

This filter requires the attribute requester’s metadata be loaded and available.
The requester’s metadata must have an <SPSSODescriptor role since that is the role that contains the listed attributes.
This matching function only operates as a value rule and only really makes sense as a permit value rule.

Define the Namespace

In you attribute filter policy file you’ll need to add the namespace declaration for this plugin. To do this:

Add the attribute xmlns:ua="http://www.switch.ch/aai/idp/uApprove/mf" before the xmlns:xsi attribute on the root <AttributeFilterPolicyGroup> element.
Add the following at the end of the whitespace delimited list of values for the xsi:schemaLocation attribute: http://www.switch.ch/aai/idp/uApprove/mf classpath:/schema/uApprove-mf.xsd.

Define the Rule

This rule is defined by the element <PermitValueRule xsi:type="ua:AttributeInMetadata"> with the following optional attribute:

[onlyIfRequired] Boolean flag indicated that only those attributes which are marked as required should be released, those marked as optional will not be. Default value: true.

Example Permit Value Rule using the AttributeInMetadata Match Function:

<PermitValueRule xsi:type="ua:AttributeInMetadata" onlyIfRequired="false">

Other

Other topics will be added upon request. Some candidates are:

Black/Whitelisting
- Different Lists for Terms Of Use and Attribute Release Module
- Specific authContextClassRef required

Troubleshooting

Check $IDP_HOME$/logs/idp-process.log for ERROR or WARN messages.
Check container standard error/out (e.g., Jetty’s $JETTY_HOME$/logs/`date +%Y_%m_%d`.stderrout.log) for error messages.

Debugging

Enabling DEBUG or TRACE log level for uApprove in $IDP_HOME$/conf/logging.xml:

<logger name="ch.SWITCH.aai.uApprove" level="DEBUG"/>

Feedback

Please report bugs, feature requests and suggestions in the uApprove Project Site. Send general questions and comments to aai@switch.ch.