Shibboleth Service Provider (SP) 3.4 Installation Guide
Table of contents
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.
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 please report any issue you encounter.
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.
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.
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.
We recommend installing sudo for commands that require root privileges.
As root user sudo can be installed with:
Red Hat Enterprise Linux, CentOS 7
yum install sudo
Red Hat Enterprise Linux, Rocky Linux 8/9
dnf install sudo
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:
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. 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.
Install the Shibboleth Service Provider.
Shibboleth Service Provider Installation
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.
Either follow the instructions on the Shibboleth Wiki Page Linux Installation to configure the shibboleth repository and install the RPM package, then come back here to proceed,
Execute the installer package. We recommend to perform the following actions during installation:
Confirm the dialog to run the software
Accept the license agreement
The setup should look like on the screenshot below.
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
Click "Next", then "Install", then "Finish"
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 = Started, Startup Type = Automatic, Logon As = Local System.
Verify IIS settings
Open Internet Information Server (IIS) Manager and verify the Shibboleth ISAPI filter is installed
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
Open Control Panel > System > Advanced System Settings > Advanced > Environment Variables > System variables > New... and add the environment variable:
The Service Provider should now be installed on the system. Of particular interests are the directories:
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:
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 SWITCHaai Participants who configure a Service Provider for the SWITCHaai Federation (or the AAI Test Federation). In all other cases refer to the configuration pages in the Shibboleth Wiki.
To update an existing Shibboleth Service Provider configuration, continue with the Migration Guide for existing installations. This option is only recommended if you are experienced with Shibboleth and if your existing configuration was customized to use advanced Shibboleth features
Mistakes and Improvements?
If you found an error or a typo or if you have suggestions for improvements, please let us know. Your contributions are appreciated very much and they will help your colleagues.