Shibboleth Service Provider (SP) v2.3.x Installation on Debian Lenny

This document provides detailed information on how to install a Shibboleth Service Provider (SP) on a Debian (Lenny) based system and configure it correctly to be integrated within the current EDIT CSSO platform.

Currently, there is no official Debian package supporting the latest version of the Shibboleth SP. So, you'll need to download and compile it from source. While SWITCHaai provides a detailed deployment guide, this guide summarises any required steps and adopts them to become an installation guide for a Service Provider integrated into the EDIT CSSO platform.

To shorten the complex installation procedure, there is also a simple setup script available setting up a default Shibboleth SP for the EDIT federation. Please refer to the setup script documentation at the end of this document.

Finally, there is a brief introduction into the installation and configuration of the Shibboleth Drupal module.

Prerequisites

SSL Web Server Certificate

Before starting the installation procedure, you will need an SSL Web Server Certificate. The certificate is mandatory in order to enable trustworthy and secure communication between all components of EDIT's CSSO infrastructure. Please refer to your institution's system administrator to provide you with such a certificate. You may also create a self-generated certificate or can get an (also self-generated) certificate from EDIT's WP 5.7 ServerCA. Please consider possible convenience restrictions due to the "Invalid Security Certificate Problem" !

Root access

In order to execute the following build and installation procedure, you need root access to your system!

Build the Shibboleth SP

Installing the build environment

If not already done, install the wget package to download the necessary source code archives. 

	apt-get install --yes wget

The following packages are required to compile the Shibboleth SP daemon and the Shibboleth Apache module. 

	apt-get install --yes gcc  
	apt-get install --yes g++
	apt-get install --yes make
	apt-get install --yes libssl0.9.8 
	apt-get install --yes libssl-dev
	apt-get install --yes libcurl3
	apt-get install --yes libcurl3-dev  
	apt-get install --yes libxerces-c28  
	apt-get install --yes libxerces-c2-dev
	apt-get install --yes libxml-security-c14
	apt-get install --yes libxml-security-c-dev
	apt-get install --yes apache2-threaded-dev

Finally, define, create and change into a build directory to execute the build process. 

export MYBUILD=~/shibsp2.3.1-build
mkdir -p $MYBUILD
cd $MYBUILD

Download and extract source code

To compile the current version 2.3.1 of the Shibboleth SP, please download the following source code archives 

wget http://shibboleth.internet2.edu/downloads/log4shib/1.0.4/log4shib-1.0.4.tar.gz
wget http://shibboleth.internet2.edu/downloads/opensaml/cpp/2.3/xmltooling-1.3.3.tar.gz
wget http://shibboleth.internet2.edu/downloads/opensaml/cpp/2.3/opensaml-2.3.tar.gz
wget http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/2.3.1/shibboleth-sp-2.3.1.tar.gz
tar xvfz log4shib-1.0.4.tar.gz
tar xvfz xmltooling-1.3.3.tar.gz
tar xvfz opensaml-2.3.tar.gz
tar xvfz shibboleth-sp-2.3.1.tar.gz

Build Shibboleth SP

Define and create a home directory for the current Shibboleth-SP version 

export SHIB_HOME=/opt/shibboleth-sp-2.3.1
mkdir $SHIB_HOME

Build Log4Shib

pushd $MYBUILD/log4shib-1.0.4/ && ./configure --disable-static --disable-doxygen --prefix=$SHIB_HOME && make && make install && popd

Build XML-Tooling

pushd $MYBUILD/xmltooling-1.3.3/ && ./configure --with-log4shib=$SHIB_HOME --prefix=$SHIB_HOME -C && make && make install && popd

Build OpenSAML

pushd $MYBUILD/opensaml-2.3}/ && ./configure --prefix=$SHIB_HOME --with-log4shib=$SHIB_HOME -C && make && make install && popd

Build Shibboleth Service Provider

