URL: http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/idp/install-idp-1.3-debian-apache.html
Author: Patrik Schnellmann - SWITCH
Author: Valery Tschopp - SWITCH
Author: Lukas Haemmerle - SWITCH
$Date: 2008/03/17 16:01:41 $
$Revision: 1.48 $

Install Shibboleth 1.3 Identity Provider on Debian 4.0 (etch), Tomcat and Apache

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

1. Introduction

This guide describes the installation of a Shibboleth Identity Provider 1.3 and its configuration for the SWITCHaai Federation. It covers installation with Tomcat 5.5 and Apache 1.3 or 2.2 on Debian etch. 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: 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 Deployment section 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). The AA servlet is accessed by the Shibboleth Service Provider (SP) and has to be protected with SSL client authentication.

This means that to enable client authentication for the AA servlet with Apache 2, two IP-addresses/DNS entries and corresponding server certificates are needed. If certificate Subject Alternative Names (Subject AltNames) are going to be used, the same server certificate can be used for both server names. Without certificate Subject Alternative Names, two server certificates will be needed.

With Apache 1.3 it is possible to run the server with one IP-Address and one server certificate, because client authentication can enabled per directory (and with mod_ssl, Renegotiation when POST requests are done).

The example values used in this guide are:

aai-logon.example.org: The DNS name of the Home Organization (Identity Provider) server. Names like "aai-logon", "aai-login", "aai" or something similar are used.
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 a different name and IP address (or a different port number) are needed when using Apache 2 as a frontend for Tomcat.
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.
Apache 1.3 with mod_ssl and mod_jk: Debian Packages: apache, libapache-mod-ssl, libapache-mod-jk
Apache 2.2 with mod_ssl and mod_proxy_ajp: Debian Packages: apache2, libapache-mod-ssl

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

Download J2SE Development Kit (JDK) 1.5 for Linux from http://java.sun.com

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

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.

Download Tomcat 5.5.x from http://tomcat.apache.org/.

Unpack apache-tomcat-5.5.26.tar.gz in /opt.

$ cd /opt
$ tar -xzf apache-tomcat-5.5.26.tar.gz

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

Remove unnecessary files from /opt/tomcat/bin:
```
$ cd /opt/tomcat/bin
$ rm *.exe *.bat
```

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

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

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

Update the different rc.d to start automatically Tomcat with the default runlevels:
```
$ update-rc.d tomcat defaults
```

6. Shibboleth IdP 1.3 Installation

Get Shibboleth IdP 1.3.3 from http://shibboleth.internet2.edu/downloads/
Extract the shibboleth-idp-1.3.3.tar.gz in directory /opt. The .tar.gz will be extracted into the directory shibboleth-1.3.3-install:
```
$ cd /opt
$ tar -xzf shibboleth-idp-1.3.3.tar.gz
```
Modify the support contact E-Mail address in /opt/shibboleth-1.3.3-install/webApplication/IdPError.jsp:
```
$ export JAVA_HOME=/opt/java
```

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]

