This document contains the uApprove deployment guide.

1 Installation

1.1 Prerequisites

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

1.2 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#).

1.3 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.

1.4 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

1.5 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

1.6 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.

2 Basic Deployment

2.1 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>

2.2 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 for configuration options.

2.3 Deployment

To activate uApprove the IdP must be re-deployed:

$IDP_INSTALL$/install.sh

3 Upgrade

If your upgrading from uApprove < 2.3 please read the according upgrade information and
follow the installation instructions.

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

3.1 Upgrade from uApprove < 2.3

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 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:

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

3.2 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.

4 Advanced Deployment

This sections contains advanced configuration topics.

4.1 Reset Attribute Release Consent

For providing the feature that a user is able to clear ¹ her attribute release consent during the login flow,
add a checkbox to $IDP_INSTALL$/src/main/webapp/login.jsp:

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

4.2 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 id="uApprove.touModule" 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 id="uApprove.attributeReleaseModule" 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 id="uApprove.touModule" 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 id="uApprove.attributeReleaseModule" 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 id="uApprove.dataSource" 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 id="uApprove.touModule" ...
        ...
        <property name="storage">
            <bean class="ch.SWITCH.aai.uApprove.tou.storage.NOPStorage" />
        </property>
    </bean>

    <bean id="uApprove.uApprove.attributeReleaseModule" ...
        ...
        <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).

4.3 Templates

Custom View Templates

Feel free to customize the JSP, CSS and image files located in $UAPPROVE_INSTALL$/webapp/.
For convienience the JSTL is used, cf. JSTL reference.

4.4 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 id="uApprove.viewHelper" 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>

4.5 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 id="uApprove.touModule" ... 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 id="uApprove.attributeReleaseModule" ... p:compareAttributeValues="true" ...

4.6 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 id="uApprove.touModule" ... p:auditLogEnabled="true" ...

Example:

20120101T010000Z|ch.SWITCH.aai.uApprove|||tou.acceptance|null|null|null|student1||1.0,5b2ee897c08c79a09cd57e8602d605bf8c52db17de9793677c36b5c78644b2b3,|

Enable Attribute Release Audit Log

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

<bean id="uApprove.attributeReleaseModule" ... 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|||

4.7 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">

4.8 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

5 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"/>

6 Feedback

Send general questions and comments to aai@switch.ch. For bug reports, please use our issue tracking.

¹ Clear means to delete general consent if it was given as well delete as all attribute release consents for the accessed relying party.