Shibboleth Service Provider (SP) 2.5 Installation Guide

Table of contents

  1. Introduction
  2. Prerequisites
  3. Shibboleth Repository
  4. Installation
  5. Quick Test
  6. Service Provider Configuration
  7. Additional Information

1. Introduction

This guide describes the installation of a Shibboleth Service Provider (SP) 2.5 on the supported operating systems below. We did not test the SP on all OS versions, so please report any issue you encounter.
Select first the operating system that is used on the host where the Shibboleth Service Provider is installed:

Debian 7.x (wheezy)/8.x (jessie) (using SWITCH Package Repository)

Ubuntu 12.04 LTS/14.04 LTS/16.04 LTS (using SWITCH Package Repository)

CentOS Linux 5.x/6.x

CentOS Linux 7.x

RedHat Enterprise Linux 5.x/6.x

RedHat Enterprise Linux 7.x

OpenSUSE 13.2.x

SUSE Linux Enterprise Server 10.x/11.x/12.x

Mac OS X 10.10.x or later

Windows Server 2008 R2 with IIS, Windows Server 2012 with IIS

This guide covers only installation but not configuration of the Service Provider. The installation instructions are generic and not federation specific.
If the Service Provider is already installed, please continue to the federation-specific Service Provider 2.5 Configuration Guide.

2. Prerequisites

For the following steps it is assumed that the reader is sufficiently experienced to use the command line environment on the operating system of choice.

Please examine the list below and ensure that the system where the Service Provider is going to be installed meets the given requirements.

2.1. Recommendations

The following software is optional but recommended to be installed for installation and operation for the Service Provider.

NTP
Servers running Shibboleth must have the system time synchronized in order to avoid clock-skew errors. It is therefore recommended to install ntp or use another time synchronisation mechanism.
Sudo
We recommend installing sudo for commands that require root privileges.
As root user sudo can be installed with:
apt-get install sudo
Curl
To download software and configuration files we recommend curl but of course you can also use wget or another tool. Just replace the curl commands in the following instructions with the tool you prefer using. Curl can be installed with:
sudo apt-get install curl
SSL enabled for Apache
It is strongly recommended to have the Apache SSL module enabled and configured to support HTTPS. By default the Shibboleth messages containing user attributes are encrypted. Therefore, they can also be sent via the insecure HTTP protocol. However, any session-based access to a web page via the insecure HTTP is prone to session hijacking attacks. This also includes the Shibboleth session. Relying on HTTPS mitigates this risk.

2.2. Requirements

The following software must be installed in order to operate the Shibboleth Service Provider.

Root access
For the following steps it must be possible to execute commands as user with root privileges, e.g. as root user or with the recommended sudo. Ensure that you have root privileges on the system.
Remove manually compiled/installed Service Provider
Before installing the Shibboleth Service Provider 2.5 on the system with the OS packet management system, ensure that there is no manually compiled and installed version of Shibboleth anymore. Manually compiled and installed version of the Shibboleth Service Provider can conflict with the new Service Provider versions that are installed via the package management system.
Follow the Service Provider Cleanup Instructions below in order to remove manually compiled Service Provider versions.

Before continuing to the next section, please ensure that the requirements above are met on the system where the Shibboleth Service Provider will be installed.

3. Shibboleth Repository

The Shibboleth project only provides official binary packages for RPM-based Linux distributions. As a service to its community members, SWITCH operates a repository with packages for the current Debian release. To configure this repository as an additional source for APT, follow these steps:

