This document contains the PrivacyLens deployment guide and the general manual.

PrivacyLens is an extension for the Shibboleth Identity Provider 3.x. It provides an interface to allow users to review the personal information that will be sent to a requesting web site, and to opt in or out of disclosing it. PrivacyLens grew out of uApprove. PrivacyLens' web page is at

Notes about this guide:

  1. 1 Installation
    1. 1.1 Prerequisites
    2. 1.2 Building PrivacyLens from source
    3. 1.3 Library Installation
    4. 1.4 PrivacyLens WebFlow files
    5. 1.5 PrivacyLens view templates
    6. 1.6 Configuration Template
    7. 1.7 Database Preparation
  2. 2 Basic Deployment
    1. 2.1 PrivacyLens Flow insertion
    2. 2.2 Custom Configuration
    3. 2.3 Custom Templates
    4. 2.4 Configure administrative interface
    5. 2.6 Configuring the Oracle
    6. 2.7 Deployment
  3. 3 Upgrade
    1. 3.1 General procedure
  4. 4 Advanced Deployment
    1. 4.1 Custom SQL Statements
    2. 4.2 Templates
      1. Custom View Templates
    3. 4.6 Machine readable attributes
    4. 4.7 Descriptive entitlements
    5. 4.8 Black/Whitelisting
  5. 5 Troubleshooting
    1. Debugging
  6. 6 Feedback
  7. 7 Abbreviations

1 Installation

1.1 Prerequisites

1.2 Building PrivacyLens from source

If you are not using a downloaded binary package of PrivacyLens, create one using Maven with the command mvn install. This will create a binary package ZIP file in the target/ directory.

1.3 Library Installation