The implementation of Sun's JAXP parser has been identified as containing a memory leak. Therefore, both JDK 1.4.x and 1.5.x should endorse the new XML libraries in tomcat. Copy the jar files /opt/shibboleth-idp/endorsed/*.jar which comes with the Shibboleth IdP 1.3 package:
```
$ cp -p /opt/shibboleth-idp/endorsed/*.jar /opt/tomcat/common/endorsed/
```
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
```
Set the IDP_HOME environment variable:
```
$ export IDP_HOME=/opt/shibboleth-idp
```
You may also include the following line into your /etc/profile file:
```
IDP_HOME=/opt/shibboleth-idp
export IDP_HOME
```

7. User Authentication / Single Sign On (SSO)

User authentication can be done on many ways if Apache and Tomcat are used. They offer their built-in user authentication and Single Sign On systems exist for both of these web servers. Even if Apache is put in front of Tomcat, user authentication can be handled by Tomcat i.e. by the CAS SSO. If authentication has to be done by Apache, there is the Pubcookie SSO and Apache modules (mod_ldap, mod_auth_pam) for various backends.

7.1 CAS

The installation of CAS server and CAS client is documented in the installation guide "How To Install a Shibboleth 1.3 Identity Provider on Debian GNU/Linux 3.1 (sarge), Tomcat only with CAS SSO" http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/idp/install-idp-1.3-debian.html.

7.2 Pubcookie

For the installation and configuration of Pubcookie, please refer to its website on http://www.pubcookie.org/. The location to be protected with Pubcookie is http://aai-logon.example.org/shibboleth-idp/SSO.

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) "aai-logon.example.org" and the Subject AltNames "aai-logon.example.org, aai-aa.example.org".

8.1 Generate certificate

Generate a 2048-bit RSA key in PEM format for Apache/Tomcat
```
$ openssl genrsa -out aai-logon.example.org.key 2048 
```

Create a Certificate Signing Request (CSR)

$ openssl req -new -key aai-logon.example.org.key > aai-logon.example.org.csr

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 aai-logon.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).
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).

9. Tomcat 5.5 Configuration

In /etc/tomcat/server.xml, configure the AJP 1.3 Connector on port 8009:

    <!-- Define an AJP 1.3 Connector on port 8009 -->
    <Connector port="8009" address="127.0.0.1"
               enableLookups="false" redirectPort="443" protocol="AJP/1.3"
               tomcatAuthentication="false" />

Other connectors are not needed when Apache is run in front of Tomcat, so they can be commented out.

10. Apache Configuration

10.1 Apache 1.3 Configuration

Apache will be configured with the modules mod_ssl for SSL support and mod_jk to redirect requests to Tomcat. The Apache configuration usually takes place in the file /etc/apache/httpd.conf.

mod_ssl

Copy the aai-logon.example.org.key to the directory /etc/apache/ssl.key/ and aai-logon.example.org.crt to the directory /etc/apache/ssl.crt/.
```
$ cp aai-logon.example.org.key /etc/apache/ssl.key/
$ cp aai-logon.example.org.crt /etc/apache/ssl.crt/
```
Get the bundle with the accepted CA root certificates within SWITCHaai and place it into the directory /etc/apache/ssl.crt/.
```
$ wget http://www.switch.ch/aai/downloads/ca-bundle.switchaai.crt
$ cp ca-bundle.switchaai.crt /etc/apache/ssl.crt/
```
Make sure the server listens on port 443 with the "Listen" directive.
```
Port 443
```

Define a virtual host for the SSL port:

<IfModule mod_ssl.c>
<VirtualHost _default_:443>
# SSL Engine Switch:
#   Enable/Disable SSL for this virtual host.
SSLEngine On

# SSL Cipher Suite:
#   List the ciphers that the client is permitted to negotiate.
#   See the mod_ssl documentation for a complete list.
SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL

# Server Certificate:
#   Point SSLCertificateFile at a PEM encoded certificate.  If
#   the certificate is encrypted, then you will be prompted for a
#   pass phrase.  Note that a kill -HUP will prompt again. A test
#   certificate can be generated with `make certificate' under
#   built time. Keep in mind that if you've both a RSA and a DSA
#   certificate you can configure both in parallel (to also allow
#   the use of DSA ciphers, etc.)
SSLCertificateFile /etc/apache/ssl.crt/aai-logon.example.org.crt

# Server Private Key:
#   If the key is not combined with the certificate, use this
#   directive to point at the key file.  Keep in mind that if
#   you've both a RSA and a DSA private key you can configure
#   both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /etc/apache/ssl.key/aai-logon.example.org.key