pushd $MYBUILD/shibboleth-2.3.1/ && ./configure --with-saml=$SHIB_HOME --enable-apache-22 --with-log4shib=$SHIB_HOME --with-xmltooling=$SHIB_HOME --prefix=$SHIB_HOME -C && make && make install && popd

Install Shibboleth SP

After having successfully build the Shibboleth SP, proceed to install the Shibboleth Apache module and daemon into your system.

Install Apache2 web server

If you did not install the Apache2 web server before, make up for it now. 

apt-get install --yes apache2

Install time synchronisation

If your system clock is not synchronised yet, make up for installing the ntpdate client software. 

apt-get install --yes ntpdate

Update the file /etc/default/ntpdate as follows:

  • set NTPDATE_USE_NTP_CONF=no
  • optionally, update the NTPSERVERS list to your needs (e.g. country specific or firewall reasons)

Create symbolic link to current Shibboleth SP version

Create a stable reference to the current Shibboleth SP version. 

unlink /opt/shibboleth-sp2
ln -s $SHIB_HOME /opt/shibboleth-sp2

Define and create a configuration directory for Shibboleth SP

export SHIBSP_CONFIG=/etc/shibboleth
mkdir -p $SHIBSP_CONFIG

Install Shibboleth SP module for Apache2

Installing the Shibboleth SP module for Apache2 web server requires the creation of the following files.

Enable Apache's Shibboleth SP and SSL module. 

a2enmod shib
a2enmod ssl

Init script for the Shibboleth SP daemon

The Shibboleth SP daemon should be started on every system startup. So, an init script must be created and added to the system's init services.

Therefore, create the file /etc/init.d/shibd as follows. 

#! /bin/sh
### BEGIN INIT INFO
# Provides: shibd
# Required-Start: $local_fs $remote_fs $network
# Required-Stop: $local_fs $remote_fs $network
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Shibboleth 2 Service Provider Daemon
# Description: Starts the separate daemon used by the Shibboleth
# Apache module to manage sessions and to retrieve
# attributes from Shibboleth Identity Providers.
### END INIT INFO
#
# Written by Quanah Gibson-Mount <quanah@stanford.edu>
# Modified by Lukas Haemmerle <lukas.haemmerle@switch.ch> for Shibboleth 2
# Based on the dh-make template written by:
#
# Written by Miquel van Smoorenburg <miquels@cistron.nl>.
# Modified for Debian
# by Ian Murdock <imurdock@gnu.ai.mit.edu>.

PATH=/sbin:/bin:/usr/sbin:/usr/bin
DESC="Shibboleth 2 daemon"
NAME=shibd
SHIB_HOME=/opt/shibboleth-sp2
SHIBSP_CONFIG=/etc/shibboleth/shibboleth2.xml
LD_LIBRARY_PATH=$SHIB_HOME/lib
DAEMON=$SHIB_HOME/sbin/$NAME
SCRIPTNAME=/etc/init.d/$NAME
PIDFILE=/var/run/$NAME.pid
DAEMON_OPTS=""

# Force removal of socket
DAEMON_OPTS="$DAEMON_OPTS -f"

# Use defined configuration file
DAEMON_OPTS="$DAEMON_OPTS -c $SHIBSP_CONFIG"

# Specify pid file to use
DAEMON_OPTS="$DAEMON_OPTS -p $PIDFILE"

# Specify wait time to use
DAEMON_OPTS="$DAEMON_OPTS -w 30"

# Exit if the package is not installed.
[ -x "$DAEMON" ] || exit 0

# Read configuration if it is present.
[ -r /etc/default/$NAME ] && . /etc/default/$NAME

# Get the setting of VERBOSE and other rcS variables.
[ -f /etc/default/rcS ] && . /etc/default/rcS

case "$1" in
start)
    # Don't start shibd if NO_START is set.
    if [ "$NO_START" = 1 ] ; then
        echo "Not starting $DESC (see /etc/default/$NAME)"
        exit 0
    fi
    echo -n "Starting $DESC: "
    start-stop-daemon --start --quiet \
        --pidfile $PIDFILE --exec $DAEMON -- $DAEMON_OPTS
    echo "$NAME."
    ;;
