URL: http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/idp/install-idp-1.3-debian.html
Author: Patrik Schnellmann - SWITCH
Author: Valery Tschopp - SWITCH
Author: Lukas Haemmerle - SWITCH
$Date: 2009/01/16 12:40:22 $
$Revision: 1.60 $ 

Install Shibboleth 1.3 Identity Provider on Debian 4.0 (etch), Tomcat only with CAS SSO

Table of Contents

1. Introduction
2. Overview
3. Prerequisites
4. Java 1.5 Installation
5. Tomcat 5.5 Installation
6. Shibboleth IdP 1.3 Installation
7. Central Authentication System (CAS) - Single Sign On (SSO)
8. X.509 Server Certificates
9. Tomcat 5.5 Configuration
10. Shibboleth IdP 1.3 Configuration
11. AAI Resource Registry
12. Links

1. Introduction

This guide describes Debian specific installation of a Shibboleth Identity Provider 1.3 and its configuration for the SWITCHaai Federation. It covers installation with Tomcat 5.5 and the Single Sign On system CAS. The Shibboleth Wiki provides information about other deployments.

Note: Load Balancing for the IdP
This guide covers the setup of once single IdP server. For load-balanced setups, the Shibboleth Wiki has useful information.

Note: Setting up an Identity Provider with Tomcat only as web server is less complex than with Apache and mod_jk as front-end. However, the Tomcat-only setup has also some disadvantages concerning speed and security. SSL handshake is performed slower by Tomcat as it would be by Apache. Furthermore, Tomcat in the default configuration of this guide is run as root user. Although Tomcat has a good track record when it comes to security holes it is recommended to prevent Tomcat running as root user. Therefore, you may have a look at the guide that describes how to run tomcat with an unprivileged user after going through this guide.

Note: If you want to join the AAI-Test Federation instead of the production SWITCHaai Federation, please consult the AAI-Test Reconfiguration guide after following the instructions on this page.

