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

  1. No entry yet.

uApprove Work Flow

uApprove is a plug-in for the Shibboleth Identity Provider. After a successful authentication by the Identity Provider, the following decision flow is used to determine whether uApprove is activated or not:
uApprove Decision Flow


Notes about this guide:



Multiple user identifiers for same user

uApprove uses the principal name provided by the Shibboleth Identity Provider to identify users. If the same user for some reason can authenticate at the Identity Provider using different principal names (e.g. uid or email address), he is treated treated like separate users. Therefore, the same user authenticating at the Identity Provider with different usernames has to accept the terms of use and attribute release for each username.

Reassigned user identifiers

uApprove cannot know when a user was deleted from the user-directory that the Identity Provider uses for authentication. This situation is of concern if principal names are reassigned to other users. Reassigned userIDs can result in the situation that a new user never has to accept the terms of use or give attribute release consent. It therefore should be ensured that the uApprove data (as well as for example the storedID data of the Shibboleth IdP) is taken into account when users are deprovisioned in the user directory that the Identity Provider uses.


The latest uApprove distribution can be downloaded from its project site on SWITCHforge:

Library Installation

Copying the libraries to the IdPs library directory:

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

Configuration Template

Copying the configuration template to the IdPs configuration directory:

Webapp files

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

Database Preparation

The following database parameters are examples.

Basic Deployment

Web Application Deployment Descriptor

Extend the IdP web application deployment descriptor ( $IDP_INSTALL$/src/main/webapp/WEB-INF/web.xml). Adapt your existing file as shown below.

<web-app ... >

        <param-value>$IDP_HOME$/conf/internal.xml; $IDP_HOME$/conf/service.xml; $IDP_HOME$/conf/uApprove.xml</param-value>

    <!-- IdP Listeners, Filters and Servlets -->
    <!-- ...                                 -->
    <!-- uApprove Filter and Servlets -->

        <servlet-name>uApprove - Terms Of Use</servlet-name>

        <servlet-name>uApprove - Terms Of Use</servlet-name>

        <servlet-name>uApprove - Attribute Release</servlet-name>

        <servlet-name>uApprove - Attribute Release</servlet-name>


Custom Configuration

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

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


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

Customize $IDP_HOME$/conf/ according to your database environment and required features.
Have a look at the inline documentation of for configuration options.

Make sure to carefully edit the properties of the database connection, i.e. the values of the properties "database.driver", "database.url", "database.username" and "database.password". Especially make sure not to insert trailing whitespace characters or even hidden control characters. This might lead to a non-working database connection.

In case you enable the ‘Terms of Use’ module (enabled by default), you need to provide an appropriate text
suitable for your organization.

An example ‘Terms Of Use’ HTML file can be found in $UAPPROVE_INSTALL$/manual/examples/terms-of-use.html.

cp $UAPPROVE_INSTALL$/manual/examples/terms-of-use.html $IDP_HOME$/conf/terms-of-use.html
tou.resource = file:$IDP_HOME$/conf/terms-of-use.html

Custom Templates

In case you want to customize the templates, follow section Custom View Templates.