stop)
    echo -n "Stopping $DESC: "
    start-stop-daemon --stop --quiet --pidfile $PIDFILE \
        --exec $DAEMON
    echo "$NAME."
    ;;
restart|force-reload)
    echo -n "Restarting $DESC: "
    start-stop-daemon --stop --quiet --pidfile $PIDFILE \
        --exec $DAEMON
    sleep 1
    start-stop-daemon --start --quiet \
        --pidfile $PIDFILE --exec $DAEMON -- $DAEMON_OPTS
    echo "$NAME."
    ;;
*)
    echo "Usage: $SCRIPTNAME {start|stop|restart|force-reload}" >&2
    exit 1
    ;;
esac

exit 0

At the beginning of the init-script, there are some options to adopt the script to your environment. But, there should be no reason to touch them, unless you are following this guide.

To enable the init script, make it executable and register it to the different run levels of your Debian system by calling update-rc.d. 

chmod +x /etc/init.d/shibd
update-rc.d shibd defaults

Install the Shibboleth Log system

The Shibboleth SP's log system should be adopted to the Debians system defaults. Therefore, create a directory /var/log/shibboleth for Shibboleth log files first. 

mkdir -p /var/log/shibboleth

Next, copy the original logger configuration template files from the Shibboleth distribution in $SHIB_HOME (/opt/shibboleth-sp2) to ${SHIBSP_CONFIG} (/etc/shibboleth). 

cp ${SHIB_HOME}/etc/shibboleth/native.logger ${SHIBSP_CONFIG}
cp ${SHIB_HOME}/etc/shibboleth/shibd.logger ${SHIBSP_CONFIG}
cp ${SHIB_HOME}/etc/shibboleth/syslog.logger ${SHIBSP_CONFIG}

Adopt the following logger files to the Debian system defaults.

Finally, create empty log files and set the log files access control lists accordingly. 

touch /var/log/shibboleth/shibd.log
touch /var/log/shibboleth/native.log
chown root:www-data /var/log/shibboleth/native.log
chmod g+w /var/log/shibboleth/native.log
chown root:www-data /var/log/shibboleth/shibd.log
chmod g+w /var/log/shibboleth/shibd.log

Configure Shibboleth SP for the EDIT federation

Certificate and key files

As stated at the beginning of the document, a SSL web server certificate is required to run the CSSO services. Usually, you should have two files in PEM format: a certificate file and a key file.

Note: The key file must not be encrypted, otherwise the SP may not run correctly.

Debian's default locations for certificates and key files are the directories /etc/ssl/certs or /etc/ssl/private respectively. So, let's copy both PEM-files to their default locations and set appropriate access control rights.

In order to get working the configuration correctly, you must follow the naming convention for certificate and key files I introduced for all my system setups. It's quite simple, use the DNS hostname of your SP and append -cert.pem or -key.pem respectively.

Example for the host idp.e-taxonomy.eu: 

Certificate file: idp.e-taxonomy.eu-cert.pem
Key file:idp.e-taxonomy.eu-key.pem

Next, copy the files to their respective locations and set access right appropriately. Replace ${shibSPHost} with the DNS host name of your SP ! 

cp ${pathToCertfile} /etc/ssl/certs/${shibSPHost}-cert.pem
cp ${pathToKeyfile} /etc/ssl/private/${shibSPHost}-key.pem
chown root:ssl-cert /etc/ssl/private/${shibSPHost}-key.pem
chmod 640 /etc/ssl/private/${shibSPHost}-key.pem

Also, currently you will also need to download and copy the actual RootCA certificates of the EDIT federation into your /etc/ssl/certs directory:

  • EDIT-WP5.7-cacert.pem
  • EDIT-WP5.7-ServerCA-cacert.pem 
    wget http://dev.e-taxonomy.eu/trac/attachment/wiki/WP57CertificationAuthority/EDIT-WP5.7-cacert.pem?format=raw
