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 www.privacylens.org

Notes about this guide:

This guide assumes that PrivacyLens will be installed on a Linux system. It’s also possible to install it on a different operating system. In this case, you may need to adapt some paths and commands accordingly.
The guide shows paths and commands using variables like, e.g, $SHIB_DIST$ , $SHIB_INSTALL$ or $PLENS_DIST$ . You need to expand these variables to the real paths, except where it is explicitly stated that you don’t need to expand them.

1 Installation

1.1 Prerequisites

Shibboleth Identity Provider, version 3.2.0 or greater.
PrivacyLens, either source or binary package.
Database which supports JDBC.

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.

Unpack the binary package ZIP file in $PLENS_DIST$ (e.g., /usr/local/src/PrivacyLens-#version#).
Copy the jar files to Shibboleth’s library directory:
- cp $PLENS_DIST$/lib/*.jar $SHIB_DIST$/webapp/WEB-INF/lib
- cp $PLENS_DIST$/lib/jdbc/*.jar $SHIB_DIST$/webapp/WEB-INF/lib
Copy the JDBC connector for your database to Shibboleth’s classpath. PrivacyLens itself already provides MySQL or HSQL JDBC connectors:
cp $PLENS_DIST$/lib/jdbc/optional/#jdbc-connector#.jar $SHIB_DIST$/webapp/WEB-INF/lib

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:

mkdir -p $SHIB_INSTALL$/flows/intercept/privacy-lens
cp $PLENS_DIST$/flows/intercept/privacy-lens/*.xml $SHIB_INSTALL$/flows/intercept/privacy-lens/

1.5 PrivacyLens view templates

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

mkdir -p $SHIB_DIST$/webapp/WEB-INF/jsp/PrivacyLens
cp -r $PLENS_DIST$/webapp/PrivacyLens/*.jsp $SHIB_DIST$/webapp/WEB-INF/jsp/PrivacyLens
cp -r $PLENS_DIST$/webapp/PrivacyLens/jquery $SHIB_DIST$/webapp/PrivacyLens/jquery
cp -r $PLENS_DIST$/webapp/PrivacyLens/img $SHIB_DIST$/webapp/PrivacyLens/img
cp -r $PLENS_DIST$/webapp/PrivacyLens/css $SHIB_DIST$/webapp/PrivacyLens/css

1.6 Configuration Template

Copy the configuration template to Shibboleth’s configuration directory:

cp $PLENS_DIST$/manual/configuration/PrivacyLens.properties $SHIB_INSTALL$/conf
cp $PLENS_DIST$/manual/configuration/PrivacyLens.xml $SHIB_INSTALL$/conf
cp $PLENS_DIST$/manual/configuration/spsetup.json $SHIB_INSTALL$/conf

1.7 Database Preparation

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

Create a database with the name “PrivacyLens”.
Create a database user with the username “PrivacyLens” and password “secret”.
Grant INSERT, SELECT, UPDATE, DELETE rights to user “PrivacyLens”.
Create the initial table structures using the schemas:
- $PLENS_DIST$/manual/storage/attribute-release-schema.sql

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

Add PrivacyLens configuration information to the same file as shown.

<bean id="privacylens.config.General"
    class="edu.cmu.ece.privacylens.config.General"
    init-method="initialize"
    factory-method="getInstance"
    p:idpName="%{general.IdPName}"
    p:adminUrl="%{general.adminUrl}"
    p:adminMail="%{general.adminMail}"
    p:credits="%{general.credits}" />

<bean id="privacylens.Oracle"
    class="edu.cmu.ece.privacylens.Oracle"
    init-method="initialize"
    factory-method="getInstance"
    p:config="/opt/shibboleth-idp/conf/spsetup.json" />

    <!-- Parent bean for attribute release consent flows. -->
<bean id="privacylens.consent.AttributeReleaseFlow" abstract="true"
        class="edu.cmu.ece.privacylens.consent.flow.ar.AttributeReleaseFlowDescriptor"
        p:storageService-ref="#{'%{idp.consent.StorageService:shibboleth.ClientPersistentStorageService}'.trim()}"
        p:doNotRememberConsentAllowed="%{idp.consent.allowDoNotRemember:true}"
        p:globalConsentAllowed="%{idp.consent.allowGlobal:true}"
        p:perAttributeConsentEnabled="%{idp.consent.allowPerAttribute:false}"
        p:compareValues="%{idp.consent.compareValues:false}"
        p:lifetime="%{idp.consent.storageRecordLifetime:P1Y}"
        p:maximumNumberOfStoredRecords="%{idp.consent.maxStoredRecords:10}"
        p:nonBrowserSupported="false">
    <property name="activationCondition">
        <bean parent="shibboleth.Conditions.OR">
            <constructor-arg>
                <bean parent="shibboleth.Conditions.NOT">
                    <constructor-arg value="%{idp.consent.allowPerAttribute:false}" />
                </bean>
            </constructor-arg>
            <constructor-arg>
                <bean class="net.shibboleth.idp.saml.profile.config.logic.IncludeAttributeStatementPredicate" />
            </constructor-arg>
        </bean>
    </property>
</bean>

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

idp.additionalProperties= /conf/ldap.properties, /conf/saml-nameid.properties, /conf/services.properties, /conf/PrivacyLens.properties

2.2 Custom Configuration

Customize $SHIB_INSTALL$/conf/PrivacyLens.properties according your database environment and required features. See inline documentation of PrivacyLens.properties 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="edu.cmu.ece.privacylens.ar.storage.JDBCStorage" init-method="initialize"
  p:dataSource-ref="DataSource" p:sqlStatements="classpath:/storage/sql-statements.properties" p:graceful="false" />
</property>

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

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.

For Apache, add these lines to the configuration to have Shibboleth handle these URLs:

<Location /admin/Shibboleth.sso>
  SetHandler shib
</Location>

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

Configure /etc/shibboleth/shibboleth2.xml to assign a new application to the administrative URL:

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

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

Define the metadata cache for the new virtual Service Provider (this file will be created by the Identity Provider). Modify $SHIB_INSTALL$/conf/metadata-providers.xml and add the following:

<MetadataProvider id="AdminSP" xsi:type="FileBackedHTTPMetadataProvider"
                  metadataURL="https://$SP_HOST$/admin/Shibboleth.sso/Metadata"
                  backingFile="$SHIB_INSTALL$/metadata/AdminSP.xml">
</MetadataProvider>

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

Ensure the virtual Service Provider is defined in $SHIB_INSTALL$/conf/PrivacyLens.properties:

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.

{
  "attrs":[
    {
      "id":Attribute identifier within Shibboleth,
      "desc":Human readable description of attribute
    },
    ...
  ],
  "SPs":[
    {
      "name":Human readable name of the Service Provider,
      "id":Regular expression to match against Service Provider identifier within Shibboleth,
      "attrGroups":[
        {
          "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
        },
        ...
      ],
      "attrs":[
        {
          "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:

cd $SHIB_DIST$
./bin/install.sh

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

3 Upgrade

3.1 General procedure

Redo the installation steps Library Installation, PrivacyLens WebFlow files, PrivacyLens view templates. These do not hold configuration settings.
Adapt any customizations you may have done to the view templates.
Deploy Shibboleth as in section Deployment above.

4 Advanced Deployment

This sections contains advanced configuration topics.

4.1 Custom SQL Statements

Copy $PLENS_DIST$/manual/storage/sql-statements.properties to $SHIB_INSTALL$/conf/PrivacyLens.sql-statements.properties.
Adjust $SHIB_INSTALL$/conf/PrivacyLens.sql-statements.properties according your needs.
Enable your custom sql-statements.properties in $SHIB_INSTALL$/flows/intercept/privacy-lens/privacy-lens-beans.xml:

    <bean id="AttributeReleaseModule" class="edu.cmu.ece.privacylens.ar.AttributeReleaseModule" init-method="initialize"
        <!-- ... -->
        <property name="storage">
            <bean class="edu.cmu.ece.privacylens.ar.storage.JDBCStorage" init-method="initialize"
               p:sqlStatements="file:/$SHIB_INSTALL$/conf/PrivacyLens.sql-statements.properties" ... />
        </property>
    </bean>

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/PrivacyLens.properties, 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/PrivacyLens.properties 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" \
  "urn:example.org:entitlement:entitlement1","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 PrivacyLens.properties 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

Check $SHIB_INSTALL$/logs/idp-process.log for ERROR or WARN messages.
Check the web application container logs (e.g., Jetty’s logs are in $JETTY_HOME$/logs/) for any error messages.

Debugging

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 privacylens@ece.cmu.edu. For bug reports, please use our issue tracking facility.

7 Abbreviations

CSS: Cascading Style Sheet
JDBC: Java Database Connectivity
JSON: Javascript Object Notation
JSP: Java Server Pages
URI: Uniform Resource Indicator