The example values used in this guide are:

idp.example.org

The DNS name of the Identity Provider

/opt/uApprove

The directory, where the uApprove is installed

/opt/uApprove/conf

The directory, where the uApprove config is located

/opt/shibboleth-identityprovider

The Shibboleth IdP installation directory (where install.sh lives)

/opt/tomcat

The directory, where Tomcat is installed.

Before start install and configure uApprove, assure that the following prerequisites are met:

Shibboleth Identity Provider 2.2.

Shibboleth Identity Provider has to be deployed properly.
That implied that Java and Tomcat are working.

SQL Database

If a SQL Database as storage is used. A SQL Server has to be prepared.
Shipped uApprove is already configured for MySQL, but another SQL Server can be adapted. Brook Schofield documented how to use uApprove with an Oracle database.

Download and unzip the uApprove package:

wget http://www.switch.ch/aai/downloads/uApprove-2.2.1-bin.zip
unzip uApprove-2.2.1-bin.zip -d /opt/
ln -s /opt/uApprove-2.2.1 /opt/uApprove

Copy libraries and configuration:

cd /opt/uApprove
mkdir conf logs war
unzip idp-plugin-2.2.1-bin.zip
cp idp-plugin-2.2.1/conf-template/* conf/
cp idp-plugin-2.2.1/lib/* /opt/shibboleth-identityprovider/lib/

Copy libraries and configuration:

cd /opt/uApprove
unzip viewer-2.2.1-bin.zip
cp viewer-2.2.1/conf-template/* conf/

First you have to decide which storage implementation should be used:

File based

This is only recommended for small installation (< 100 users)

SQL Database

MySQL database is fully suppored, but any SQL Database which has an JDBC connector should work. May be advanced configuration is needed.

A file based storage hast to be setup in /opt/uApprove/conf/common.properties:

#storageType=database
#databaseConfig=/opt/uApprove/conf/database.properties

storageType=file
flatFile = /opt/uApprove/data/uApprove-log.xml

Note

Assure that uApprove-log.xml is read- and writeable by Tomcat.

First, a databases and a user have to be created:

mysql -u root -p
mysql>
CREATE DATABASE uApprove;
CREATE USER 'uApprove'@'localhost' IDENTIFIED BY 'uApprove';
GRANT USAGE ON *.* TO 'uApprove'@'localhost';
GRANT SELECT , INSERT , UPDATE , DELETE ON `uApprove`.* TO 'uApprove'@'localhost';
ALTER DATABASE uApprove DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;

Second, generate the table structures:

mysql -u root -p
mysql>
use uApprove;

create table ArpUser (
  idxArpUser int unsigned auto_increment primary key,
  auUserName varchar(255) not null,
  auLastTermsVersion varchar(255),
  auFirstAccess timestamp,
  auLastAccess timestamp
);
create index idxUserName on ArpUser (auUserName );

create table ShibProvider (
  idxShibProvider int unsigned auto_increment primary key,
  spProviderName varchar(255)
);

insert into ShibProvider (idxShibProvider) values (1);
create index idxProvidername on ShibProvider (spProviderName);

create table AttrReleaseApproval (
  idxAttrReleaseApproval int unsigned auto_increment primary key,
  araIdxArpUser int unsigned references ArpUser ( idxArpUser ),
  araIdxShibProvider int unsigned references ShibProvider( idxShibProvider ),
  araTimeStamp timestamp not null,
  araTermsVersion varchar(255),
  araAttributes text(2048)
);

create table ProviderAccess (
  idxProviderAccess int unsigned auto_increment primary key,
  paIdxArpUser int unsigned references ArpUser( idxArpUser ),
  paIdxShibProvider int unsigned references ShibProvider( idxShibProvider ),
  paAttributesSent text,
  paTermsVersion varchar(255),
  paIdxAttrReleaseApproval int unsigned references AttrReleaseApproval ( idxAttrReleaseApproval ),
  paShibHandle varchar(255),
  paTimeStamp timestamp not null
);

A Database setup is configured in /opt/uApprove/conf/common.properties:

storageType=database
databaseConfig=/opt/uApprove/conf/database.properties

#storageType=file
#flatFile=/opt/uApprove/data/uApprove-log.xml

Note

uApprove supports JDBC connection pooling provided by the BoneCP library.
It is possible to configure container managed connections as well as application managed connection pooling.

All database specific configuration is done in /opt/uApprove/conf/database.properties:

sqlCommands=/opt/uApprove/conf/mysql.commands

# first option to use jndi and container managed connections
# resourceName=jdbc/mypool

# second option to use application managed connection pooling
# this is provided by the bonecp library http://jolbox.com/
# these are the required parameters
driver=com.mysql.jdbc.Driver
url=jdbc:mysql://localhost:3306/uApprove
user=uApprove
password=uApprove

# optional parameters for bonecp
#
# connectionTestStatement=SELECT 1
# minConnectionsPerPartition=1
# maxConnectionsPerPartition=5
# partitionCount=2

Note

If another SQL server than MySQL is used, the values above has to be adjusted.
Don't forget to put according JDBC driver into the library folder.
If it is necessary, the SQL commands can be re-defined in /opt/uApprove/conf/custom-sql.commands

The TermsOfUseManager, which shows a Terms of use text to the user is optional. If the TermsOfUseManager should be active, define the terms in /opt/uApprove/conf/common.properties:

termsOfUse=/opt/uApprove/conf/terms-of-use.xml

Note

The shipped terms-of-use.xml is an empty one, which can be filled by custom terms of use version and text.
If you want see a real world example, take a look at the SWITCHaai VHO terms of use (doc/terms-of-use-SWITCH.xml).

Cause the IdP plugin and the viewer application exchange some confidential information, this is encrypted and decrypted by a shared secret (128 bit, 16 characters) in /opt/uApprove/conf/common.properties:

sharedSecret=QErDXYZEAoS6jooPvdBhQg==

For easy creating a random value, containing 16 chars, you can use the following command:

openssl rand -base64 16 2>/dev/null

<web-app>
  ...

  <filter>
    <filter-name>uApprove IdP plugin</filter-name>
    <filter-class>ch.SWITCH.aai.uApprove.idpplugin.Plugin</filter-class>
    <init-param>
      <param-name>Config</param-name>
      <param-value>
        /opt/uApprove/conf/idp-plugin.properties;
        /opt/uApprove/conf/common.properties;
      </param-value>
    </init-param>
  </filter>

  <filter-mapping>
    <filter-name>uApprove IdP plugin</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>

</web-app>

cd /opt/shibboleth-identityprovider/
sh install.sh

spBlacklist=/opt/uApprove/conf/sp-blacklist

# Example 1: specific resource
https://sp\.example\.org/shibboleth

# Example 2: all applications within a Service Provider
https://sp\.example\.org/.*

# Example 3: all Service Provider within a specific domain
https://.*\.example\.org/.*

logProviderAccess=false
monitoringOnly=false
uApproveViewer=https://idp.example.org/uApprove/Controller
isPassiveSupport=false

uApprove shows all attributes which will be released for the current user to the target resource.

It is possible to define a order of the attribute listing and if necessary, attributes can also be hidden. The configuration of the attribute list is optional done by /opt/uApprove/conf/idp-plugin.properties:

attributeList=/opt/uApprove/conf/attribute-list

An attribute-list can be look like:

# Defined attribute order
surname
givenName
postalAddress
...

# attributes to hide
!persistentId
!transientId

Note

The attribute name in attribute-list has to comply with the attribute id in /opt/shibboleth-idp/conf/attribute-resolver.xml

<Context docBase="/opt/uApprove/war/uApprove.war"
         privileged="true"
         antiResourceLocking="false"
         antiJARLocking="false"
         unpackWAR="false" />                             

<web-app>
  ...
  <context-param>
    <param-name>Config</param-name>
    <param-value>
        /opt/uApprove/conf/viewer.properties;
        /opt/uApprove/conf/common.properties;
    </param-value>
  </context-param>
  ...
<web-app>

cd /opt/uApprove/viewer-2.2.1/
ant deploy -Duapprove.deployment=/opt/uApprove/war

The viewer web application ist multi lingual for the static text and dynamic text, like attribute names and descrptions.
For the static text, the following languages are supported: en, de, fr, it, pt.
For the attribute names and descriptions, the localized content is taken from /opt/shibboleth-idp/conf/attribute-resolver.xml (Shibboleth IdP resolver). It's possible to adjust or extent it:

...

<resolver:AttributeDefinition id="postalAddress" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="postalAddress">
  <resolver:Dependency ref="myLDAP" />
  <resolver:DisplayName xml:lang="en">Business postal address</resolver:DisplayName>
  <resolver:DisplayName xml:lang="de">Geschäftsadresse</resolver:DisplayName>
  <resolver:DisplayName xml:lang="fr">Adresse Professionnelle</resolver:DisplayName>
  <resolver:DisplayName xml:lang="it">Indirizzo professionale</resolver:DisplayName>
  <resolver:DisplayDescription xml:lang="en">Business postal address: Campus or office address</resolver:DisplayDescription>
  <resolver:DisplayDescription xml:lang="de">Adresse am Arbeitsplatz</resolver:DisplayDescription>
  <resolver:DisplayDescription xml:lang="fr">Adresse de l'institut, de l'universite</resolver:DisplayDescription>
  <resolver:DisplayDescription xml:lang="it">Indirizzo professionale: Indirizzo dell'istituto o dell'ufficio</resolver:DisplayDescription>
  <resolver:AttributeEncoder xsi:type="SAML1String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
                             name="urn:mace:dir:attribute-def:postalAddress" />
  <resolver:AttributeEncoder xsi:type="SAML2String" xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
                             name="urn:oid:2.5.4.16" friendlyName="postalAddress" />
</resolver:AttributeDefinition>
...

Note

For the SWITCHaai attributes, there is a prepared doc/attribute-descriptions.xml for the languages: en, de, fr, it.

The viewer uses the language from the users browsers request, if that language is not available, the default locale en will be taken.
It is possible to enforce a specific language. This can be defined optional in /opt/uApprove/conf/viewer.properties:

useLocale=US_en

It is possible that a user can give global attribute release consent, which mean, that she/he is never be asked again by uApprove. If it is required, that a user has to give consent to each different resource access, global consent has to be disabled in /opt/uApprove/conf/viewer.properties:

globalConsentPossible=true

The viewer web application uses LogBack (see references) like the Shibboleth IdP.
The logback configuration file is defined in /opt/uApprove/conf/viewer.properties:

loggingConfig=/opt/uApprove/conf/logging.xml

Adjust logging.xml for the log location, assure that the file is writeable by Tomcat:

<configuration>
  ...
  <appender class="ch.qos.logback.core.FileAppender" name="RootFileAppender">
    <file>/opt/uApprove/logs/uApprove.log</file>
    ...
  </appender>
  ...
</configuration>

If you are using Apache HTTPd in front of your Tomcat setup, proxy the viewer web application in /etc/apache2/sites-enabled/idp.example.org:

<VirtualHost idp.example.org:443>
  ...
  <Location /uApprove>
    Allow from all
    ProxyPass ajp://localhost:8009/uApprove
  </Location>
  ...
</VirtualHost>

Restart Apache HTTPd:

/etc/init.d/apache2 restart

The optional reset-approvals can be operated in two ways:

In-flow mode

The In-flow operation means, that a user can reset his setting during the login process. As exampple this is done by a checkbox on the login form.

Standalone mode

The standalone operation can is as JSP which can be called directly.

Warning

The reset-approvals application can only used with a database setup.

For enabling the In-Flow reset-approvals application, the Shibboleth UsernamePassword login form /opt/tomcat/webapps/idp/login.jsp can be adapted by adding a checkbox:

Warning

Followed, the In-Flow reset-settings application configuration is for the shipped JAAS UsernamePassword login handler. If you are using another login handler (i.e. RemoteUser) you have to assure, that the GET parameter is transmitted to the IdP plugin.

...
<form ...>
  <table>
  ...
    <tr>
      <td colspan="2">
        <input type="checkbox" name="resetuserconsent" value="true" />
        Reset my attribute release approvals
      </td>
    </tr>
  </table>
</form>
...

For the standalone mode, the JSP has to be protected either by container managed authentication or Shibboleth Service Provider, that the REMOTE_USER is provided.

The standalone JSP can be called like https://idp.example.org/uApprove/reset-approvals.jsp?standalone_next_url=http://go.here.org/after/reset. The parameter standalone_next_url has to be set.

Restart Tomcat:

/opt/tomcat/bin/shutdown.sh && sleep 10 && /opt/tomcat/bin/startup.sh

Note

If the Tomcat manager (http://idp.example.org:8080/manager/html/) is installed, web applications can easily be restarted separate.

Note

Check the logs, if the startup of the IdP and uApprove web application was succesful.
If it was succesful, try to access any Service Provider using your Identity Provider.

Cause the IdP plugin runs within the Shibboleth IdP web application, it uses the IdP logger. The IdP logger is configured by /etc/shibboleth-idp/logging.xml:

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

The logging of uApprove viewer application is configured as described. Adjust the log level to DEBUG.

uApprove is shipped for a JDK 1.5 target. However your Tomcat setup runs with an JDK ≥ 1.5, it could be that the Jasper engine compiles the JSP's on the fly for another target (e.g. 1.3). The following configuration in TOMCAT_HOME\conf\web.xml specifies for which target the JSP's has to be compiled:

<servlet>
  ...
  <init-param>
    <param-name>compilerSourceVM</param-name>
    <param-value>1.5</param-value>
  </init-param>
  <init-param>
    <param-name>compilerTargetVM</param-name>
    <param-value>1.5</param-value>
  </init-param>
  ...
</servlet>

• Shibboleth Identity Provider 2.2 deployment guide
• LogBack manual

• uApprove.jp: uApprove including selection of optional attributes to be released (Japanese federation GakuNin)

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