Shibboleth Service Provider (SP) 3.4 Installation Guide

Table of contents

  1. No entry yet.
Note regarding Upgrades to Shibboleth SP 3
Shibboleth SP v3 supports the SP v2 configuration format, so the SP v2 configuration files are forward-compatible with SP v3.
Check the shibd.log for deprecation warnings for legacy configuration elements.
The Migration guide documents how to update your configuration to get rid of the deprecation warnings for legacy configuration elements.

Introduction

This guide describes the installation of a Shibboleth Service Provider (SP) 3.4 on the operating systems Windows and Linux/Unix as supported by the Shibboleth Consortium. The instructions are generic, not federation specific.
We did not test the SP on all OS versions, so any issue you encounter.

Check and confirm the Shibboleth SP 3 System Requirements before proceeding.

Select the type of operating system on the host where the Shibboleth Service Provider gets installed:


If you use a Linux distribution not listed above that includes an up-to-date Shibboleth SP package, you can try to install that one.

If the Service Provider is already installed, please continue to our federation-specific Switch Shibboleth Service Provider Configuration Guide.

Note regarding CentOS 8
Since September 2023, the Shibboleth Consortium no longer supports CentOS 8 as officially supported platform.

Note for Debian and Ubuntu installations that used the former pkg.switch.ch repository:

As previously announced, the https://pkg.switch.ch/switchaai/ repository is no longer available. Use the packages from the official Debian and Ubuntu distribution channels.

To remove the SWITCHaai package repository from your system, uninstall packages shibboleth and switchaai-apt-source, then remove any remaining APT configuration for this repository (if any). This won't uninstall the Shibboleth SP and the currently-installed SWITCHaai SP packages will remain until a newer version is available from the distribution's official repository.

apt remove shibboleth
apt-mark manual libapache2-mod-shib
apt purge switchaai-apt-source
rm /etc/apt/trusted.gpg.d/SWITCHaai-swdistrib.gpg /etc/apt/sources.list.d/SWITCHaai-swdistrib.list
apt update

Recommendations

The Shibboleth project maintains its own shibboleth repository that provides the official Shibboleth Service Provider binaries and its dependencies for RPM-based Linux distributions. This repository contains always up-to-date version of the Shibboleth Service Provider. Therefore, prefer this repository and its packages over packages that may be provided by the OS distribution.

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

NTP
Servers running Shibboleth must have the system time synchronized in order to avoid clock-skew errors. Therefore, it is recommended to activate ntp, chrony or some other time synchronisation mechanism.
sudo
We recommend installing sudo for commands that require root privileges.
As root user sudo can be installed with:
Debian, Ubuntu
apt install sudo
Red Hat Enterprise Linux, CentOS
yum install sudo
Red Hat Enterprise Linux, Rocky Linux
dnf 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:
Debian, Ubuntu
apt install curl
Red Hat Enterprise Linux, CentOS 7
sudo yum install curl
Red Hat Enterprise Linux, Rocky Linux 8/9
sudo dnf install curl
SSL enabled for Apache
It is strongly recommended to enable and configure the Apache SSL module mod_ssl to support HTTPS (e.g. with sudo a2enmod ssl; sudo a2ensite default-ssl on Debian/Ubuntu). 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.
SSL enabled for Microsoft IIS
The IIS website should have an appropriate x509 certificate installed and SSL enabled.

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.

Installation

Install the Shibboleth Service Provider.

Shibboleth Service Provider Installation
  1. 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. However, you should update them to get rid of deprecation warnings for legacy configuration elements. Generally, it is recommended to perform a clean configuration as is described in the configuration guide mentioned below.
    1. For Debian and Ubuntu install the shibboleth package with:
      sudo apt install libapache2-mod-shib
    2. For Redhat, Centos, Rocky Linux, Amazon Linux fetch the appropriate RPM repository file and then install the shibboleth package with:
      sudo yum install shibboleth
    3. If none of the above apply, follow the instructions on the Shibboleth Wiki Page Linux Installation to configure the shibboleth repository or install from source, then come back here to proceed,
  2. After having installed the package, you need to start and enable the shibd daemon:
    sudo systemctl start shibd.service
    sudo systemctl enable shibd.service
  3. The Shibboleth Consortium does not support the SP in conjunction with SELinux. Check out the Common Errors topic on SELinux.