Download Repository Key
sudo curl -k -O http://pkg.switch.ch/switchaai/SWITCHaai-swdistrib.asc
Verify Repository Key
Run the command:
gpg --with-fingerprint  SWITCHaai-swdistrib.asc
Then verify that the fingerprint of the repository signing key is 294E 37D1 5415 6E00 FB96 D7AA 26C3 C469 15B7 6742
Add Repository Key
sudo apt-key add SWITCHaai-swdistrib.asc
Add Repository
Create a new source file /etc/apt/sources.list.d/SWITCHaai-swdistrib.list that contains the SWITCH repository for the Shibboleth package.
For Debian 6.x (squeeze) add:
echo 'deb http://pkg.switch.ch/switchaai/debian squeeze main' | sudo tee /etc/apt/sources.list.d/SWITCHaai-swdistrib.list > /dev/null
For Debian 7.x (wheezy) add:
echo 'deb http://pkg.switch.ch/switchaai/debian wheezy main' | sudo tee /etc/apt/sources.list.d/SWITCHaai-swdistrib.list > /dev/null
For Debian 8.x (jessie) add:
echo 'deb http://pkg.switch.ch/switchaai/debian jessie main' | sudo tee /etc/apt/sources.list.d/SWITCHaai-swdistrib.list > /dev/null
Refresh Repository
sudo apt-get update
Note The package repository on http://pkg.switch.ch/switchaai/ is operated for the SWITCH community and support is limited to its members. Use of the repository by other parties is permitted, but in this case it is provided AS IS and without any support.

4. Installation

Install the Service Provider by:

Shibboleth Service Provider Installation
sudo apt-get install shibboleth
If asked to confirm whether you really want to install Shibboleth and all dependencies, answer with 'Y' for yes.

If a previous version of the Service Provider from the official repository was installed on this system, this old version might be replaced by the newer version from the SWITCH repository. It is therefore ok to agree that old versions (like libapache2-mod-shib2 libshibsp4 opensaml2-schemas shibboleth-sp2-schemas) are removed.

If there was an older version of a Service Provider already installed on the system, you might be asked whether to keep the existing configuration files or overwrite them with the package default files. The old configuration files should be kept. You can continue to use the old files in most cases. Generally, it is however recommended to perform a clean configuration as is described in the configuration guide mentioned below.
Optional proxy settings
Shibboleth will automatically download metadata and CRL files. If your network policy does not allow outgoing connections on port 80 by default, then it is recommended to configure an HTTP proxy for outgoing connections.
Add the following line in /etc/default/shibd
export http_proxy=proxy.example.org:8080

4.1. Result

The Service Provider should now be installed on the system. Of particular interests are the directories:

/etc/shibboleth
Configuration directory of Shibboleth. The main configuration file is shibboleth2.xml.
/var/log/shibboleth
Log directory where logs are written to. The most important log file is the shibd.log file that should be consulted in case of problems.
/var/run/shibboleth
Runtime directory where process ID and socket files are stored.
/var/cache/shibboleth
Cache directory where metadata backup and CRL files are stored.
/etc/init.d
Init script directory where the startup script for the shibd daemon is stored.

5. Quick Test

After the installation a quick test shows whether the Service Provider was installed properly.

Shibboleth Configuration Check
In the command line, execute the following command to see whether the Shibboleth Service Provider can load the default configuration:
sudo shibd -t
Important is that the last line of the output is:
overall configuration is loadable, check console for non-fatal problems
Apache Configuration Check
Also test the Apache configuration with the command:
sudo apache2ctl configtest
or The output of this command should be:
Syntax OK
mod_shib Test
(Re-) Start the web server and then access the URL: https:///Shibboleth.sso/Session.

The web server (or Shibboleth module respectively) should return a page that says:
A valid session was not found.
This message shows that the Shibboleth module is loaded by the webserver and is communicating with the shibd process.

6. Service Provider Configuration

After the above tests were successful, continue to the Shibboleth configuration. Note that the configuration and migration guides are only for Service Providers that are configured for the SWITCHaai federation. In all other cases refer to the configuration guides of the Shibboleth Consortium.

Mistakes and Improvements? If you found an error or a typo or if you have suggestions for improvements, please . Your contributions are appreciated very much and they will help your colleagues.

7. Additional Information

7.1. References

7.2. Version Information

Copyright: SWITCH
Author: aai@switch.ch
URL: https://help.switch.ch/aai/guides/sp/installation-2.5/index.html