If the Shibboleth Identity Provider has not yet been installed, proceed with a normal installation of Shibboleth. Make a note of the directory you unpacked the
source to ( $SHIB_DIST$, e.g. /usr/local/src/shibboleth-identity-provider-#version#), and the directory the web application was installed into ( $SHIB_INSTALL$, e.g. /opt/shibboleth-idp).

Ensure your installation of Shibboleth is working correctly.

Ensure that only one version of each jar file is present in $SHIB_DIST$/webapp/WEB-INF/lib.

1.4 PrivacyLens WebFlow files

Copy the PrivacyLens flow and component configuration files to the Shibboleth flow directory:

1.5 PrivacyLens view templates

Copy the PrivacyLens view templates ( JSPs, CSS files, images and JavaScript libraries) to directories under Shibboleth’s webapp directory:

1.6 Configuration Template

Copy the configuration template to Shibboleth’s configuration directory:

1.7 Database Preparation

The following database parameters are examples. Adapt the values as necessary. Choose a secure password.

2 Basic Deployment

2.1 PrivacyLens Flow insertion

Edit $SHIB_INSTALL$/conf/intercept/profile-intercept.xml and add PrivacyLens to the list of available intercept flows.

            <list merge="true">
                <bean id="intercept/privacy-lens" parent="privacylens.consent.AttributeReleaseFlow" />

Add PrivacyLens configuration information to the same file as shown.

<bean id="privacylens.config.General"
    p:credits="%{general.credits}" />

<bean id="privacylens.Oracle"
    p:config="/opt/shibboleth-idp/conf/spsetup.json" />

    <!-- Parent bean for attribute release consent flows. -->
<bean id="privacylens.consent.AttributeReleaseFlow" abstract="true"
    <property name="activationCondition">
        <bean parent="shibboleth.Conditions.OR">
                <bean parent="shibboleth.Conditions.NOT">
                    <constructor-arg value="%{idp.consent.allowPerAttribute:false}" />
                <bean class="net.shibboleth.idp.saml.profile.config.logic.IncludeAttributeStatementPredicate" />

Add the PrivacyLens properties file to the available properties of the IdP:

idp.additionalProperties= /conf/, /conf/, /conf/, /conf/

2.2 Custom Configuration

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

In case of database connectivity problems, you may want to set the “graceful” property to “true” in $SHIB_INSTALL$/flows/intercept/privacy-lens/privacy-lens-beans.xml:

<property name="storage">
  <bean class="" init-method="initialize"
  p:dataSource-ref="DataSource" p:sqlStatements="classpath:/storage/" p:graceful="false" />

You may then want to provide an appropriate timeout setting to the database configuration in $SHIB_INSTALL$/conf/

2.3 Custom Templates

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

You should at the least copy your organization’s logo to the file $SHIB_DIST$/src/main/webapp/PrivacyLens/img/logo.png, since a placeholder logo is installed by default.
You may also want to put your federation’s logo to the file $SHIB_DIST$/src/main/webapp/PrivacyLens/img/federation-logo.png (which is an empty placeholder logo by default).

2.4 Configure administrative interface

On the client side, the web server and the Shibboleth module have to be configured.

<Location /admin/Shibboleth.sso>
  SetHandler shib

<Location /admin>
  AuthType shibboleth
  ShibRequestSetting requireSession 1
  Require shib-session

<ApplicationOverride id="admin" entityID="https://<SP host>/admin">
  <Sessions lifetime="28800" timeout="3600" checkAddress="false" handlerURL="/admin/Shibboleth.sso" />

Server side configuration
In $SHIB_INSTALL$/conf/, the property general.adminUrl determines the Service Provider identifier that should cause the PrivacyLens administrative interface to be presented.

<MetadataProvider id="AdminSP" xsi:type="FileBackedHTTPMetadataProvider"

Provide the full set of attributes to users of this Service Provider, and require authentication.

general.adminUrl = https://$SP_HOST$/admin

2.6 Configuring the Oracle

As there is currently no reliable transmission of requested and required attributes from a Service Provider when it refers a user to his home Identity Provider, PrivacyLens is currently referring to a configuration file to provide these details. Adjust $SHIB_INSTALL$/conf/spsetup.json to fit your environment. The file is in JSON format.

The id field for a Service Provider definition is interpreted as a regular expression. By ordering the definitions from specific to general, specific information can be shown for some Service Providers, yet general information still provided for others. To specify a definition that should be matched successfully for all Service Providers, the id field can be set to DEFAULT.

      "id":Attribute identifier within Shibboleth,
      "desc":Human readable description of attribute
      "name":Human readable name of the Service Provider,
      "id":Regular expression to match against Service Provider identifier within Shibboleth,
          "id":Attribute group identifier,
          "description":Human readable description of attribute group,
          "reason":HTML text describing reason for requesting the attribute group,
          "privpolicy":HTML text with privacy policy for attribute group data
          "id":Attribute identifier within Shibboleth,
          "reason":HTML text describing reason for requesting this attribute,
          "privpolicy":HTML text with privacy policy for this attribute,
          "required":Does the Service Provider require this attribute (true/false),
          "group":Group this attribute with others by this attribute group identifier

2.7 Deployment

To activate PrivacyLens, Shibboleth must be re-deployed:


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

3 Upgrade

3.1 General procedure

4 Advanced Deployment

This sections contains advanced configuration topics.

4.1 Custom SQL Statements

    <bean id="AttributeReleaseModule" class="" init-method="initialize"
        <!-- ... -->
        <property name="storage">
            <bean class="" init-method="initialize"
               p:sqlStatements="file:/$SHIB_INSTALL$/conf/" ... />

4.2 Templates

Custom View Templates

Feel free to customize the PrivacyLens view templates in $SHIB_DIST$/webapp/WEB-INF/jsp/PrivacyLens/.

4.6 Machine readable attributes

PrivacyLens can be configured to not show the value of attributes that
are intended for data processing, and not human comprehension. In the
file $SHIB_INSTALL$/conf/, add the desired attributes to “ar.attributes.machinereadable”, each separated by a space. For example:

ar.attributes.machinereadable = eduPersonEntitlement anotherAttribute

4.7 Descriptive entitlements

The eduPersonEntitlement attribute is a set of URIs, each specifying rights to access resources. A glossary of entitlement URIs can be defined in $SHIB_INSTALL$/conf/ with the ar.attributes.entitlement.description property. Each translation is specified with the coded value in quotes, followed by a comma, followed by the translation in quotes. Multiple translations are separated from each others by spaces, as can be seen in the following example (line break has been inserted for clarity, but is equivalent to a separating space):

ar.attributes.entitlement.description = "urn:mace:dir:entitlement:common-lib-terms","Library Resource Access" \
  "","Secpass B"

4.8 Black/Whitelisting

PrivacyLens can be configured to show or not show the interface, depending on what Service Provider is involved. In the file, regular expressions that the Service Provider will be matched again are provided to “services”. If “services.blacklist” is true, the user will not see the interface for any Service Provider that matches the regular expressions. If “services.blacklist” is false, the user will only see the interface for Service Providers that match the regular expressions.

5 Troubleshooting


Enabling DEBUG or TRACE log level for PrivacyLens in $SHIB_INSTALL$/conf/logback.xml:

<logger name="edu.cmu.ece.PrivacyLens" level="DEBUG"/>

6 Feedback

Send general questions and comments to For bug reports, please use our issue tracking facility.

7 Abbreviations

Cascading Style Sheet
Java Database Connectivity
Javascript Object Notation
Java Server Pages
Uniform Resource Indicator