Download Windows Installer file
Download the Shibboleth Service Provider .msi file from the Shibboleth software repository. Either the 64 bit version or 32 bit version. Please check also the Installation Guide of the Shibboleth Wiki.
Run the installer
Execute the installer package. We recommend to perform the following actions during installation:
  1. Confirm the dialog to run the software
  2. Click "Next"
  3. Accept the license agreement
  4. The setup should look like on the screenshot below.
    Windows Installer screenshot
    Install the Service Provider into the default location to C:\opt\shibboleth-sp
    "Install ISAPI modules into IIS" should be checked
    IIS Script Extension should be the default ".sso"
    Compatibility with IIS 7 or older is not required if you run IIS 8 or newer
  5. Click "Next", then "Install", then "Finish"
  6. Click "Yes" to restart the system
Verify Shibboleth Service settings
In order to check whether the installation was successful, open Administrative Tools > Services. The Shibboleth service (Shibboleth 3 Daemon) should have Status = Running, Startup Type = Automatic, Logon As = Local System.
Verify IIS settings
Open Internet Information Server (IIS) Manager and verify the Shibboleth ISAPI filter is installed
Note
As of V3, a new IIS plugin is available which provides a richer and more secure integration with IIS version 7 and later. Please read about changes and advantages on Wiki page on Microsoft IIS.
  • If you are using IIS 6: Right-click on Web Sites, open Properties, select the ISAPI Filters tab. You should see a green arrow in the Status column for Shibboleth.
    Double-click on the Shibboleth filter entry and you should see Executable = C:\opt\shibboleth-sp\lib\shibboleth\isapi-shib.dll for a 32-bit install. If the status is unknown, use a web browser to open the URL of your web site. Often this will force the Shibboleth ISAPI filter to be activated.
  • For IIS 7 and later no specific checks are needed.
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/sysconfig/shibd
export http_proxy=proxy.example.org:8080
Open Control Panel > System > Advanced System Settings > Advanced > Environment Variables > System variables > New... and add the environment variable:

Result

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

/etc/shibbolethC:\opt\shibboleth-sp\etc\shibboleth
Configuration directory of Shibboleth. The main configuration file is shibboleth2.xml.
/var/log/shibbolethC:\opt\shibboleth-sp\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.
/run/shibboleth C:\opt\shibboleth-sp\var\run\shibboleth
Runtime directory where process ID and socket files are stored.
/var/cache/shibboleth C:\opt\shibboleth-sp\var\cache\shibboleth
Cache directory where metadata backup and CRL files are stored.
Note
Find below a list of useful Windows management console commands, which can be opened by 'Start -> Run':
IIS Management Console
%SYSTEMROOT%\System32\inetsrv\iis.msc
Event viewer
%SYSTEMROOT%\System32\eventvwr.msc
Local User & Group Management
%SYSTEMROOT%\System32\lusrmgr.msc
Services
%SYSTEMROOT%\System32\services.msc

Quick Test

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

Shibboleth SP Configuration Check
In the command line, execute the following command to see whether the Shibboleth Service Provider can load the default configuration:
For Debian, Ubuntu, Rocky Linux, CentOS:
sudo shibd -t
For Red Hat Enterprise Linux:
sudo LD_LIBRARY_PATH=/opt/shibboleth/lib64 shibd -t
C:\opt\shibboleth-sp\sbin\shibd.exe -check
Important is that the last line of the output is:
overall configuration is loadable, check console for non-fatal problems
If there are any ERROR log entries, it is strongly recommended to have a look at the problem.
Messages with log level WARN are generally not problematic but it is recommended to examine the causes of these warning messages.
Apache Configuration Check
Also test the Apache configuration with the command:
sudo apachectl configtest
The output of this command should be:
Syntax OK
Shibboleth Quick Test
(Re-) Start the web server and then access the URL: https:///Shibboleth.sso/Session.

The web server (or rather the Shibboleth daemon 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.

Service Provider Configuration

After the above tests were successful, continue to the Shibboleth SP configuration. Note that the configuration and migration guides are only for Switch edu-ID Participants who configure a Service Provider for the Switch edu-ID Federation (or the AAI Test Federation). In all other cases refer to the configuration pages in the Shibboleth Wiki.

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.

Additional Information

References

Version Information

Copyright: Switch
Author: aai@switch.ch
URL: index.html