# Server Certificate Chain:
#   Point SSLCertificateChainFile at a file containing the
#   concatenation of PEM encoded CA certificates which form the
#   certificate chain for the server certificate. Alternatively
#   the referenced file can be the same as SSLCertificateFile
#   when the CA certificates are directly appended to the server
#   certificate for convenience.
SSLCertificateChainFile /etc/apache/ssl.crt/aai-logon.example.org.crt

#Sertificate Authority (CA):
#   Set the CA certificate verification path where to find CA
#   certificates for client authentication or alternatively one
#   huge file containing all of them (file must be PEM encoded)
#   Note: Inside SSLCACertificatePath you need hash symlinks
#         to point to the certificate files. Use the provided
#         Makefile to update the hash symlinks after changes.
#SSLCACertificatePath   /etc/apache/ssl.crt
SSLCACertificateFile /etc/apache/ssl.crt/ca-bundle.switchaai.crt

# Certificate Revocation Lists (CRL):
#   Set the CA revocation path where to find CA CRLs for client
#   authentication or alternatively one huge file containing all
#   of them (file must be PEM encoded)
#   Note: Inside SSLCARevocationPath you need hash symlinks
#         to point to the certificate files. Use the provided
#         Makefile to update the hash symlinks after changes.
#SSLCARevocationPath     /etc/apache/ssl.crl
#SSLCARevocationFile     /etc/apache/ssl.crl/ca-bundle.crl

# Client Authentication (Type):
#   Client certificate verification type and depth.  Types are
#   none, optional, require and optional_no_ca.  Depth is a
#   number which specifies how deeply to verify the certificate
#   issuer chain before deciding the certificate is not valid.
#SSLVerifyClient require
SSLVerifyDepth  10

# SSL Protocol Adjustments:
#   The safe and default but still SSL/TLS standard compliant shutdown
#   approach is that mod_ssl sends the close notify alert but doesn't
#   wait for the close notify alert from client. When you need a
#   different shutdown approach you can use one of the following
#   variables:
#   ssl-unclean-shutdown:
#     This forces an unclean shutdown when the connection is closed, 
#     i.e. no SSL close notify alert is send or allowed to received.
#     This violates the SSL/TLS standard but is needed for some
#     brain-dead browsers. Use this when you receive I/O errors
#     because of the standard approach where mod_ssl sends the close
#     notify alert.
#   ssl-accurate-shutdown:
#     This forces an accurate shutdown when the connection is closed,
#     i.e. a SSL close notify alert is send and mod_ssl waits for the
#     close notify alert of the client. This is 100% SSL/TLS standard
#     compliant, but in practice often causes hanging connections with
#     brain-dead browsers. Use this only for browsers where you know
#     that their SSL implementation works correctly.
#
#   NOTICE: Most problems of broken clients are also related to the
#   HTTP keep-alive facility, so you usually additionally want to
#   disable keep-alive for those clients, too. Use variable
#   "nokeepalive" for this.
SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown

</VirtualHost>
</IfModule>

Enable client authentication for the Shibboleth Attribute Authority endpoint:

<IfModule mod_ssl.c>
<Location /shibboleth-idp/AA>
    SSLVerifyClient optional_no_ca
    SSLOptions +ExportCertData -StdEnvVars
</Location>
</IfModule>

mod_jk

This is a sample workers.properties in case the tomcat package does not contain a sample configuration file. For detailed explanations, please refer to the Tomcat connectors documentation.

# /etc/tomcat/workers.properties
# define a worker using ajp13
worker.list=ajp13
worker.ajp13.type=ajp13
worker.ajp13.host=localhost
worker.ajp13.port=8009
worker.ajp13.lbfactor=50
worker.ajp13.cachesize=10
worker.ajp13.cache_timeout=600
worker.ajp13.socket_keepalive=1
worker.ajp13.recycle_timeout=300

Configure mod_jk with the mapping to the shibboleth-idp web app. Uncomment the last JkMount line if CAS is going to be used.