wget http://dev.e-taxonomy.eu/trac/attachment/wiki/WP57CertificationAuthority/EDIT-WP5.7-ServerCA-cacert.pem?format=raw
cp EDIT-WP5.7-cacert.pem?format=raw /etc/ssl/certs/EDIT-WP5.7-cacert.pem
cp EDIT-WP5.7-ServerCA-cacert.pem?format=raw /etc/ssl/certs/EDIT-WP5.7-ServerCA-cacert.pem

Note: If your certificate was issued by another RootCA, the RootCA's certificate must also be copied to /etc/ssl/certs!

Then, set the access right appropriately and create the required hash links to the certificate files with c_rehash: 

chown root:root /etc/ssl/certs/*
chmod 644 /etc/ssl/certs/*
c_rehash

Finally, you must add the user www-data to the group ssl-cert, so that the Apache web server can access the key file. 

adduser www-data ssl-cert

Shibboleth SP

Our EDIT specific configuration of the Shibboleth SP takes place in the following files:

shibboleth2.xml covers the main configuration of a Shibboleth SP. attribute-map.xml defines the mapping of attributes sent by EDIT's Identity provider to Apache2 web server's environment variables. attribute-policy.xml defines Shibboleth SP's access control policy rules. metadata-idp.xml contains EDIT's IdP metadata for backup reasons. EDIT-Logo.png and main.css set up logo and style of any kind of messages shown by the Shibboleth SP in the user's web browser. 

cp attribute-map.xml attribute-policy.xml metadata-idp.xml EDIT-Logo.png main.css ${SHIBSP_CONFIG}

Except from the shibboleth2.xml file, all files come already preconfigured fitting the EDIT federation's requirements. So, you can just download and copy them to the Shibboleth SP's configuration directory (${SHIBSP_CONFIG} (/etc/shibboleth)).

When downloading shibboleth2.xml, you receive a preconfigured template (shibboleth2.xml.tmpl), which requires some additional work to make it compatible. Therefore, the template file contains a placeholder (${shibSPHost}), which must be replaced by the full qualified hostname (including domain name) of your service provider(e.g. idp.e-taxonomy.eu). That can be done with your preferred text editor, or by executing the following command (e.g. for idp.e-taxonomy.eu). 

sed -i s\\'${shibSPHost}'\\idp.e-taxonomy.eu\\ shibboleth2.xml.tmpl

Finally, you can copy and rename the modified file to the Shibboleth SP's configuration directory (${SHIBSP_CONFIG} (/etc/shibboleth)). 

cp shibboleth2.xml.tmpl ${SHIBSP_CONFIG}/shibboleth2.xml

Apache2 site configuration

The site configuration for Apache2 web server requires the following files.

As for shibboleth2.xml, the Shibboleth SP site configuration file for the Apache2 web server also comes as a preconfigured template (/etc/apache2/sites-available/shibboleth-sp). It can be adopted to the SP's host name by executing the same command as above or by editing it with a text editor. 

sed -i s\\${shibSPHost}\\idp.e-taxonomy.eu\\ shibboleth-sp.tmpl

Activating the shibboleth-sp site within the Apache2 web server, puts the SSL part of your site ("https://your.site.org/") completely under the control of the Shibboleth SP's. That means, any login approach will be redirected to the EDIT Identity Provider (i.e. https://idp.e-taxonomy.eu/opensso/)!

To change this, the root path (/) within the Location statement must be adopted to meet the local requirements. Further Location statements may be added in order to protect several paths on the service provider. 

	<Location />
		AuthType Shibboleth
		ShibRequireSession On
  		ShibUseHeaders On
  		require shibboleth
	</Location>

For verifying the functionality of the CSSO access later on, the PHP script shibenv.php may be useful. While it just displays any Shibboleth and Apache environment variables, the correct functionality of the CSSO access can be monitored. For that, it should be simply copied to the document root of the Apache2 web server (usually /var/www).

Here are the remaining commands to protect the SSL part of your site by CSSO. 

cp shibboleth-sp.tmpl /etc/apache2/sites-available/shibboleth-sp
a2ensite shibboleth-sp
cp shibenv.php /var/www/
chown root:www-data /var/www/shibenv.php
chmod 750 /var/www/shibenv.php

Shibboleth SP notification mechanism

The configuration of the Shibboleth SP's notification mechanism needs following files.

The Shibboleth notification mechanism is used to implement the Single Logout (SLO) functionality on service providers. The Shibboleth SP's notification mechnism simply calls a defined script (/var/www/notify.php), which calls all logout URLs of applications running on the given site. That way, there should be no specific application authentication cookies left causing some applications to "think" that a user is always logged in. In particular, this scenario may occur, when Single Logout was initiated on another server.

To enable this, install the php5-curl library first. Then, download and copy notify.php to the document root of your Apache2 web server. Furthermore, set the access control rights appropriately 

apt-get install php5-curl
cp notify.php /var/www/
chown root:www-data /var/www/notify.php
chmod 750 /var/www/notify.php

Last but not least, the $logoutURL array at the beginning of the notify.php script must be adopted by entering the logout URLs of your applications.

Note: Do not change anything below the array definition, if you do not know what you are doing !

Note: Since, these URLs will be called by the users' browser, they must be listed with their external hostname. Defining URLs like http://localhost/app/logout will not work!

Here is an example defining a Drupal logout URLs 

$logoutURL = array(
  'http://your.host.org/drupal5/?q=logout',
  'http://your.host.org/drupal6/?q=logout'
);

Restarting Apache2 and the Shibboleth daemon

Finally, let's restart the Apache2 web server and shibd. 

/etc/init.d/apache2 restart && /etc/init.d/shibd restart && ps -efa | grep shibd

Please check, if the shibd process is really running. If not, repeat the last command. Sometimes, the shibd does not start!?

If there are any problems, please check the log files of Apache2 web server (/var/log/apache2) and Shibboleth SP daemon (/var/log/shibboleth) first!

Registering the new Shibboleth SP at the EDIT federation

If anything went fine, accessing your Shibboleth SP at the URLhttps://your.host.org/shibboleth should succesfully start a download of the SP's metadata. In that case, please notify the [suhrbier@… EDIT federation manager]. Then, the federation manager may register your service provider to the EDIT federation. Since that point in time, any registered EDIT user may login to the applications on your service provider!

Next, verify if users can login successfully, by accessing shibenv.php script stated above on your web server (e.g. https://your.host.org/shibenv.php). Presumed, you are already an registered user at the EDIT federation (otherwise, refer to the [suhrbier@… EDIT federation manager] as well), you should be redirected to EDIT's IdP (https://idp.e-taxonomy.eu/opensso/). After having successfully authenticated there, you should be redirected back to originally selected service provider and see an attribute list containing at least your name and email address on your browser!

Setup Script

The setup script is a compressed tar file containing a directory with the script, some configuration files and some template files as described above. So, if you want to use the setup script for installing and configuring your Shibboleth SP, download and extract the script first. Then, change to the setup directory just created.

Download and extract setup directory

wget -O shibSP-Setup.tgz http://dev.e-taxonomy.eu/trac/attachment/wiki/ShibbolethSP2InstallDebianLenny/shibSP-Setup.tgz?format=raw
tar xvfz shibSP-Setup.tgz
cd shibSP-Setup

Within the directory, there is a script called shibSPSetup. If you call it without parameters, the command help will be printed on the screen.

Copy certificate files

Before starting the installation, the certificate and key file for your web server must be copied into the shibSP-Setup directory. Also, both files should be renamed according the naming rules stated above. Here is an example for the host idp.e-taxonomy.eu. 

Certificate file: idp.e-taxonomy.eu-cert.pem
Key file:idp.e-taxonomy.eu-key.pem

Installation

The setup script offers the following commands. Letters in brackets[] show the options to be applied with that command.

  • all compile, install and configure SP"
  • compile compile SP [-btv]"
  • configure configure SP [-cdeihkrsv]"
  • install install SP [-tv]"
  • setacl set ACLfor SP installation [-v]"
  • uninstall removes build, install and configuration files"

The following options are available:

  • -b build target (default: ./)"
  • -c Local SSL certificate file (default: ./$hostname-cert.pem)"
  • -d DS Url (default: https://idp.e-taxonomy.eu/DS) not implemented yet"
  • -e Support Contact (default: editsupport@…"
  • -i IdP entity id (default: https://idp.e-taxonomy.eu:443/opensso)"
  • -h hostname (default: 'eval hostname')"
  • -k Local SSL private key file (default: ./$hostname-key.pem)"
  • -a IdP hostname (default: idp.e-taxonomy.eu)"
  • -r SSL RootCA certificate path (default: /etc/ssl/certs)"
  • -s SP entity id (default: https://$hostname/shibboleth"
  • -t installation target (default: /opt)"
  • -v SP version to install (default: 2.3.1)"

Besides the certificate files, the only information the script needs for a default installation is the hostname of your server. Therefore, the script uses the hostname command to get the hostname automatically. Please check, if that command prints the correct, full qualified hostname of your server (e.g. idp.e-taxonomy.eu) 

root@idp:~# hostname
idp.e-taxonomy.eu

Next, the setup procedure may start. Use the all command to setup your basic Shibboleth SP in one go. Alternatively, use the compile, install and configure in that order. You can also use these command steps to repeat any of these steps on error. If you need to change some of the configuration parameters, please check which command options may apply.

The complete setup will take approximately 20-30 minutes. Most of time will be consumed by the compile command. Here, take care on potential error messages. In that case, you should verify your setup and repeat the compile step.

If all went well, you should have reached the state Registering the new Shibboleth SP at the EDIT federation. So, contact the [suhrbier@… EDIT federation manager] to register your service provider with the EDIT federation.

Installing and Configuring Drupal modules

The setup directory supports the installation of Drupal 5(6) modules adopted to the EDIT CSSO setup. Currently, There are two quit simple scripts (shibDrupal5(6)Setup) which are copying the modules to their usual location. These locations may easily be changed by adapting the paths to /var/www/drupal5(6) to another directory.

Next, the Drupal modules must be installed configured appropriately. Therefore, you must login with Drupal administration rights, and install the modules userprotect and shib_auth by selecting the respective modules in Drupal's module administration section. After that, configure the Shibboleth module within the Shibboleth settings->General settings menu within of the User management administration section.

Configure the General Shibboleth settings as follows:

Shibboleth handler settings
Shibboleth handler URL: /Shibboleth.sso
Shibboleth handler protocol: HTTPS
WAYF location: /Login
Shibboleth login target protocol: HTTPS
Shibboleth logout return URL: e.g. http://your.host.org/drupal6/?q=logout
Attribute settings
Server variable for username: Shib_eduPersonPrincipalName
Server variable for e-mail address: Shib-mail

You can also define specific access rules, which will map Shibboleth attribute values to defined Drupal user roles. The mapping will be defined by matching regular expressions. Access rules may be configures within the Shibboleth settings->Shibboleth group rules menu. When adding a new rule, the Shibboleth attribute name and a regular expression must be entered. Then, the user roles assigned to users matching the regular expression must be selected.

The currently defined attributes are listed within the Current Set of EDIT Attributes document. Using e.g. the eduPersonAffiliation attribute (Shib_eduPersonAffiliation variable), the EDIT Federation manager group will be matched by defining the following regular expression: 

^cn=FederationManager.*

When assigned to the Drupal admin rule, EDIT Federation manager can manage e.g. the Shibboleth configuration on your Drupal instance.

Attachments