URL: http://www.switch.ch/aai/docs/shibboleth/SWITCH/2.0/idp/install-idp-2.0-debian.html
Author: Patrik Schnellmann - SWITCH
$Date: 2008/10/29 13:27:41 $
$Revision: 1.21 $
Install Shibboleth 2.0 Identity Provider on Debian 4.0 (etch), Tomcat and Apache
Table of Contents
1. Introduction
2. Overview
3. Prerequisites
4. Java 1.5 Installation
5. Tomcat 5.5 Installation
6. Shibboleth IdP 2.0 Installation
7. X.509 Server Certificates
8. User Authentication / Single Sign On (SSO)
9. Tomcat 5.5 Configuration
10. Apache Configuration
11. Shibboleth IdP 2.0 Configuration
12. AAI Resource Registry
13. Links
1. Introduction
This guide describes the installation of a Shibboleth Identity Provider 2.0
and its configuration for the SWITCHaai Federation. It covers installation with
Tomcat 5.5 and Apache 2.2 on Debian etch using authentication handlers provided
by the Shibboleth IdP. The
Shibboleth Wiki
provides information about other deployments.
2. Overview
The Shibboleth Identity Provider (IdP) 2.0 is a Java web application using SAML2.
The IdP has endpoints for user authentication (SSO) and for back-channel
attribute requests (Attribute Authority, AA). Communication with these endpoints
is usually secured with TLS/SSL, for which X.509 server certificates are
used.
The setup in this guide is as follows:
- Sun Java 1.5
- Apache 2 with Tomcat 5.5
- Shibboleth 2 using its own Authentication Handler
- SSO endpoint on port 443
- Attribute Authority endpoint on port 8443
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.
- ldap.example.org
- The name of the LDAP server where the user attributes are stored.
- https://aai-logon.example.org/idp/shibboleth
- entityID of the IdP in the federation metadata
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
to run the Sun Java virtual machine and a web application server
like Tomcat or JBoss. The following packages should be installed
on the 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 2.2 with mod_ssl and mod_proxy_ajp
- Debian packages:
apache2
The modules mod_ssl
and
mod_proxy_ajp
are part of the package.
- cURL
- Debian package:
curl
(optional, as an alternative to wget)
- gnupg (GNU Privacy Guard) and gpgv
- Debian packages:
gnupg
and gpgv
(recommended,
to verify the signature on the installed software)
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
Make sure the non-free repository is included in the apt sources
(sources.list
file or a file in directory
/etc/apt/sources.list.d/
).
# /etc/apt/sources.list
deb ftp://mirror.switch.ch/mirror/debian etch main contrib non-free
Install the Sun 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
Check that the correct Java version is in the path:
$ java -version
java version "1.5.0_14"
[...]
Once Java is installed, the rest of this section can be skipped.
Continue with "5. Tomcat 5.5 Installation".
4.2 Install Java 1.5 manually
This section shows the steps to manually install Sun Java JDK 1.5.
Doing this implies a manual installation of Apache Tomcat 5.5 as
the Tomcat5.5 Debian package depends on an installed JVM package.
- 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_15-linux-i586.bin
$ ./jdk-1_5_0_15-linux-i586.bin
$ ln -s /opt/jdk1.5.0_15 /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 at the end of
/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 2.0. Debian etch includes a Tomcat 5.5 package (version 5.5.20).
To get a later version, Tomcat still has to be installed manually.
The first subsection shows the installation of the package, the second
subsection shows the manual installation of Tomcat 5.5.
5.1 Install Tomcat 5.5 Debian package
Install the tomcat5.5
package. This will also install a lot
of dependent packages.
$ apt-get install tomcat5.5
Configure JVM memory options and not to use the security manager. In
/etc/default/tomcat5.5
set the following variables:
CATALINA_OPTS="-Xms256M -Xmx512M -XX:MaxPermSize=512M -XX:-DisableExplicitGC -server"
TOMCAT5_SECURITY=no
The values for memory usage depend on the physical memory of the
server. Set Xmx
to 512MBytes
minimum and
XX:MaxPermSize
to half of the available memory or
512MBytes
minimal.
Once Tomcat 5.5 is installed, the rest of this section can be skipped.
Continue with "6. Shibboleth 2.0 IdP Installation".
5.2 Install Tomcat 5.5 manually
- 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
- Add user
tomcat55
to run tomcat:
$ if ! id tomcat55 > /dev/null 2>&1 ; then
adduser --system --home /opt/tomcat --no-create-home \
--ingroup nogroup --disabled-password --shell /bin/false \
tomcat55
fi
- Install an
init.d
startup script as /etc/init.d/tomcat5.5
(this is a slightly modified Tomcat startup script from the Debian distribution):
#! /bin/sh -e
#
# /etc/init.d/tomcat5.5 -- startup script for the Tomcat 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>.
### BEGIN INIT INFO
# Provides: tomcat
# Required-Start: $local_fs $remote_fs $network
# Required-Stop: $local_fs $remote_fs $network
# Should-Start: $named
# Should-Stop: $named
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Start Tomcat.
# Description: Start the Tomcat servlet engine.
### END INIT INFO
set -e
PATH=/bin:/usr/bin:/sbin:/usr/sbin
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.5
# Run Tomcat 5.5 as this user ID (default: tomcat55)
# Set this to an empty string to prevent Tomcat from starting automatically
TOMCAT5_USER=tomcat55
# 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="-Xms256M -Xmx512M -XX:MaxPermSize=192M -XX:-DisableExplicitGC -server"
# 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.5 ]; then
. /etc/default/tomcat5.5
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 2.0 Installation
This section describes the installation of the Shibboleth IdP 2.0 together
with a database for persistent identifiers.
6.1 Shibboleth IdP 2.0 Installation
- Get Shibboleth IdP 2.0.0 from http://shibboleth.internet2.edu/downloads/
$ curl -O http://shibboleth.internet2.edu/downloads/shibboleth/idp/2.0/shibboleth-idp-2.0.0-bin.zip
$ curl -O http://shibboleth.internet2.edu/downloads/shibboleth/idp/2.0/shibboleth-idp-2.0.0-bin.zip.asc
- Verify signature on the downloaded file:
$ gpg --keyserver hktp://subkeys.pgp.net --recv-keys 47905D15 146B2514
$ gpgv --keyring .gnupg/pubring.gpg shibboleth-idp-2.0.0-bin.zip.asc
gpgv: Signature made [...] using DSA key ID 47905D15
gpgv: Good signature from [...]
- Extract the
shibboleth-idp-2.0.0-bin.zip
. The .zip will be extracted into the directory identityprovider
:
$ cd /opt
$ jar -xf shibboleth-idp-2.0.0-bin.zip
- Install the Shibboleth IdP package in
/opt/shibboleth-idp-2.0.0
and the webapplication in $CATALINA_HOME/webapps/
.
$ cd /opt/identityprovider
- Remove XML/Xerces libraries that came with the Tomcat distribution
from
$CATALINA_HOME/common/endorsed
(with
$CATALINA_HOME=/opt/tomcat
in case of a manually installed
Tomcat.
$ rm /usr/share/tomcat5.5/common/endorsed/xercesImpl.jar
$ rm /usr/share/tomcat5.5/common/endorsed/xml-apis
- Endorse libraries from the Shibboleth IdP tar ball in directory
$CATALINA_HOME/common/endorsed
(with
$CATALINA_HOME=/opt/tomcat
in case of a manually installed
Tomcat):
$ cp endorsed/*.jar /usr/share/tomcat5.5/common/endorsed/
- Run the ant tasks to install the Shibboleth IdP software:
$ chmod 755 ant.sh
$ ./ant.sh
-
Is this a new installation? Answering yes will overwrite your current configurat
ion. [yes|no]
yes
Where should the Shibboleth Identity Provider software be installed? [default: /
opt/shibboleth-idp-2.0.0]
/opt/shibboleth-idp-2.0.0
What is the hostname of the Shibboleth Identity Provider server? [default: idp.e
xample.org]
idp.example.org
A keystore is about to be generated for you. Please enter a password that will b
e used to protect it.
secret
(further output omitted)
- Set symbolic links for your convenience. Link
/etc/shibboleth
to the shibboleth-idp
configuration directory and /var/log/shibboleth
to the shibboleth-idp log directory:
$ ln -s /opt/shibboleth-idp-2.0.0 /opt/shibboleth-idp
$ ln -s /opt/shibboleth-idp/conf /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
- Set permissions and ownership in order to allow the
tomcat55
user to access directories in $IDP_HOME
:
$ cd /opt/shibboleth-idp
$ chown -R tomcat55 logs metadata credentials
$ chmod 755 logs metadata
- Create a context descriptor for the IdP web application in
$CATALINA_HOME/conf/Catalina/localhost/
:
$ cd /var/lib/tomcat5.5/
$ mkdir -p conf/Catalina/localhost
Create the context descriptor file conf/Catalina/localhost/idp.xml
:
<Context
docBase="/opt/shibboleth-idp/war/idp.war"
privileged="true"
antiResourceLocking="false"
antiJARLocking="false"
unpackWAR="false" />
6.2 MySQL Server Installation / Configuration
This section shows how to install and configure a MySQL database
for persistent identifiers locally on the IdP server. A remote
MySQL server may also be used, as long as it meets the availability
requirements of the IdP server.
Install MySQL server
-
Install the Debian etch package for MySQL server version 5.0:
$ apt-get install mysql-server-5.0
With the defaults, the mysql daemon only listens to localhost on IPv4.
- Set password for the root user in MySQL:
$ /usr/bin/mysqladmin -u root password 'secret-password'
Create users and databases
- Create database:
$ mysql -u root -p
SET NAMES 'utf8';
SET CHARACTER SET utf8;
CHARSET utf8;
CREATE DATABASE IF NOT EXISTS shibboleth CHARACTER SET = utf8;
USE shibboleth;
- Create table
shibpid
for the persistent id:
CREATE TABLE IF NOT EXISTS shibpid (
localEntity TEXT NOT NULL,
peerEntity TEXT NOT NULL,
principalName VARCHAR(255) NOT NULL default '',
localId VARCHAR(255) NOT NULL,
persistentId VARCHAR(36) NOT NULL,
peerProvidedId VARCHAR(255) default NULL,
creationDate timestamp NOT NULL default CURRENT_TIMESTAMP on update CURRENT_TIMESTAMP,
deactivationDate timestamp NULL default NULL,
KEY persistentId (persistentId),
KEY persistentId_2 (persistentId, deactivationDate),
KEY localEntity (localEntity(16), peerEntity(16),localId),
KEY localEntity_2 (localEntity(16), peerEntity(16), localId, deactivationDate)
) ENGINE=MyISAM DEFAULT CHARSET=utf8;
- Show information about the table that has been created in the step before.
DESCRIBE shibpid;
+------------------+--------------+------+-----+-------------------+-------+
| Field | Type | Null | Key | Default | Extra |
+------------------+--------------+------+-----+-------------------+-------+
| localEntity | text | NO | MUL | | |
| peerEntity | text | NO | | | |
| principalName | varchar(255) | NO | | | |
| localId | varchar(255) | NO | | | |
| persistentId | varchar(36) | NO | MUL | | |
| peerProvidedId | varchar(255) | YES | | NULL | |
| creationDate | timestamp | NO | | CURRENT_TIMESTAMP | |
| deactivationDate | timestamp | YES | | NULL | |
+------------------+--------------+------+-----+-------------------+-------+
8 rows in set (0.00 sec)
- Create a user
shibboleth
with password demo
:
USE mysql;
INSERT INTO user
(Host,User,Password,Select_priv,Insert_priv,Update_priv,Delete_priv,
Create_tmp_table_priv,Lock_tables_priv,Execute_priv) VALUES
('localhost','shibboleth',PASSWORD('demo'),
'Y','Y','Y','Y','Y','Y','Y');
FLUSH PRIVILEGES;
QUIT
- Check if the user
shibboleth
has been created
with password demo
:
$ mysql -u shibboleth -p
Enter password:demo
Welcome to the MySQL monitor. Commands end with ; or \g.
[...]
Install the java mysql connector
- Install debian package
apt-get install libmysql-java
.
mysql-connector-java.jar
will be installed in /user/share/java/
:
$ apt-get install libmysql-java
- Create a symbolic link to provide tomcat with the java mysql connector classes:
$ ln -s /usr/share/java/mysql-connector-java.jar \
/usr/share/tomcat5.5/common/lib/
7. 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".
7.1 Generate certificate
- Generate a 2048-bit RSA key in PEM format for Apache/Tomcat
$ openssl genrsa -out aai-logon.example.org.key 2048
$ chmod 400 aai-logon.example.org.key
- 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 have 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).
8. User Authentication / Single Sign On (SSO)
User authentication can be done on many ways if Apache and Tomcat are used.
Firstly, the Shibboleth 2.0 has built-in authentication handlers.
Then, Apache and Tomcat offer 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.
8.1 Shibboleth IdP 2.0 authentication handler
Configure JAAS in login.config
:
/*
This is the JAAS configuration file used by the Shibboleth IdP.
A JAAS configuration file is a grouping of LoginModules defined in the
following manner:
<LoginModuleClass> <Flag> <ModuleOptions>;
LoginModuleClass - fully qualified class name of the LoginModule class
Flag - indicates whether the requirement level for the modules;
allowed values: required, requisite, sufficient, optional
ModuleOptions - a space delimited list of name="value" options
For complete documentation on the format of this file see:
http://java.sun.com/j2se/1.5.0/docs/api/javax/security/auth/login/Configuration.html
For LoginModules available within the Sun JVM see:
http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/tutorials/LoginConfigFile.html
Warning: Do NOT use Sun's JNDI LoginModule to authentication against an LDAP
directory, use the LdapLoginModule that ships with Shibboleth and is
demonstrated below.
Note, the application identifier MUST be ShibUserPassAuth
*/
ShibUserPassAuth {
// Example LDAP authentication
// See: https://spaces.internet2.edu/display/SHIB2/IdPAuthUserPass
edu.vt.middleware.ldap.jaas.LdapLoginModule required
host="ldap.example.org"
port="389"
ssl="false"
tls="false"
base="ou=people,dc=example,dc=org"
subtreeSearch="true"
userField="uid"
serviceUser="cn=administrator,dc=example,dc=org"
serviceCredential="password";
// Example Kerberos authentication, requires Sun's JVM
// See: https://spaces.internet2.edu/display/SHIB2/IdPAuthUserPass
/*
com.sun.security.auth.module.Krb5LoginModule required
keyTab="/path/to/idp/keytab/file";
*/
};
9. Tomcat 5.5 Configuration
In /etc/tomcat5.5/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
should be commented out (i.e. the Connector for port 8180).
10. Apache 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/
.
$ curl 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 (and 8443 for AA connections)
with the "Listen" directive in
/etc/apache2/ports.conf
.
Listen 443
Listen 8443
- Configure the virtual host on aai-logon.example.org. Create a new
configuration file in
/etc/apache2/sites-available
or adapt an
existing one.
For example, use /etc/apache2/sites-availabe/aai-logon
.
<IfModule mod_ssl.c>
<VirtualHost _default_:443>
ServerName aai-logon.example.org
SSLEngine On
SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:!SSLv2:+EXP
SSLProtocol all -SSLv2
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 /idp ajp://localhost:8009/idp retry=5
</IfModule>
- Configure the virtual host for port 8443. Make a new configuration
file in
/etc/apache2/sites-available
or adapt an existing one.
For example, use /etc/apache2/sites-availabe/aai-aa
.
<IfModule mod_ssl.c>
<VirtualHost _default_:8443>
ServerName aai-logon.example.org
SSLEngine On
SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:!SSLv2:+EXP
SSLProtocol all -SSLv2
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 /idp ajp://localhost:8009/idp retry=5
</IfModule>
- Enable both virtual hosts (aai-logon and aai-aa):
$ a2ensite aai-logon
$ a2ensite aai-aa
$ apache2ctl -t
Syntax OK
-
Enable the ssl module.
$ a2enmod ssl
-
Enable the ajp proxy module, the module
mod_proxy
will also be
enabled.
$ 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:
$ apache2ctl -k restart
11. Shibboleth IdP 2.0 Configuration
11.1 Configure Shibboleth IdP
- Copy the key and certificate used for signing to the
/opt/shibboleth-idp/credentials/
directory.
Make sure the tomcat user has read access for both the key
and the certificate file.
$ cp aai-logon.example.org.{key,crt} /opt/shibboleth-idp/credentials/
Remember to set appropriate ownership and permissions, notably
for the file aai-logon.example.org.key
.
$ cd /opt/shibboleth-idp/credentials
$ chown tomcat55 aai-logon.example.org.key
$ chgrp root aai-logon.example.org.{key,crt}
$ chmod 440 aai-logon.example.org.key
$ chmod 644 aai-logon.example.org.crt
-
Move away the self-signed certificate generated from the installation
procedure.
$ mv idp.crt idp-self-signed.crt
$ mv idp.key idp-self-signed.key
- Use the certificate
aai-logon.example.crt
for the IdP-to-SP
communcation together with aai-logon.example.key
.
$ cd /opt/shibboleth-idp/credentials
$ ln -sf aai-logon.example.crt idp.crt
$ ln -sf aai-logon.example.key idp.key
- Install the SWITCHaai metadata trust anchor.
$ curl -O http://www.switch.ch/aai/downloads/metadata.crt
$ cp metadata.crt /opt/shibboleth-idp/credentials
$ chmod 644 /opt/shibboleth-idp/credentials/metadata.crt
- Configure to use the SWITCHaai federation metadata and the trusted root certificate
in
relying-party.xml
.
The entityID (https://idp.example.org/idp/shibboleth
)
of the IdP may be adapted also, if a different value than the default should
be used.
For the AAI test federation, configure http://www.switch.ch/aai/federation/aaitest/metadata.aaitest_signed.xml
as metadataURL
and /opt/shibboleth-idp/metadata/metadata.aaitest.xml
as backingFile
.
<!-- ========================================== -->
<!-- Relying Party Configurations -->
<!-- ========================================== -->
<AnonymousRelyingParty provider="https://idp.example.org/idp/shibboleth" />
<DefaultRelyingParty provider="https://idp.example.org/idp/shibboleth"
defaultSigningCredentialRef="IdPCredential"
defaultAuthenticationMethod="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport">
<!--
...
-->
<!-- ========================================== -->
<!-- Metadata Configuration -->
<!-- ========================================== -->
<!-- MetadataProvider the combining other MetadataProviders -->
<MetadataProvider id="ShibbolethMetadata" xsi:type="ChainingMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata">
<!-- MetadataProvider reading metadata from a URL. -->
<!-- Fill in metadataURL and backingFile attributes with deployment specific information -->
<!-- SWITCHaai production federation metadata
These attributes are set specifically for SWITCHaai
maintainExpiredMetadata: use expired metadata (boolean)
cacheDuration: max time until next metadata refresh (seconds)
-->
<MetadataProvider id="URLMD" xsi:type="FileBackedHTTPMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata"
metadataURL="http://www.switch.ch/aai/federation/SWITCHaai/metadata.switchaai_signed.xml"
backingFile="/opt/shibboleth-idp/metadata/metadata.switchaai.xml"
maintainExpiredMetadata="false"
cacheDuration="3600">
<MetadataFilter xsi:type="SignatureValidation"
xmlns="urn:mace:shibboleth:2.0:metadata"
trustEngineRef="shibboleth.MetadataTrustEngine"
requireSignedMetadata="true" />
</MetadataProvider>
<!--
...
-->
<!-- ========================================== -->
<!-- Security Configurations -->
<!-- ========================================== -->
<security:Credential id="IdPCredential" xsi:type="security:X509Filesystem">
<security:PrivateKey>/opt/shibboleth-idp/credentials/idp.key</security:PrivateKey>
<security:Certificate>/opt/shibboleth-idp/credentials/idp.crt</security:Certificate>
</security:Credential>
<!-- Trust engine used to evaluate the signature on loaded metadata. -->
<security:TrustEngine id="shibboleth.MetadataTrustEngine" xsi:type="security:StaticExplicitKeySignature">
<security:Credential id="SWITCHaaiFederationCredentials" xsi:type="security:X509Filesystem">
<security:Certificate>/opt/shibboleth-idp/credentials/metadata.crt</security:Certificate>
</security:Credential>
</security:TrustEngine>
<!-- DO NOT EDIT BELOW THIS POINT -->
<!--
...
-->
-
Adapt the attribute resolver to use your attribute source. The example shows
a configuration with an LDAP server to resolve the attributes from. Download
the SWITCHaai specific
attribute-resolver.xml
file
and adapt it.
$ cd /opt/shibboleth-idp/conf/
$ curl -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.0/idp/attribute-resolver.xml
Make sure to have replaced the salt
of the storedID Connector
with a random string. The random string may be generated with the following command:
$ openssl rand -base64 36 2>/dev/null
The salt is a string of random data; must be at least 16 characters,
48 characters is recommended. Be sure to write down this salt value somewhere
safe so that the persistentIDs are not lost if you delete your configuration
file!
<!--
...
-->
<!-- ========================================== -->
<!-- Attribute Definitions -->
<!-- ========================================== -->
<!--
...
-->
<!-- ========================================== -->
<!-- Data Connectors -->
<!-- ========================================== -->
<!-- Example Static Connector -->
<!--
<resolver:DataConnector id="staticAttributes" xsi:type="Static" xmlns="urn:mace:shibboleth:2.0:resolver:dc">
<Attribute id="eduPersonAffiliation">
<Value>member</Value>
</Attribute>
<Attribute id="eduPersonEntitlement">
<Value>urn:mace:dir:entitlement:common-lib-terms</Value>
</Attribute>
<Attribute id="swissEduPersonHomeOrganization">
<Value>idp.example.org</Value>
</Attribute>
<Attribute id="swissEduPersonHomeOrganizationType">
<Value>others</Value>
</Attribute>
</resolver:DataConnector>
-->
<!-- Example Relational Database Connector -->
<!--
<resolver:DataConnector id="mySIS" xsi:type="RelationalDatabase" xmlns="urn:mace:shibboleth:2.0:resolver:dc">
<ApplicationManagedConnection jdbcDriver="oracle.jdbc.driver.OracleDriver"
jdbcURL="jdbc:oracle:thin:@db.example.org:1521:SomeDB" jdbcUserName="myid" jdbcPassword="mypassword" />
<QueryTemplate>
<![CDATA[
SELECT * FROM student WHERE gzbtpid = $requestContext.principalName
]]>
</QueryTemplate>
<Column columnName="gzbtpid" attributeID="uid" />
<Column columnName="fqlft" attributeID="gpa" type="Float" />
</resolver:DataConnector>
-->
<!-- Example LDAP Connector -->
<resolver:DataConnector id="myLDAP"
xsi:type="LDAPDirectory"
xmlns="urn:mace:shibboleth:2.0:resolver:dc"
ldapURL="ldap://ldap.example.org"
baseDN="ou=people,dc=example,dc=org"
principal="cn=admin,dc=example,dc=org"
principalCredential="secret-password">
<FilterTemplate>
<![CDATA[
(uid=$requestContext.principalName)
]]>
</FilterTemplate>
</resolver:DataConnector>
<!-- StoredID (persistentID) Connector -->
<resolver:DataConnector id="myStoredId"
xsi:type="StoredId"
xmlns="urn:mace:shibboleth:2.0:resolver:dc"
generatedAttributeID="persistentID"
sourceAttributeID="swissEduPersonUniqueID"
salt="put-in-random-string-here">
<resolver:Dependency ref="swissEduPersonUniqueID" />
<ApplicationManagedConnection
jdbcDriver="com.mysql.jdbc.Driver"
jdbcURL="jdbc:mysql://localhost:3306/shibboleth?autoReconnect=true"
jdbcUserName="shibboleth"
jdbcPassword="demo" />
</resolver:DataConnector>
<!-- Computed targeted ID connector -->
<!--
<resolver:DataConnector xsi:type="ComputedId" xmlns="urn:mace:shibboleth:2.0:resolver:dc"
id="computedID"
generatedAttributeID="computedID"
sourceAttributeID="uid"
salt="your random string here">
<resolver:Dependency ref="myLDAP" />
</resolver:DataConnector>
-->
<!-- ========================================== -->
<!-- Principal Connectors -->
<!-- ========================================== -->
<resolver:PrincipalConnector xsi:type="Transient" xmlns="urn:mace:shibboleth:2.0:resolver:pc" id="shibTransient"
nameIDFormat="urn:mace:shibboleth:1.0:nameIdentifier" />
<resolver:PrincipalConnector xsi:type="Transient" xmlns="urn:mace:shibboleth:2.0:resolver:pc" id="saml1Unspec"
nameIDFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" />
<resolver:PrincipalConnector xsi:type="Transient" xmlns="urn:mace:shibboleth:2.0:resolver:pc" id="saml2Transient"
nameIDFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:transient" />
</AttributeResolver>
- This sample Attribute Filter Policy file
attribute-filter.xml
allows the release of attributes to some test Service Providers within the SWITCHaai Federation.
It has to be kept up to date in order to allow the release of attributes for
e.g. new Service Providers or new attributes to be released to Service Providers.
A version specific to each IdP can be retrieved from the
SWITCHaai Resource Registry.
The attribute-filter.xml
file can be configured to be downloaded
from a URL. The configuration in service.xml
is shown below.
For the AAI test federation, configure https://rr.aai.switch.ch/aaitest/idp.example.org/attribute-filter.xml
as url
.
<Service id="shibboleth.AttributeFilterEngine"
xsi:type="attribute-afp:ShibbolethAttributeFilteringEngine">
<ConfigurationResource xsi:type="resource:HttpResource"
url="https://rr.aai.switch.ch/switchaai/idp.example.org/attribute-filter.xml"
/>
</Service>
This setting will change in the future due to improved mechanisms for retrieving
the attribute-filter.xml
from URLs.
- Enable the login handler of the Shibboleth IdP in
handler.xml
(remove the comments around the <LoginHandler> element):
<!--
...
-->
<!-- Username/password login handler -->
<LoginHandler xsi:type="UsernamePassword"
jaasConfigurationLocation="file:///opt/shibboleth-idp-2.0.0/conf/login.config">
<AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</AuthenticationMethod>
</LoginHandler>
<!--
...
-->
11.2 Test the installation
11.2.1 IdP Status URL
To test if the IdP web application is up, check the Status URL of the IdP with the
web browser:
https://idp.example.org/idp/profile/Status
.
The page should show the string ok
. If not, check the log files for
errors (see next section).
11.2.2 Attribute Viewer Service Provider
SWITCH runs Service Providers as test counterparts for Identity Providers.
On https://aai-viewer.switch.ch/aai/
(SWITCHaai federation),
the attributes sent to that resource are shown on a web page. Before testing,
make sure the attribute resolver (attribute-resolver.xml
is
configured properly and the attribute filter (attribute-filter.xml
)
allows attributes to be released to the respective resource. If no
attributes are shown on the Service Provider, check your log files for errors
(see the "Log Files" section).
11.3 Log Files
Error logs of the Shibboleth IdP are go to /var/log/shibboleth/idp-error.log
.
The process log shows the interactions on the IdP: /var/log/shibboleth/idp-process.log
.
To set the log level for debugging, edit the /etc/shibboleth/logging.xml
configuration file. In the <loggerg>
element the attribute
level
of <ErrorLog>
can be set to DEBUG
.
For production use, set the log level 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 allows to download a customized attribute-filter.xml
file for the IdP.
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
- Shibboleth2 at Internet2
- http://shibboleth.internet2.edu
- Shibboleth Wiki
- https://spaces.internet2.edu/display/SHIB2/
- 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
- MySQL
-
http://dev.mysql.com/doc/refman/5.0/en/
--
$Id: install-idp-2.0-debian.html,v 1.21 2008/10/29 13:27:41 schnell Exp $