<IfModule mod_jk.c>
        JkWorkersFile   /etc/tomcat/workers.properties
        JkLogFile       /var/log/apache/mod_jk.log
        JkLogLevel      emerg
        JkMount         /shibboleth-idp/*       ajp13
#        JkMount         /cas/*                 ajp13
</IfModule>

10.2 Apache 2.2 Configuration

Apache will be configured with the modules mod_ssl for SSL support and mod_proxy_ajp to redirect requests to Tomcat. The Apache configuration usually takes place in files in the directory /etc/apache2/sites-available/.

mod_ssl

Copy the aai-logon.example.org.key to the directory /etc/ssl/private/ and aai-logon.example.org.crt to the directory /etc/ssl/certs/.
```
$ cp aai-logon.example.org.key /etc/ssl/private/
$ cp aai-logon.example.org.crt /etc/ssl/certs/
```
Get the bundle with the accepted CA root certificates within SWITCHaai and place it into the directory /etc/ssl/.
```
$ wget http://www.switch.ch/aai/downloads/ca-bundle.switchaai.crt
$ cp ca-bundle.switchaai.crt /etc/ssl/
```
Make sure the server listens on port 443 with the "Listen" directive in /etc/apache2/ports.conf.
```
Listen 443
```

Configure the virtual host on aai-logon.example.org. Make a new configuration file in /etc/apache2/sites-available or adapt an existing one. For example, use /etc/apache2/sites-availabe/aai-logon. Uncomment the last ProxyPass line if CAS is going to be used.

<IfModule mod_ssl.c>
<VirtualHost aai-logon.example.org:443>
ServerName aai-logon.example.org
SSLEngine On
SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
SSLCertificateFile       /etc/ssl/certs/aai-logon.example.org.crt
SSLCertificateKeyFile    /etc/ssl/private/aai-logon.example.org.key
SSLCertificateChainFile  /etc/ssl/certs/aai-logon.example.org.crt
#SSLCACertificatePath    /etc/ssl/certs
#SSLCACertificateFile    /etc/ssl/ca-bundle.crt
#SSLCARevocationPath     /etc/ssl/certs
#SSLCARevocationFile     /etc/ssl/ca-bundle.crl
#SSLVerifyDepth  10
SSLOptions +StdEnvVars
</VirtualHost>
</IfModule>

<IfModule mod_proxy_ajp.c>
    ProxyRequests Off
    
    <Proxy ajp://localhost:8009>
        Allow from all
    </Proxy>
    
    ProxyPass /shibboleth-idp ajp://localhost:8009/shibboleth-idp retry=5
#    ProxyPass /cas ajp://localhost:8009/cas retry=5
</IfModule>

Configure the virtual host on aai-aa.example.org. Make a new configuration file in /etc/apache2/sites-available or adapt an existing one. For example, use /etc/apache2/sites-availabe/aai-aa. Uncomment the last ProxyPass line if CAS is going to be used.

<IfModule mod_ssl.c>
<VirtualHost aai-aa.example.org:443>
ServerName aai-aa.example.org
SSLEngine On
SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
SSLCertificateFile       /etc/ssl/certs/aai-aa.example.org.crt
SSLCertificateKeyFile    /etc/ssl/private/aai-aa.example.org.key
SSLCertificateChainFile  /etc/ssl/certs/aai-aa.example.org.crt
#SSLCACertificatePath    /etc/ssl/certs
SSLCACertificateFile     /etc/ssl/ca-bundle.switchaai.crt
#SSLCARevocationPath     /etc/ssl/certs
#SSLCARevocationFile     /etc/ssl/ca-bundle.crl
SSLVerifyDepth  10
SSLVerifyClient          optional_no_ca
SSLOptions -StdEnvVars +ExportCertData
</VirtualHost>
</IfModule>

<IfModule mod_proxy_ajp.c>
    ProxyRequests Off
    
    <Proxy ajp://localhost:8009>
        Allow from all
    </Proxy>
    
    ProxyPass /shibboleth-idp ajp://localhost:8009/shibboleth-idp retry=5
</IfModule>

Enable both virtual hosts (aai-logon and aai-aa):


$ a2ensite aai-logon
$ a2ensite aai-aa
$ apache2ctl configtest
Syntax OK

Enable the ssl module.

$ a2enmod ssl
Module ssl installed; run /etc/init.d/apache2 force-reload to enable.

mod_proxy

$ a2enmod proxy_ajp
Enabling proxy as a dependency
Module proxy installed; run /etc/init.d/apache2 force-reload to enable.
Module proxy_ajp installed; run /etc/init.d/apache2 force-reload to enable.

Restart the apache httpd server:
```
$ /etc/init.d/apache2 restart
```

11. Shibboleth IdP 1.3 Configuration

11.1 Configure Shibboleth IdP

Copy the key and certificate used for signing to the /etc/shibboleth directory. Duplication is not necessary as the Shibboleth IdP 1.3 is able to use the same key and certificate files as Apache in the respective Apache configuration directory.
```
$ cp aai-logon.example.org.key /etc/shibboleth/
$ cp aai-logon.example.org.crt /etc/shibboleth/
```
Remember to set appropriate ownership and access permissions, especially for the file aai-logon.example.org.key.

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/aai-logon.example.org.key</Path>
      </Key>
      <Certificate>
        <Path>file:///etc/shibboleth/aai-logon.example.org.crt</Path>
      </Certificate>
    </FileResolver>

  <!-- this block may be used instead of the FileResolver - the IdP will then use the same keystore as Tomcat -->
  <!-- 
  <KeyStoreResolver Id="switchaai_cred" storeType="JKS">
      <Path>file:///etc/tomcat/aai-logon.example.org.jks</Path>
      <KeyAlias>aai-logon.example.org</KeyAlias>
      <CertAlias>aai-logon.example.org</CertAlias>
      <StorePassword>STOREPASS</StorePassword>
      <KeyPassword>STOREPASS</KeyPassword>
    </KeyStoreResolver>
  -->

  </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>
    <!-- regex works when using default protocol ports -->
  </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">
    <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>

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

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

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

11.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/shibboleth.

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

11.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 lower.

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.

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

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

13. 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
AAI-Test Reconfiguration Guide: http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/idp/reconfigure-idp.html
Metadata refresh instructions: http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/idp/refresh-metadata-idp.html
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
Apache Tomcat Connectors: http://tomcat.apache.org/connectors-doc/
mod_ssl for Apache: http://www.modssl.org
Pubcookie: http://www.pubcookie.org
CAS SSO: http://www.ja-sig.org/products/cas/
Esup-CAS, Generic Auth Handler for CAS: http://esup-casgeneric.sourceforge.net
Load balanced IdP: https://spaces.internet2.edu/display/SHIB/LoadBalancedIdP

--
$Id: install-idp-1.3-debian-apache.html,v 1.48 2008/03/17 16:01:41 schnell Exp $

Install Shibboleth 1.3 Identity Provider on Debian 4.0 (etch), Tomcat and Apache

Table of Contents

1. Introduction

2. Overview

3. Prerequisites

4. Java 1.5 Installation

4.1 Install the Debian etch Java 1.5 JDK package

4.2 Install Java 1.5 manually

5. Tomcat 5.5 Installation

6. Shibboleth IdP 1.3 Installation

7. User Authentication / Single Sign On (SSO)

7.1 CAS

7.2 Pubcookie

8. X.509 Server Certificates

8.1 Generate certificate

9. Tomcat 5.5 Configuration

10. Apache Configuration

10.1 Apache 1.3 Configuration

mod_ssl

mod_jk

10.2 Apache 2.2 Configuration

mod_ssl

11. Shibboleth IdP 1.3 Configuration

11.1 Configure Shibboleth IdP

11.2 Test the installation

11.3 Log Files

12. AAI Resource Registry

13. Links