At least, you should copy your organization’s logo to the file $IDP_INSTALL$/src/main/webapp/uApprove/logo.png, since a placeholder logo is installed by default.
You may also want to put your federation’s logo to the file $IDP_INSTALL$/src/main/webapp/uApprove/federation-logo.png (which is an empty placeholder logo by default).
(For the SWITCHaai federation, the logo is available at


To activate uApprove the IdP must be re-deployed:


You also need to restart your Java web application server (e.g. Tomcat or Jetty).


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

Upgrade from uApprove < 2.3

uApprove 2.2 and older contain an HTML injection vulnerability. Therefore, it is strongly recommended to upgrade to a recent version of uApprove.
Thanks go to Motonori Nakamura, Kazutsuna Yamaji and Takeshi Nishimura from the National Institute of Informatics (Japan) for reporting this vulnerability and providing a patch.

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.

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/ $IDP_HOME$/conf/

Upgrade from uApprove 2.3 to 2.4

Upgrade from uApprove 2.4 to 2.5

uApprove version 2.5 mainly introduces support for interfederation, besides some fixes and other minor features.
You should upgrade to uApprove 2.5 in case you participate in interfederation. If an Identity Provider is not interfederation-enabled (e.g. in eduGAIN), the upgrade is probably not necessary but still recommended.

In version 2.5, the web templates (JSP files, CSS files, images) have been adapted to support the legal requirements of interfederation
(see Legal Templates for SWITCHaai).
This means that you also need to update the web application files in $IDP_INSTALL$/src/main/webapp/uApprove.
Because the text translations are contained in the library file, keeping the old web application files would
mean that some texts are not shown anymore. In case you have customized the old web application files
of uApprove, you should install the new web application files and re-apply your customizations.

The upgrade procedure is:

Update the JDBC dependencies:

Optionally update the JDBC connector for your database unless your Identity Provider already uses a new version of the JDBC connector. You might use one of the provided MySQL or HSQL JDBC connector that comes with uApprove:

Update the web application files in $IDP_INSTALL$/src/main/webapp/uApprove. If you have done any customizations
of these files, do a backup of the old files first, and then re-apply the customizations after having updated
these files

In case you want to adapt the text translations, see section Localization below.

Adapt some values in $IDP_HOME$/conf/$:

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


It is also necessary to restart the Java web application server (e.g. Tomcat or Jetty).

Extension to uApprove 2.5.0: Show Service's Information and Privacy Statement URLs

This extension is recommended if the IdP is interfederation-enabled (e.g. in eduGAIN) and uApprove version 2.5.0 or older is used, which don't show a service's Privacy Statement URL in the standard configuration. Version 2.6.0 or uApprove already contains all necessary changes.
Displaying the Privacy Statement URL is recommended for interfederation-enabled IdPs. Please follow the instructions below at Extension to uApprove 2.5.0: Show Service's Information and Privacy Statement URLs to add this extension to your new installation of uApprove.

A service can declare URLs that refer to information about the service and to the service's privacy statement.

To show these URLs, one can include appropriate code into the existing uApprove webapp. Updated versions of the webapp files header.jsp and attribute-release.jsp are provided below. In case these files have not been modified since the initial installation of uApprove, the update is just a matter of replacing these two files with new versions.If the file attribute-release.jsp was modified, header.jsp needs to be replaced with the new version and a few additional lines of code have to be added to the attribute-release.jsp file.

It is assumed that no changes were made to the file header.jsp, because this normally should never have been necessary.

These are the step-by-step instructions on how the information and privacy statement URLs can be added to the uApprove deployment:

To activate these changes, the IdP must be re-deployed:


It is also necessary to restart the Java web application server (e.g. Tomcat or Jetty).

Upgrade from uApprove 2.5 to 2.6

The general upgrade procedure is to copy the new uApprove and related JAR files to the library directory of the Identity Provider with:

uApprove version 2.6 mainly introduces LDAP support, includes the changes for better displaying Information and Privacy URL and adds new localized text strings for Swedish (thanks to RCTSaai) and Portuguese (thanks to SWAMID). Depending on your current deployment some configuration changes might therefore be required by the update. In particular:

Changes for LDAP-Storage Support Only

If uApprove is to store its data in an LDAP server, one also has to copy:

Advanced Deployment Topics

This section contains advanced configuration topics.

Reset Attribute Release Consent

To enable the feature that allows a user to clear her attribute release consent (delete general consent and all attribute release consents for the current service) during the login flow, add a checkbox to $IDP_INSTALL$/src/main/webapp/login.jsp:

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

Storage Alternatives

The default storage method in uApprove is JDBC. Typically, data is stored in a MySQL database. However, there are alternatives that are described below:

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="" />
    <bean id="uApprove.uApprove.attributeReleaseModule" ... >
        <property name="storage">
            <bean class="" />

File-based Storage

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

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.

LDAP-based Storage

The RWTH Aachen University implemented and contributed a storage interface to store terms of use and consent data in LDAP. The prerequisites to use the LDAP storage are:

uApprove might not be able to retrieve and store data if the LDAP server is restarted. In this case, the terms-of-use acceptance and attribute consent are requested on each login until the IdP is also restarted.

The following steps are then needed to eanble LDAP-based storage:

  1. Ensure that within the base subtree (e.g. ou=uApprove,dc=example,dc=ch) there are two further subtrees: Both sub trees must have the object class organization. It is important that the Relative Distringuished Names (RDN) of the sub trees are o=AttRelCon and o=ToU because these values are hard-coded in uApprove.
  2. In the file $IDP_HOME$/conf/ uncomment all ldap properties and adapt the settings where needed.
    An example configuration where the LDAP server would be operated on the same server as the Identity Provider could look like:
    # LDAP configuration                                                  #
    ldap.url                    = ldap://
    ldap.username               = cn=admin,dc=example,dc=org
    ldap.password               = MySecretPassword123
    ldap.base                   = ou=uApprove,dc=example,dc=org
  3. In the file $IDP_HOME$/conf/uApprove.xml uncomment: and comment out (to disable):
  4. Restart Tomcat and check the idp-process.log for errors and warnings.

The LDAP storage interface then creates new entries in the ToU and AttRelCon subtrees for each user (uid=principal name) and within that for each terms of use version/service. Also consider adding appropriate indexes to speed up the lookup of users.

Advanced JDBC Topics

Custom SQL Statements

  1. Copy the provided $UAPPROVE_INSTALL$/manual/storage/ to $IDP_HOME$/conf/
  2. Adjust $IDP_HOME$/conf/ according to your needs.
  3. Enable your custom in $IDP_HOME$/conf/uApprove.xml:
    <bean class="ch.SWITCH.aai.uApprove.tou.ToUModule" ... >
        <!-- ... -->
        <property name="storage">
            <bean class="" ...
                p:sqlStatements="file:/$IDP_HOME$/conf/" ... />
    <!-- ... -->
    <bean id="uApprove.attributeReleaseModule" class="" ...>
        <!-- ... -->
        <property name="storage">
            <bean class="" ...
               p:sqlStatements="file:/$IDP_HOME$/conf/" ... />

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="" ...
                p:graceful="true" ... />
    <!-- ... -->
    <bean id="uApprove.attributeReleaseModule" class="" ...>
        <!-- ... -->
        <property name="storage">
            <bean class="" ...
               p:graceful="true" ... />

JDBC Connection Pool Tuning

Please consulte the c3p0 configuration reference 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.


Custom Template Views

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

Localized 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

uApprove can replace the standard attribute names (e.g. eduPersonEntitlement) used in the Shibboleth attribute-resolver.xml file with more user-friendly attribute names and (mouse over) descriptions. To use custom display names for the attributes supported by the Identity Provider, add a DisplayName element to the attribute-resolver.xml file for a given attribute defined in an AttributeDefinition. An example for the email attribute is given below:

<!-- E-mail -->
<resolver:AttributeDefinition id="email" xsi:type="ad:Simple" sourceAttributeID="mail">
    <resolver:Dependency ref="ldapAttributes" />
    <resolver:DisplayName xml:lang="en">E-mail</resolver:DisplayName>
    <resolver:DisplayName xml:lang="de">E-Mail</resolver:DisplayName>
    <resolver:DisplayDescription xml:lang="en">E-Mail: Preferred address for e-mail to be sent to this person</resolver:DisplayDescription>
    <resolver:DisplayDescription xml:lang="de">E-Mail Adresse</resolver:DisplayDescription>
    <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:mace:dir:attribute-def:mail" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:0.9.2342.19200300.100.1.3" friendlyName="mail" />

Have a look at this example attributer-resolver.xml snippet file to see how this feature can be used and to get some examples of common attributes. $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 consuming service descriptors in metadata are supported, to retrieve localized relying party names and descriptions.
For providing such names and descriptions extend the metadata for the SP like:

<EntityDescriptor entityID="">
    <!-- ... -->
        <!-- ... -->
        <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 -->

The metadata of the SWITCHaai federation contains these information.

Strict ToU/Attribute 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 id="uApprove.attributeReleaseModule" ... 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 id="uApprove.touModule" ... p:auditLogEnabled="true" ... >



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



Attribute In Attribute Requester’s Metadata Plugin


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:

Define the Namespace

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

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

Service Blacklisting

In order to make uApprove not too intrusive, it might make sense to blacklist or whiteliste some service for which no user consent is necessary. Be it internal service or be it services within the same country as the Identity Provider is operated in etc. This can - to some extent - be achieved via the services and the services.blacklist options which use regular expressions on the entityID of a Service Provider to show or not show the attribute consent.
Find below an example to disable attribute consent for all services that are operated within the same organisation whose domain name is ''. Additionally that organisation also has services on '' and some services don't use a URL as entityID but a URN.
Note that multiple space-separated regular expressions can be given per line (or on multiple lines with \).

# List of service provider entity IDs.
# The entries are interpreted as regular expression.
# can assist you creating such expressions.
services = ^https?://[^/]*\.example\.org.*$ \
           ^https?://[^/]*\.other-domain\.org.*$ \

# Indicates if the list above should be interpreted as blacklist (true)
# or as whitelist (false). 
# In this example, use services as blacklist = don't show user consent
# for services that match the regular expression in services
services.blacklist          = true

MySQL connection via TLS/SSL

The installation notes in this section where contributed by Bernd Kohler from RWTH Aachen University, Germany.

If the MySQL database used by uApprove is located on a different host than the Identity Provider, you might consider protecting the LDAP connection between uApprove and MySQL with TLS. Please note that while the security of the connection is improved the performance is slightly reduced due to the encryption overhead.

Installation Steps

  1. Ensure that the MySQL Server is properly configured with TLS/SSL by first connecting with the mysql client on the host where uApprove is installed.
    This can be achieved with a command like (substitute IP, port and file names accordingly):
    mysql -h -P 5678 --ssl --ssl-cert=client-cert.pem --ssl-key=client-key.pem -D uApprove -u uApprove -p
    Enter password:
    mysql> \s
    Current database:   uApprove
    Current user:       uApprove@IDP
    SSL:                Cipher in use is DHE-RSA-AES256-SHA
    Protocol version:   10
    Connection: via TCP/IP
    Server characterset:    utf8
    Db     characterset:    utf8
    Client characterset:    utf8
    Conn.  characterset:    utf8
    TCP port:       5678
  2. Import the MySQL server certificate's issueing CA into a truststore:
    keytool -import -v -alias mysqld_ca -file mysqld_ca_cert.pem -keystore truststore.jks
  3. Import the MySQL client's certificate into the truststore:
    keytool -import -v -alias mysql  -file client-cert.pem -keystore truststore.jks
  4. Convert the client certificate and key into a PKCS12 file and import it into the truststore:
    openssl pkcs12 -export -in client-cert.pem -inkey client-key.pem \
    -CAfile mysqld_ca_cert.pem -name uApprove -out uApprove.p12
    openssl pkcs12 -in uApprove.p12 -info
    keytool -importkeystore -destkeystore truststore.jks -deststorepass $PASSWD1 \
    -srckeystore uApprove.p12 -srcstoretype PKCS12 -srcstorepass $PASSWD2
  5. Adapt the Tomcat/Java configuration to use the truststore according to Java MySQL client reference for SSL.
    This requires setting the JAVA_OPTS variable in /etc/defaults/tomcat and/or /etc/init.d/tomcat:$PASSWD1
  6. Adapt the database URL in the uApprove configuration (
    database.url = jdbc:mysql:// \


In case of problems it is recommended to:

Enabling DEBUG or TRACE log level for uApprove in $IDP_HOME$/conf/logging.xml allows to better debug problems. To set the log level to DEBUG create the following entry:

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


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