1. Introduction
This guide describes the installation of a Shibboleth Identity Provider and its configuration for the SWITCHaai Federation. It covers installation with Tomcat 5.5 and Apache 2.2 on Debian etch using CAS Single Sign-On. The Shibboleth Wiki provides information about other deployments.
2. Overview
The Shibboleth Identity Provider (IdP) 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 6
- Apache 2 with Tomcat 5.5
- Shibboleth 2 and CAS (server and client)
- 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)
- Maven
- Maven will be used to build CAS server and client. Currently, there’s no Debian package for Maven 2 in the stable distribution. A manual installation will be needed on pure Debian/stable systems, which is shown below.
4. Java 6 Installation
As Java 1.5 is already being phased out by Sun, we strongly recommend to install the current version Sun Java 6. The official Java 6 from Sun is available as a package in Debian etch-backports. However, to have the latest version, some prefer to install Java manually. This section shows the installation of the Debian package and how to install Sun Java 6 without a packaging system.
4.1 Install the Debian etch (backports) Java 6 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 http://www.backports.org/debian etch-backports main contrib non-free
Install the Sun JDK package:
$ sudo apt-get install -t etch-backports sun-java6-jdk
If you install this package, the following dependent packages will also be installed (among others): sun-java6-bin, sun-java6-jre, sun-java6-demo. Java will be installed in /usr/lib/jvm/java-6-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-6-sun export JAVA_HOME
Check that the correct Java version is in the path:
$ java -version java version “1.6.0_17″ [...]
Once Java is installed, the rest of this section can be skipped. Continue with “5. Tomcat 5.5 Installation”.
4.2 Install Java 6 manually
This section shows the steps to manually install Sun Java JDK 6. Doing this implies a manual installation of Apache Tomcat 5.5 as the Tomcat5.5 Debian package depends on an installed JVM package.
- Download Java SE Development Kit (JDK) 6 for Linux from http://java.sun.com
- Install Java 6 in directory
/opt.
$ cd /opt $ chmod 750 jdk-6u10-linux-i586.bin $ ./jdk-6u10-linux-i586.bin $ ln -s /opt/jdk1.6.0_10 /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.1. 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 IdP Installation”.
5.2 Install Tomcat 5.5 manually
- Download Tomcat 5.5.x from http://tomcat.apache.org/.
- Unpack
apache-tomcat-5.5.27.tar.gz in /opt.
$ cd /opt $ tar -xzf apache-tomcat-5.5.27.tar.gz
- Create symlinks to facilitate access to configuration and log directories of Tomcat:
$ ln -s /opt/apache-tomcat-5.5.27 /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 Installation
This section describes the installation of the Shibboleth IdP together with a database for persistent identifiers.
6.1 Shibboleth IdP Installation
- Get Shibboleth IdP 2.1.0 from http://shibboleth.internet2.edu/downloads/
$ curl -O http://shibboleth.internet2.edu/downloads/shibboleth/idp/2.1.0/shibboleth-idp-2.1.0-bin.zip $ curl -O http://shibboleth.internet2.edu/downloads/shibboleth/idp/2.1.0/shibboleth-idp-2.1.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.1.0-bin.zip.asc gpgv: Signature made [...] using DSA key ID 47905D15 gpgv: Good signature from [...]
- Extract the
shibboleth-idp-2.1.0-bin.zip. The .zip will be extracted into the directory shibboleth-identityprovider-2.1.0:
$ cd /opt $ jar -xf shibboleth-idp-2.1.0-bin.zip
- 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):
$ cd /opt/shibboleth-idp $ 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] /opt/shibboleth-idp 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/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 IdP 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.
This section shows how CAS can be used with JAAS authenticating against an LDAP server.
8.1 Maven installation
To build CAS server 3, maven 2 is required. This sections shows how to install maven 2 manually.
- Get Maven 2:
$ curl -O http://www.apache.org/dyn/closer.cgi/maven/binaries/apache-maven-2.0.9-bin.zip
- Install
maven2 in /opt/
$ cd /opt $ jar -xf apache-maven-2.0.9-bin.zip ln -s /opt/apache-maven-2.0.9 /opt/apache-maven
- Add the following lines to
/etc/profile:
M2_HOME=/opt/apache-maven export M2_HOME M2=$M2_HOME/bin PATH=$M2:$PATH export PATH
The environment variables will become active in a new shell.
Note:
Users behind a firewall, forced to use an http proxy, see the proxy guide for maven.
8.2 CAS Server installation
8.2.1 CAS Server web application
- Get
CAS server 3.3 from http://www.ja-sig.org/products/cas/.
$ curl -O http://www.ja-sig.org/downloads/cas/cas-server-3.3-release.zip
- Uncompress CAS server in
/opt.
$ cd /opt $ jar -xf cas-server-3.3-release.zip
- Make the Virginia Tech LDAP Login Module classes available to CAS:
$ cd /opt/cas-server-3.3 $ mkdir -p cas-server-webapp/src/main/webapp/WEB-INF/lib $ cp /opt/shibboleth-idp/lib/vt-ldap-2.8.1.jar ./cas-server-webapp/src/main/webapp/WEB-INF/lib/
- Enable the JAAS authentication handler for the cas web application by editing
cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml. Within the AuthenticationManager’s “authenticationHandlers” property, place the following configuration (replace the SimpleTestUsernamePassword handler):
<bean class=”org.jasig.cas.authentication.handler.support.JaasAuthenticationHandler” />
- Adapt the server name in
src/main/webapp/WEB-INF/cas.properties
cas.securityContext.serviceProperties.service=https://idp.example.org:443/cas/services/j_acegi_cas_security_check
cas.securityContext.casProcessingFilterEntryPoint.loginUrl=https://idp.example.org:443/cas/login
cas.securityContext.ticketValidator.casServerUrlPrefix=https://idp.example.org:443/cas
cas.themeResolver.defaultThemeName=default
cas.viewResolver.basename=default_views
host.name=cas
#database.hibernate.dialect=org.hibernate.dialect.OracleDialect
#database.hibernate.dialect=org.hibernate.dialect.MySQLDialect
database.hibernate.dialect=org.hibernate.dialect.HSQLDialect
- Build the CAS server web application:
$ cd cas-server-webapp $ mvn package
- Create a context descriptor for the CAS server web application in
$CATALINA_HOME/conf/Catalina/localhost/:
$ cd /var/lib/tomcat5.5/
Create the context descriptor file conf/Catalina/localhost/cas.xml:
<Context docBase=”/opt/cas-server-3.3/cas-server-webapp/target/cas.war” privileged=”true” antiResourceLocking=”false” antiJARLocking=”false” unpackWAR=”false” />
8.2.2 JAAS configuration
- Configure JAAS in the file
jaas.conf (save it as /etc/shibboleth/jaas.conf):
/* This is the JAAS configuration file used by CAS. 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 CAS */ CAS { // 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”; */ };
- Have the JVM use the above JAAS configuration. Place the following line in
/etc/java-6-sun/security/java.security:
# # Default login configuration file # login.config.url.1=file:/opt/shibboleth-idp/conf/jaas.conf
8.3 CAS Client installation
- Get the JA-SIG CAS Java Client from http://www.ja-sig.org/products/cas/downloads/.
cd /opt http://www.ja-sig.org/downloads/cas-clients/cas-client-3.1.3-release.zip
- Uncompress
cas-client in /opt:
$ jar -xf cas-client-3.1.3.zip
- Build cas client:
$ cd cas-client-3.1.3/cas-client-core $ mvn package
- Make the cas client classes available to the Shibboleth IdP web application:
$ cp cas-client-core/target/cas-client-core-3.1.3.jar /opt/shibboleth-identityprovider-2.1.0/lib/
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
ProxyPass /cas ajp://localhost:8009/cas 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 Configuration
11.1 Configure Shibboleth IdP
11.1.1 IdP Credentials Configuration
The credentials which the Shibboleth IdP uses are in the /opt/shibboleth-idp/credentials/ directory. The installer generates a self-signed certificate which be used within the SWITCHaai federation.
- Make sure the tomcat user has read access for both the key and the certificate file. Remember to set appropriate ownership and permissions, notably for the file
idp.key.
$ cd /opt/shibboleth-idp/credentials $ chown tomcat55 idp.key $ chgrp root idp.{key,crt} $ chmod 440 idp.key $ chmod 644 idp.crt
11.1.2 Metadata Trust Configuration
- Download the SWITCHaai metadata trust anchor.
$ curl -O http://ca.aai.switch.ch/SWITCHaaiRootCA.crt.pem
- Compare the certificate fingerprint with the fingerprint of the SWITCHaai Root CA certificate shown on https://www.switch.ch/pki/aai/:
$ openssl x509 -in SWITCHaaiRootCA.crt.pem -fingerprint -sha1 -noout SHA1 Fingerprint=3C:E2:5A:E0:9D:B4:BB:2B:FD:33:3C:22:80:39:F7:FC:4A:F9:2C:E9
- If the fingerprint is correct, copy the certificate to IdP’s
credentials directory.
$ cp SWITCHaaiRootCA.crt.pem /opt/shibboleth-idp/credentials/ $ chmod 644 /opt/shibboleth-idp/credentials/SWITCHaaiRootCA.crt.pem
- Configure to use the SWITCHaai federation metadata and the trusted root certificate in
relying-party.xml as shown below. Please make sure the StaticPKIXSignature Metadata TrustEngine is used.
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://metadata.aai.switch.ch/metadata.aaitest.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://metadata.aai.switch.ch/metadata.switchaai.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:StaticPKIXSignature”> <security:ValidationInfo id=”SWITCHaaiFederationCredentials” xsi:type=”security:PKIXFilesystem”> <security:Certificate>/opt/shibboleth-idp/credentials/SWITCHaaiRootCA.crt.pem</security:Certificate> </security:ValidationInfo> </security:TrustEngine> <!– DO NOT EDIT BELOW THIS POINT –> <!– … –>
11.1.3 Attribute Resolution and Filtering Configuration
- 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.1/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” configurationResourcePollingFrequency=”3600000″> <ConfigurationResource xsi:type=”resource:FileBackedHttpResource” url=”https://rr.aai.switch.ch/switchaai/idp.example.org/attribute-filter.xml” file=”/opt/shibboleth-idp/conf/attribute-filter.xml”/> </Service>
This setting will change in the future due to improved mechanisms for retrieving the attribute-filter.xml from URLs.
11.1.4 Authentication Handler configuration
- Enable the
RemoteUser login handler of the Shibboleth IdP in handler.xml (remove the comments around the <LoginHandler> element):
<!– … –> <!– Login Handlers –>
<LoginHandler xsi:type=”RemoteUser”> <AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</AuthenticationMethod> </LoginHandler> <!– Username/password login handler –> <!– <LoginHandler xsi:type=”UsernamePassword” jaasConfigurationLocation=”file:///opt/shibboleth-idp/conf/login.config”> <AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</AuthenticationMethod> </LoginHandler> –> <!– … –>
- Configure the CAS client filter for the Shiboleth IdP web application in
/opt/shibboleth-identityprovider-2.1.0/build/WEB-INF/web.xml:
<!– … –> <!– Spring 2.0 listener used to load up the configuration –> <listener> <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class> </listener> <!– CAS Filter Configuration –> <context-param> <param-name>serverName</param-name> <param-value>
https://idp.example.org</param-value> </context-param> <!– CAS Authentication Filter –> <filter> <filter-name>CAS Authentication Filter</filter-name> <filter-class>org.jasig.cas.client.authentication.AuthenticationFilter</filter-class> <init-param> <param-name>casServerLoginUrl</param-name> <param-value>
https://idp.example.org/cas/login</param-value> </init-param> </filter> <!– CAS Validation Filter –> <filter> <filter-name>CAS Validation Filter</filter-name> <filter-class>org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter</filter-class> <init-param> <param-name>casServerUrlPrefix</param-name> <param-value>
https://idp.example.org/cas</param-value> </init-param> </filter> <!– CAS HttpServletRequest Wrapper Filter –> <filter> <filter-name>CAS HttpServletRequest Wrapper Filter</filter-name> <filter-class>org.jasig.cas.client.util.HttpServletRequestWrapperFilter</filter-class> </filter> <!– CAS Assertion Thread Local Filter –> <filter> <filter-name>CAS Assertion Thread Local Filter</filter-name> <filter-class>org.jasig.cas.client.util.AssertionThreadLocalFilter</filter-class> </filter> <!– CAS Filter for Shibb RemoteUser –> <filter-mapping> <filter-name>CAS Authentication Filter</filter-name> <url-pattern>/Authn/RemoteUser</url-pattern> </filter-mapping> <filter-mapping> <filter-name>CAS Validation Filter</filter-name> <url-pattern>/Authn/RemoteUser</url-pattern> </filter-mapping> <filter-mapping> <filter-name>CAS HttpServletRequest Wrapper Filter</filter-name> <url-pattern>/Authn/RemoteUser</url-pattern> </filter-mapping> <filter-mapping> <filter-name>CAS Assertion Thread Local Filter</filter-name> <url-pattern>/Authn/RemoteUser</url-pattern> </filter-mapping> <!– Add IdP Session object to incoming profile requests –> <!– … –>
- Redeploy the Shibboleth IdP web application, responding
no. Tomcat will reload the web application provided that the context descriptor points to the file /opt/shibboleth-idp/war/idp.war (see the IdP deployment section for that).
$ cd /opt/shibboleth-identityprovider-2.1.0/ $ ./ant.sh install Buildfile: build.xml install: Is this a new installation? Answering yes will overwrite your current configurat ion. [yes|no] no
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 <logger> element the attribute level of <ErrorLog> can be set to DEBUG. For production use, set the log level to WARN or lower.
To enable logging for the LDAP connection, insert the following lines in logging.xml:
<!-- Logs LDAP related messages -->
<logger name="edu.vt.middleware.ldap">
<level value="WARN"/>
</logger>
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/
- Maven
- http://maven.apache.org
- CAS server and client
- http://www.ja-sig.org/products/cas/
- CAS user manual
- http://www.ja-sig.org/wiki/display/CASUM/
- Virginia Tech LDAP module
- http://www.middleware.vt.edu/doku.php?id=middleware:opensource:ldap
--
$Id: install-idp-2.1-cas-debian.html,v 1.8 2008/11/17 15:14:43 schnell Exp $
) (vi /etc/squid/notsex)
) :