Note: For general information about the deployment of Shibboleth within the SWITCHaai Federation, please consult the technical support pages of the SWITCHaai website (http://www.switch.ch/aai/).

2. Overview

The Shibboleth Identity Provider (IdP) 1.3 is implemented in Java and can be run as a Java web application in Tomcat. The IdP consists of the two servlets SSO (Single Sign On) and AA (Attribute Authority). The users access the SSO servlet which requires authentication. The Shibboleth IdP does not include an SSO functionality, so authentication has to be handled outside of the IdP by means of an SSO system (like CAS for Tomcat or Pubcookie for Apache) or Tomcat authentication. The AA servlet is accessed by the Shibboleth Service Provider (SP) and has to be protected with SSL client authentication. This means that for a Tomcat-only installation two IP-addresses/DNS entries and corresponding server certificates will be needed. If Subject Alternative Names (Subject AltNames) are going to be used, the same server certificate can be used for both server names. Without Subject AltNames, two server certificates will be needed.

The example values used in this guide are:

www.example.org
The DNS name of the Home Organization (Identity Provider) server, for real installations instead of "www", names like "aai-logon", "aai" or something similar are used. In the Tomcat connector configuration, the matching IP address is IP_ADDRESS_1.
aai-aa.example.org
The DNS name of the server where the Home Organization's Attribute Authority is running. It is usually the same server as the one above, but the different name is needed for a Tomcat-only installation and also when using Apache 2 as a frontend for Tomcat. In the Tomcat connector configuration, the matching IP address is IP_ADDRESS_2.
ldap.example.org
The name of the LDAP server where the user attributes are stored.

3. Prerequisites

As indicated in the title, this guide applies to Debian 4.0 (etch) and contains some references to Debian specific tools. However, the Shibboleth IdP can be installed on every system which allows you to run a Java virtual machine and a web application server like Tomcat. The following packages should be installed on your system prior to the installation:

OpenSSL
Recommended Version 0.9.8, Debian Package: openssl
The OpenSSL tools will be used to handle server certificates.
NTP
Debian Package: ntp-server (or any other package which provides time-synchronization)
Servers running Shibboleth should have their system time synchronized in order to avoid clock-skews.

4. Java 1.5 Installation

The official Java 1.5 from Sun is available as a package in Debian etch. However, to have the latest version, some prefer to install Java manually. This section shows the installation of the official Debian package and how to install Sun Java 1.5 without a packaging system.

4.1 Install the Debian etch Java 1.5 JDK package

$ sudo apt-get install sun-java5-jdk
If you install this package, the following dependent packages will also be installed (among others): sun-java5-bin, sun-java5-jre, sun-java5-demo. Java will be installed in /usr/lib/jvm/java-1.5.0-sun. To avoid conflicts with other Java virtual machines like kaffe or gcj, deinstalling them is highly suggested.

You may also include the following lines in /etc/profile:

JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun export JAVA_HOME

Once Java is installed, the rest of this section can be skipped.

4.2 Install Java 1.5 manually

  1. Download J2SE Development Kit (JDK) 1.5 for Linux from http://java.sun.com
  2. Install Java 1.5 in directory /opt.
    $ cd /opt $ chmod a+x jdk-1_5_0_14-linux-i586.bin $ ./jdk-1_5_0_14-linux-i586.bin $ ln -s /opt/jdk1.5.0_14 /opt/java
  3. Use Debian update-alternatives to include the Java binaries into the system path.
    $ export JAVA_HOME=/opt/java $ /usr/sbin/update-alternatives --install /usr/bin/java java \ $JAVA_HOME/bin/java 200 $ /usr/sbin/update-alternatives --install /usr/bin/javac javac \ $JAVA_HOME/bin/javac 200 $ /usr/sbin/update-alternatives --install /usr/bin/jar jar \ $JAVA_HOME/bin/jar 200 $ /usr/sbin/update-alternatives --install /usr/bin/keytool keytool \ $JAVA_HOME/bin/keytool 200

You may also include the following lines in /etc/profile:

JAVA_HOME=/opt/java export JAVA_HOME

5. Tomcat 5.5 Installation

Tomcat 5.5 is the recommended version to use together with Shibboleth Identity Provider 1.3. Debian etch includes a Tomcat 5.5 package (version 5.5.20). To get a later version, Tomcat still has to be installed manually. This section shows the manual installation of Tomcat 5.5.

  1. Download Tomcat 5.5.x from http://tomcat.apache.org/.
  2. Unpack apache-tomcat-5.5.26.tar.gz in /opt.
    $ cd /opt $ tar -xzf apache-tomcat-5.5.26.tar.gz
  3. Create symlinks to facilitate access to configuration and log directories of Tomcat:
    $ ln -s /opt/apache-tomcat-5.5.26 /opt/tomcat $ ln -s /opt/tomcat/conf /etc/tomcat $ ln -s /opt/tomcat/logs /var/log/tomcat
  4. Remove unnecessary files from /opt/tomcat/bin:
    $ cd /opt/tomcat/bin $ rm *.exe *.bat
  5. Remove web applications you don't need from /opt/tomcat/webapps:
    $ cd /opt/tomcat/webapps $ rm -rf balancer servlets-examples jsp-examples webdav tomcat-docs
  6. Create a symlink to catalina.sh which is used by the tomcat startup script below.
    $ ln -s /opt/tomcat/bin/catalina.sh /usr/bin/tomcat
  7. Install an init.d startup script as /etc/init.d/tomcat (this is a Tomcat 4 startup script from the Debian distribution, modified for Tomcat 5):
    #! /bin/sh -e # # /etc/init.d/tomcat -- startup script for the Tomcat 5.0 servlet engine # # Written by Miquel van Smoorenburg <miquels@cistron.nl>. # Modified for Debian GNU/Linux by Ian Murdock <imurdock@gnu.ai.mit.edu>. # Modified for Tomcat by Stefan Gybas <sgybas@debian.org>. PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin NAME=tomcat DESC="Tomcat 5.5 servlet engine" DAEMON=/usr/bin/$NAME CATALINA_HOME=/opt/$NAME # The following variables can be overwritten in /etc/default/tomcat5 # Run Tomcat 5.5 as this user ID (default: tomcat5) # Set this to an empty string to prevent Tomcat from starting automatically TOMCAT5_USER=root # The first existing directory is used for JAVA_HOME (if JAVA_HOME is not # defined in /etc/default/tomcat5) JDK_DIRS="/opt/java /usr" # Arguments to pass to the Java virtual machine (JVM) CATALINA_OPTS="" # Use the Java security manager? (yes/no) TOMCAT5_SECURITY="no" # End of variables that can be overwritten in /etc/default/tomcat5 # overwrite settings from default file if [ -f /etc/default/tomcat5 ]; then . /etc/default/tomcat5 fi test -f $DAEMON || exit 0 # Look for the right JVM to use for jdir in $JDK_DIRS; do if [ -d "$jdir" -a -z "${JAVA_HOME}" ]; then JAVA_HOME="$jdir" fi done export JAVA_HOME export CATALINA_OPTS # Define other required variables PIDFILE="/var/run/$NAME.pid" LOGDIR="$CATALINA_HOME/logs" WEBAPPDIR="$CATALINA_HOME/webapps" STARTUP_OPTS="" if [ "$TOMCAT5_SECURITY" = "yes" ]; then STARTUP_OPTS="-security" fi # CATALINA_PID for catalina.sh export CATALINA_PID="$PIDFILE" case "$1" in start) if [ -z "$TOMCAT5_USER" ]; then echo "Not starting $DESC as configured (TOMCAT5_USER is empty in" echo "/etc/default/tomcat5)." exit 0 fi if [ -z "$JAVA_HOME" ]; then echo "Could not start $DESC because no Java Development Kit" echo "(JDK) was found. Please download and install JDK 1.3 or higher and set" echo "JAVA_HOME in /etc/default/tomcat5 to the JDK's installation directory." exit 0 fi echo -n "Starting $DESC using Java from $JAVA_HOME: " # Remove dangling webapp symlinks for webapp in "$WEBAPPDIR"/*; do if [ "$webapp" != "$WEBAPPDIR/*" -a ! -e "$webapp" ]; then echo "Removing obsolete webapp $webapp" >>"$LOGDIR/catalina.out" rm "$webapp" >> "$LOGDIR/catalina.out" 2>&1 || true fi done # Symlink new webapps from /usr/share/java/webapps for webapp in /usr/share/java/webapps/*; do if [ -e "$webapp" -a ! -e "$WEBAPPDIR/`basename $webapp`" \ -a ! -e "$WEBAPPDIR/`basename $webapp .war`" ]; then echo "Symlinking new webapp $webapp" >>"$LOGDIR/catalina.out" ln -s "$webapp" "$WEBAPPDIR" || true fi done mkdir -p "$CATALINA_HOME/work/_temp" touch "$PIDFILE" "$LOGDIR/catalina.out" || true chown --dereference "$TOMCAT5_USER" "$PIDFILE" "$LOGDIR" \ "$LOGDIR/catalina.out" "$CATALINA_HOME/work" \ "$CATALINA_HOME/temp" || true if start-stop-daemon --test --start --pidfile "$PIDFILE" \ --user $TOMCAT5_USER --startas "$DAEMON" >/dev/null; then # -p preserves the environment (for $JAVA_HOME etc.) # -s is required because tomcat5's login shell is /bin/false su -p -s /bin/sh $TOMCAT5_USER \ -c "\"$DAEMON\" start $STARTUP_OPTS" \ >>"$LOGDIR/catalina.out" 2>&1 echo "$NAME." else echo "(already running)." fi ;; stop) echo -n "Stopping $DESC: " if start-stop-daemon --test --start --pidfile "$PIDFILE" \ --user $TOMCAT5_USER --startas "$DAEMON" >/dev/null; then echo "(not running)." else su -p $TOMCAT5_USER -c "\"$DAEMON\" stop" >/dev/null 2>&1 || true # Fallback to kill the JVM process in case stopping did not work sleep 1 start-stop-daemon --stop --oknodo --quiet --pidfile "$PIDFILE" \ --user "$TOMCAT5_USER" rm -f "$PIDFILE" echo "$NAME." fi ;; restart|force-reload) $0 stop sleep 1 $0 start ;; *) echo "Usage: /etc/init.d/tomcat {start|stop|restart|force-reload}" >&2 exit 1 ;; esac exit 0
  8. Update the different rc.d to start automatically Tomcat with the default runlevels:
    $ update-rc.d tomcat defaults

6. Shibboleth IdP 1.3 Installation

  1. Get Shibboleth IdP 1.3.3 from http://shibboleth.internet2.edu/downloads/
  2. Extract the shibboleth-idp-1.3.3.tar.gz in directory /opt. The .tar.gz file will be extracted into the directory shibboleth-1.3.3-install:
    $ cd /opt $ tar -xzf shibboleth-idp-1.3.3.tar.gz
  3. Modify the support contact E-Mail address in /opt/shibboleth-1.3.3-install/webApplication/IdPError.jsp:
  4. Set environment variable for Java:
    $ export JAVA_HOME=/opt/java
  5. Install the Shibboleth IdP package in /opt/shibboleth-idp and the webapplication in /opt/tomcat/webapps.
    $ cd /opt/shibboleth-1.3.3-install $ ./ant build-util $ ./ant Do you want to install the Shibboleth Identity Provider? [Y,n] Y What name do you want to use for the Identity Provider web application? [default: shibboleth-idp] shibboleth-idp Deploying the java web application. Do you want to install it directly onto the filesystem or use the tomcat manager application? 1) filesystem (default) 2) manager 1 Select a home directory for the Shibboleth Identity Provider [default: /usr/local/shibboleth-idp] /opt/shibboleth-idp Enter the tomcat home directory [default: /usr/local/tomcat] /opt/tomcat [further output omitted]
  6. The implementation of Sun's JAXP parser has been identified as containing a memory leak. Therefore, the XML libraries from the Shibboleth IdP distribution should be used in tomcat. Any pre-existing Xalan and Xmlsec .jar files in /opt/tomcat/common/endorsed/ may conflict with the new versions and should therefore be removed.

    $ rm /opt/tomcat/common/endorsed/*.jar
    Copy the jar files /opt/shibboleth-idp/endorsed/*.jar which come with the Shibboleth IdP 1.3 package:
    $ cp -p /opt/shibboleth-idp/endorsed/*.jar /opt/tomcat/common/endorsed/
  7. Set symbolic links /etc/shibboleth to the shibboleth-idp configuration directory and /var/log/shibboleth to the shibboleth-idp log directory:
    $ ln -s /opt/shibboleth-idp/etc /etc/shibboleth $ ln -s /opt/shibboleth-idp/logs /var/log/shibboleth
  8. Set the IDP_HOME environment variable:
    $ export IDP_HOME=/opt/shibboleth-idp
  9. You may also include the following line into your /etc/profile file:
    export IDP_HOME=/opt/shibboleth-idp

7. Central Authentication System (CAS) Single Sign On (SSO)

7.1 CAS Server Web Application

The Central Authentication System (CAS) handles user authentication against different backends like LDAP, SQL databases, NIS, Kerberos, etc. Depending on the backend to be used, there are three solutions:

  1. For LDAP and SQL databases, use the CAS Generic Handler. Please refer to the documentation on http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/idp/install-esupcas.html.
  2. For Kerberos authentication, use the KerberosAuthHandler. See the instructions on http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/idp/install-cas.html.
  3. If all else fails, implement an own Authentication Handler, which is described in the documentation distributed with the CAS Server.

7.2 CAS Client

Get the Java CAS Client (version 2.1.1) from http://www.ja-sig.org/products/cas/.

  1. Unpack the cas-client-java-2.1.1.tar.gz file and build cas with ant. If you don't have ant installed on your system, you may use the ant tool that comes with the shibboleth-idp (/opt/shibboleth-1.3.3-install/ant).
    $ cd /opt $ tar -xzf ./cas-client-java-2.1.1.tar.gz $ cd cas-client-java-2.1.1 $ ant jar
  2. Enable the Shibboleth web application to use CAS Single Sign On. Lateron, after the installation of the Shibboleth web application, the casclient.jar can be found in /opt/tomcat/webapps/shibboleth-idp/WEB-INF/lib/.
    $ cp /opt/cas-client-java-2.1.1/dist/casclient.jar \ /opt/shibboleth-1.3.3-install/webApplication/WEB-INF/lib/
  3. Modify the file /opt/shibboleth-1.3.3-install/webAppConfig/dist.idp.xml to use the CAS Filter as follows. (The modifications will not be effective until the Shibboleth IdP web application is deployed again.)
    Note:
    In case your CAS server is not on the same host as your Shibboleth IdP server, be careful to choose the correct URLs in this config!
    <?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd"> <web-app> <context-param> <param-name>IdPConfigFile</param-name> <param-value>file:///etc/shibboleth/idp.xml</param-value> </context-param>
    <filter> <filter-name>CASFilter</filter-name> <filter-class>edu.yale.its.tp.cas.client.filter.CASFilter</filter-class> <!-- URL of login page of CAS Server --> <init-param> <param-name>edu.yale.its.tp.cas.client.filter.loginUrl</param-name> <param-value>https://www.example.org/cas/login</param-value> </init-param> <!-- URL to validation URL of CAS Server --> <init-param> <param-name>edu.yale.its.tp.cas.client.filter.validateUrl</param-name> <param-value>https://www.example.org/cas/proxyValidate</param-value> </init-param> <!-- Full hostname with port number to be filtered. The port number is not required for standard ports (80,443) --> <init-param> <param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name> <param-value>www.example.org</param-value> </init-param> <!-- expose REMOTE_USER (from CAS Client version 2.1.0) --> <init-param> <param-name>edu.yale.its.tp.cas.client.filter.wrapRequest</param-name> <param-value>true</param-value> </init-param> </filter> <filter-mapping> <filter-name>CASFilter</filter-name> <url-pattern>/SSO/*</url-pattern> </filter-mapping>
    <servlet> <servlet-name>IdP</servlet-name> <display-name>Shibboleth Identity Provider</display-name> <servlet-class>edu.internet2.middleware.shibboleth.idp.IdPResponder</servlet-class> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>IdP</servlet-name> <url-pattern>/SSO</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>IdP</servlet-name> <url-pattern>/AA</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>IdP</servlet-name> <url-pattern>/Artifact</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>IdP</servlet-name> <url-pattern>/Status</url-pattern> </servlet-mapping> <mime-mapping> <extension>css</extension> <mime-type>text/css</mime-type> </mime-mapping> </web-app>
  4. Deploy Shibboleth IdP web application (proceed with the defaults, the settings have been stored from the first installation)
    $ cd /opt/shibboleth-1.3.3-install ./ant Do you want to install the Shibboleth Identity Provider? [Y,n] What name do you want to use for the Identity Provider web application? [default: shibboleth-idp] Deploying the java web application. Do you want to install it directly onto the filesystem or use the tomcat manager application? 1) filesystem (default) 2) manager Select a home directory for the Shibboleth Identity Provider [default: /opt/shibboleth-idp] Enter the tomcat home directory [default: /opt/tomcat] [further output omitted]

8. X.509 Server Certificates

This section briefly mentions the needed steps to get a server certificate. For a full documentation how to get SWITCHpki certificates, see http://www.switch.ch/pki/manage.html. SWITCHpki allows the use of "Subject Alternative Names" in certificates. The desired Subject AltNames can be submitted with the certificate request. In this guide, one certificate is used for two Tomcat connectors. The certificate has the common name (CN) "www.example.org" and the Subject AltNames "www.example.org, aai-aa.example.org".

8.1 Generate certificate

  1. Generate a 2048-bit RSA key in PEM format for Apache/Tomcat
    $ openssl genrsa -out www.example.org.key 2048
  2. Create a Certificate Signing Request (CSR)
    $ openssl req -new -key www.example.org.key > www.example.org.csr
  3. Using the .csr file created above, get your signed server certificate with the full chain up to the root CA certificate and save it as www.example.org.crt (in PEM format). You may also manually concatenate the files of the server certificate and the certificate chain (i.e. intermediate / root certificates).
  4. Check that your certificate file contains the certificate chain with the signing CA certificate. This means, the file must contain at least two -----BEGIN CERTIFICATE-----, -----END CERTIFICATE----- blocks. The host certificate has to be the first one, then follows the signing CA certificate (intermediate certificate).

8.2 Create Java Keystore with the key/certificate

  1. Create an empty Java keystore:
    $ keytool -genkey -alias a -keystore www.example.org.jks Enter keystore password: KEYSTOREPASS What is your first and last name? [Unknown]: What is the name of your organizational unit? [Unknown]: What is the name of your organization? [Unknown]: What is the name of your City or Locality? [Unknown]: What is the name of your State or Province? [Unknown]: What is the two-letter country code for this unit? [Unknown]: Is CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct? [no]: yes Enter key password for <a> (RETURN if same as keystore password): $ keytool -delete -alias a -keystore www.example.org.jks Enter keystore password: KEYSTOREPASS
  2. Convert PEM formatted key to PKCS8 format:
    $ openssl pkcs8 -in www.example.org.key -topk8 -nocrypt \ -outform DER -out www.example.org.key.pkcs8
  3. Import key/certificate into keystore using the extkeytool from the Shibboleth IdP installation:
    $ /opt/shibboleth-1.3.3-install/bin/extkeytool -importkey \ -alias www.example.org \ -keyfile www.example.org.key.pkcs8 -certfile www.example.org.crt \ -keystore www.example.org.jks -storepass KEYSTOREPASS \ -provider org.bouncycastle.jce.provider.BouncyCastleProvider

8.3 Java Keystore with Trusted CA Certificates

The Java keystore described in this section is only to be used for Shibboleth Identity Provider servers in the SWITCHaai federation.

Using the pre-built truststore.jks

  1. Download the Java keystore (truststore.jks) with the trusted CA certificates for SWITCHaai. The password for this truststore is "changeit".
    $ cd /etc/tomcat/ $ wget http://www.switch.ch/aai/downloads/truststore.jks

Manual creation of the truststore.jks file

This subsection shows how to create the truststore.jks file manually.

  1. Create an empty Java keystore with the name truststore.jks:
    $ keytool -genkey -alias a -keystore truststore.jks Enter keystore password: TRUSTSTOREPASS What is your first and last name? [Unknown]: What is the name of your organizational unit? [Unknown]: What is the name of your organization? [Unknown]: What is the name of your City or Locality? [Unknown]: What is the name of your State or Province? [Unknown]: What is the two-letter country code for this unit? [Unknown]: Is CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct? [no]: yes Enter key password for <a> (RETURN if same as keystore password): $ keytool -delete -alias a -keystore truststore.jks Enter keystore password: TRUSTSTOREPASS
  2. Get accepted root CA certificates for SWITCHaai. For further information about the accepted root CA certificates refer to http://www.switch.ch/aai/certificates/.
    $ wget http://www.switch.ch/aai/downloads/swisssignca.PEM.crt $ wget http://www.switch.ch/aai/downloads/tctrustcenterclass2ca.PEM.crt $ wget http://www.switch.ch/aai/downloads/tctrustcenterclass3ca.PEM.crt $ wget http://www.switch.ch/aai/downloads/thawteserverca.PEM.crt $ wget http://www.switch.ch/aai/downloads/thawtepremiumserverca.PEM.crt $ wget http://www.switch.ch/aai/downloads/verisignclass3ca.PEM.crt $ wget http://www.switch.ch/aai/downloads/epfl.PEM.crt $ wget http://www.switch.ch/aai/downloads/gtecybertrustglobalroot.PEM.crt $ wget http://www.switch.ch/aai/downloads/quovadisrootca.PEM.crt $ wget http://www.switch.ch/aai/downloads/quovadisrootca2.PEM.crt
  3. Import CA root certificates into keystore (truststore.jks):
    $ keytool -import -trustcacerts -alias swisssignca \ -file swisssignca.PEM.crt -keystore truststore.jks $ keytool -import -trustcacerts -alias tctrustcenterclass2ca \ -file tctrustcenterclass2ca.PEM.crt -keystore truststore.jks $ keytool -import -trustcacerts -alias tctrustcenterclass3ca \ -file tctrustcenterclass3ca.PEM.crt -keystore truststore.jks $ keytool -import -trustcacerts -alias thawteserverca \ -file thawteserverca.PEM.crt -keystore truststore.jks $ keytool -import -trustcacerts -alias thawtepremiumserverca \ -file thawtepremiumserverca.PEM.crt -keystore truststore.jks $ keytool -import -trustcacerts -alias verisignclass3ca \ -file verisignclass3ca.PEM.crt -keystore truststore.jks $ keytool -import -trustcacerts -alias epflca \ -file epfl.PEM.crt -keystore ./truststore.jks $ keytool -import -trustcacerts -alias gtecybertrustglobalca \ -file gtecybertrustglobalroot.PEM.crt -keystore ./truststore.jks $ keytool -import -trustcacerts -alias quovadisrootca \ -file quovadisrootca.PEM.crt -keystore ./truststore.jks $ keytool -import -trustcacerts -alias quovadisrootca2 \ -file quovadisrootca2.PEM.crt -keystore ./truststore.jks
    Omitting the -keystore option adds the CA certificates to Java's default certificate store (/opt/java/jre/lib/security/cacerts or /etc/java-1.5.0-sun/security/cacerts if the Debian java package is used).

9. Tomcat 5.5 Configuration

  1. Copy the keystore(s) to the /etc/tomcat/ directory:
    $ cp www.example.org.jks /etc/tomcat/
    Make sure the permissions are set correctly. Only the user running Tomcat must be able to read the keystore. Other users don't need to access the keystore file, so setting the correct ownership and access permissions is highly recommended.
  2. Copy the truststore to the /etc/tomcat/ directory:
    $ cp truststore.jks /etc/tomcat/
  3. The truststore containing the accepted CA certificates can be configured via CATALINA_OPTS in the /etc/init.d/tomcat startup script. This variable is passed to the JVM on startup of Tomcat which will the use the truststore specified instead of the default certificate store.

  4. Configure the Connectors for Shibboleth: one without client authentication (used for authentication by SSO servlet), one with SSL client authentication (used for attribute queries by AA servlet). The location of the configuration file is usually /etc/tomcat/.
    <!-- Tomcat configuration file /etc/tomcat/server.xml --!> <!-- Service name="Catalina"> <!-- ... --!> <!-- Define a SSL HTTP/1.1 Connector on port 443 without client auth for www.example.org --> <Connector address="IP_ADDRESS_1" port="443" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keystoreFile="/etc/tomcat/www.example.org.jks" keystorePass="KEYSTOREPASS" /> <!-- Define a SSL HTTP/1.1 Connector on port 443 with client authentication for aai-aa.example.org --> <Connector address="IP_ADDRESS_2" port="443" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true" clientAuth="true" sslProtocol="TLS" keystoreFile="/etc/tomcat/www.example.org.jks" keystorePass="KEYSTOREPASS" truststoreFile="/etc/tomcat/truststore.jks" truststorePass="KEYSTOREPASS" /> <!-- ... --!> <Engine name="Standalone" defaultHost="localhost" jvmRoute="jvm1"> <!-- ... --!>
    Other connectors (like the AJP13 connector on port 8009) are not needed for a Tomcat-only installation and can be commented out.

10. Shibboleth IdP 1.3 Configuration

10.1 Configure Shibboleth IdP

  1. Copy the key and certificate used for signing to the /etc/shibboleth directory.
    $ cp www.example.org.key /etc/shibboleth/ $ cp www.example.org.crt /etc/shibboleth/
    Remember to set appropriate ownership and access permissions, especially for the key-file.
    $ chown root:root www.example.org.key www.example.org.crt $ chmod 400 www.example.org.key
  2. Download the IdP template into /etc/shibboleth/idp.xml, and configure your Identity Provider for the SWITCHaai Federation as shown in the template file below.
    <?xml version="1.0" encoding="ISO-8859-1"?> <!-- Shibboleth Identity Provider configuration idp.xml TEMPLATE for the SWITCHaai federation see SWITCHaai installation guide --> <IdPConfig xmlns="urn:mace:shibboleth:idp:config:1.0" xmlns:cred="urn:mace:shibboleth:credentials:1.0" xmlns:name="urn:mace:shibboleth:namemapper:1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:mace:shibboleth:idp:config:1.0 ../schemas/shibboleth-idpconfig-1.0.xsd" blockStaleRequests="true" blameSP="true" AAUrl="https://aai-aa.example.org/shibboleth-idp/AA" resolverConfig="file:///etc/shibboleth/resolver.xml" defaultRelyingParty="urn:mace:switch.ch:SWITCHaai" providerId="urn:mace:switch.ch:SWITCHaai:example.org"> <!-- This section contains configuration options that apply only to a site or group of sites This would normally be adjusted when a new federation or bilateral trust relationship is established --> <RelyingParty name="urn:mace:switch.ch:SWITCHaai" signingCredential="switchaai_cred"> <!-- (signingCredential) must correspond to a <Credential/> element below --> <NameID nameMapping="shm"/> <!-- (nameMapping) must correspond to a <NameMapping/> element below --> </RelyingParty> <!-- Configuration for the attribute release policy engine For most configurations this won't need adjustment --> <ReleasePolicyEngine> <ArpRepository implementation="edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository"> <Path>file:///etc/shibboleth/arps</Path> </ArpRepository> </ReleasePolicyEngine> <!-- Logging Configuration The defaults work fine in this section, but it is sometimes helpful to use "DEBUG" as the level for the <ErrorLog/> when trying to diagnose problems --> <Logging> <ErrorLog level="WARN" location="file:///var/log/shibboleth/shib-error.log" /> <TransactionLog level="INFO" location="file:///var/log/shibboleth/shib-access.log" /> </Logging> <!-- Uncomment the configuration section below and comment out the one above if you would like to manually configure log4j --> <!-- <Logging> <Log4JConfig location="file:///tmp/log4j.properties" /> </Logging> --> <!-- This configuration section determines how Shibboleth maps between SAML Subjects and local principals. The default mapping uses shibboleth handles, but other formats can be added. The mappings listed here are only active when they are referenced within a <RelyingParty/> element above --> <NameMapping xmlns="urn:mace:shibboleth:namemapper:1.0" id="shm" format="urn:mace:shibboleth:1.0:nameIdentifier" type="SharedMemoryShibHandle" handleTTL="28800"/> <!-- Determines how SAML artifacts are stored and retrieved The (sourceLocation) attribute must be specified when using type 2 artifacts --> <ArtifactMapper implementation="edu.internet2.middleware.shibboleth.artifact.provider.MemoryArtifactMapper" /> <!-- This configuration section determines the keys/certs to be used when signing SAML assertions --> <!-- The credentials listed here are used when referenced within <RelyingParty/> elements above --> <Credentials xmlns="urn:mace:shibboleth:credentials:1.0"> <FileResolver Id="switchaai_cred"> <Key> <Path>file:///etc/shibboleth/www.example.org.key</Path> </Key> <Certificate> <Path>file:///etc/shibboleth/www.example.org.crt</Path> </Certificate> </FileResolver> </Credentials> <!-- Protocol handlers specify what type of requests the IdP can respond to. The default set listed here should work for most configurations. Modifications to this section may require modifications to the deployment descriptor --> <ProtocolHandler implementation="edu.internet2.middleware.shibboleth.idp.provider.ShibbolethV1SSOHandler"> <Location>.+/shibboleth-idp/SSO</Location> </ProtocolHandler> <ProtocolHandler implementation="edu.internet2.middleware.shibboleth.idp.provider.SAMLv1_AttributeQueryHandler"> <Location>.+/shibboleth-idp/AA</Location> </ProtocolHandler> <ProtocolHandler implementation="edu.internet2.middleware.shibboleth.idp.provider.SAMLv1_1ArtifactQueryHandler"> <Location>.+/shibboleth-idp/Artifact</Location> </ProtocolHandler> <ProtocolHandler implementation="edu.internet2.middleware.shibboleth.idp.provider.Shibboleth_StatusHandler"> <!-- regex works when using default protocol ports --> <Location>https://[^:/]+(:443)?/shibboleth-idp/Status</Location> </ProtocolHandler> <!-- This section configures the loading of SAML2 metadata, which contains information about system entities and how to authenticate them. The metadatatool utility can be used to keep federation metadata files in synch. Metadata can also be placed directly within this these elements. --> <MetadataProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata" uri="file:///etc/shibboleth/metadata.switchaai.xml"/> </IdPConfig>
  3. Configure your attribute source in the file /etc/shibboleth/resolver.xml. The example below shows a resolver configuration for an LDAP repository and the attributes defined according to the SWITCHaai Attribute Specification version 1.1.
    <AttributeResolver xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:mace:shibboleth:resolver:1.0" xsi:schemaLocation="urn:mace:shibboleth:resolver:1.0 shibboleth-resolver-1.0.xsd"> <SimpleAttributeDefinition id="urn:mace:switch.ch:attribute-def:swissEduPersonUniqueID"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:uid"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:sn"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:givenName"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:switch.ch:attribute-def:swissEduPersonMatriculationNumber"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:employeeNumber"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:switch.ch:attribute-def:swissEduPersonDateOfBirth"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:switch.ch:attribute-def:swissEduPersonGender"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:preferredLanguage"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:mail"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:homePostalAddress"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:postalAddress"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:homePhone"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:telephoneNumber"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:mobile"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:switch.ch:attribute-def:swissEduPersonHomeOrganization"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:switch.ch:attribute-def:swissEduPersonHomeOrganizationType"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonAffiliation"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:switch.ch:attribute-def:swissEduPersonStudyBranch1"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:switch.ch:attribute-def:swissEduPersonStudyBranch2"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:switch.ch:attribute-def:swissEduPersonStudyBranch3"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:switch.ch:attribute-def:swissEduPersonStudyLevel"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:switch.ch:attribute-def:swissEduPersonStaffCategory"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonOrgDN"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonOrgUnitDN"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonEntitlement"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <!-- Data connector --> <JNDIDirectoryDataConnector id="directory"> <Search filter="uid=%PRINCIPAL%"> <Controls searchScope="SUBTREE_SCOPE" returningObjects="false" /> </Search> <Property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory" /> <Property name="java.naming.provider.url" value="ldap://ldap.example.org:389/dc=example,dc=org" /> <!-- <Property name="java.naming.security.principal" value="cn=admin,dc=example,dc=org" /> <Property name="java.naming.security.credentials" value="examplepw" /> --> <!-- You may have to use this for Active Directory --> <!-- <Property name="java.naming.referral" value="follow" /> --> </JNDIDirectoryDataConnector> </AttributeResolver>
    See the Internet2 Wiki for further documentation concerning Attribute Definitions and JNDIDataConnector definitions.
  4. The SWITCHaai metadata file enables the Shibboleth IdP to do tests against some test Service Providers within the SWITCHaai Federation.
    $ cd /etc/shibboleth/ $ wget http://www.switch.ch/aai/federation/SWITCHaai/metadata.switchaai.xml
    For production, the metadata.switchaai.xml file has to be updated on a regular basis. Install the update scripts as described in the metadata refresh instructions.
  5. This sample Attribute Release Policy file arp.site.xml allows the release of attributes to some test Service Providers within the SWITCHaai Federation. It has to be updated in order to include new Service Providers. A version specific to each IdP can be retrieved from the SWITCHaai Resource Registry. Place the ARP file in directory /etc/shibboleth/arps:
    $ cd /etc/shibboleth/arps $ wget http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/idp/arp.site.xml

10.2 Test the installation

To verify the attribute resolver configuration and ARP processing, the resolvertest tool can be used. The following command shows attributes for the user "USERNAME" which would be sent to the SP with providerID https://aai-viewer.switch.ch/.

$ export IDP_HOME=/opt/shibboleth-idp $ cd /opt/shibboleth-idp $ ./bin/resolvertest -d --idpXml=file:///etc/shibboleth/idp.xml \ --requester=https://aai-viewer.switch.ch/shibboleth --user=USERNAME

If you are using SSL to secure the connection to the LDAP server, the resolvertest script has to be modified. The Java truststore containing your LDAP SSL certificate (or its CA root certificate respectively) has to be used. Therefore, the last line in the script has to be modified as follows:

$JAVACMD -Djavax.net.ssl.trustStore="/etc/tomcat/truststore.jks" \ -Djava.endorsed.dirs="$ENDORSED" -cp $SHIB_UTIL_CLASSPATH \ edu.internet2.middleware.shibboleth.utils.ResolverTest "$@"

10.3 Log Files

Error logs of the Shibboleth IdP are go to /var/log/shibboleth/shib-error.log. To set the log level for debugging, edit the /etc/shibboleth/idp.xml configuration file. In the <Logging> element the attribute level of <ErrorLog> can be set to DEBUG. For production use, set the LogLevel to WARN or INFO.

If the Shibboleth web application does not start up at all, there may be some piece of information in the Tomcat logs in /var/log/tomcat/catalina.out.

11. AAI Resource Registry

You are now ready to register your Home Organization (Identity Provider) in the AAI Resource Registry. Doing this will allow you to download customized ARP file for your IdP.

  1. Install the updateARP script on the IdP to keep the Attribute Release Policy up-to-date following the instructions on the update ARP installation guide.

The SWITCHaai Resource Registry collects configuration information about Resources (Service Providers) and Home Organizations (Identity Providers) which participate in the federations "SWITCHaai", and "AAI Test".

12. Links

SWITCH AAI project website
http://www.switch.ch/aai/
SWITCHaai Resource Registry: Register Identity Providers and Service Providers in the SWITCHaai Federation
https://aai-rr.switch.ch
Shibboleth at Internet2
http://shibboleth.internet2.edu
Shibboleth Wiki
https://spaces.internet2.edu/display/SHIB/WebHome/
Debian
http://www.debian.org
Sun Java
http://java.sun.com
Apache Tomcat
http://tomcat.apache.org
ESUP-CAS, Generic Auth Handler for CAS
http://esup-casgeneric.sourceforge.net
CAS SSO
http://www.ja-sig.org/products/cas/
Load balanced IdP
https://spaces.internet2.edu/display/SHIB/LoadBalancedIdP
--
$Id: install-idp-1.3-debian.html,v 1.60 2009/01/16 12:40:22 schnell Exp $