Shibboleth Service Provider (SP) 3.2 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.2 on the supported operating systems below.
We did not test the SP on all OS versions, so any issue you encounter.

First select the operating system that is used on the host where the Shibboleth Service Provider is installed:





(not macOS 11)

This guide covers only installation but not the 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 Configuration Guide.

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

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.

Requirements

The following requirements must be met to install and operate the Shibboleth Service Provider.

Microsoft IIS
Because Shibboleth is mostly used for web authentication, a web server is needed. In this guide a Microsoft IIS webserver is required. It is also possible to use the Shibboleth SP with Apache on Windows but this combination is not covered in this guide.
Apache Webserver
Because Shibboleth is mostly used for web authentication, a web server is needed. In this guide an Apache webserver is required for the Shibboleth Service Provider. It is also possible to use the Shibboleth SP with Nginx but this is out of scope for this guide.
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.
MacPorts
To install the Shibboleth Service Provider package on macOS, the package management system MacPorts must be installed. If not yet installed, please install MacPorts on the system. Prerequisite for using MacPorts is that XCode is installed on the system as MacPorts must compile some software.
IIS Management Compatibility
IIS 6 Management Compatibility should be installed on IIS 7.x since the Shibboleth installer package uses those management interfaces. Without IIS 6 Management Compatibility additional manual configuration steps not covered in this document will be required. The IIS 6 Management Compatibility option can be installed from Administrative Tools > Server Manager > Web Server (IIS) > Role Services.
Remove manually compiled/installed Service Provider
Before installing the Shibboleth Service Provider 3.2 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.

Recommendations

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. 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 install sudo
yum install sudo
dnf install sudo
zypper 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 install curlsudo yum install curlsudo dnf 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.
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.

Shibboleth Repository

The Shibboleth project maintains its own 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, it is recommended to prefer this repository and its packages over packages that may be provided by the OS distribution.

The Shibboleth project only provides official binary packages for RPM-based Linux distributions. Until end of November 2022, SWITCH provides a repository with packages for the current Debian stable release. To configure this repository as an additional source for APT, follow these steps:

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 Ubuntu LTS release. To configure this repository as an additional source for APT, follow these steps:

The Shibboleth project maintains the official Shibboleth Service Provider MacPorts packages. Therefore, no specific repository has to be configured for macOS provided MacPorts is installed.

Download repository package
curl --fail --remote-name https://pkg.switch.ch/switchaai/debian/dists/buster/main/binary-all/misc/switchaai-apt-source_1.0.0_all.deb
curl --fail --remote-name https://pkg.switch.ch/switchaai/ubuntu/dists/bionic/main/binary-all/misc/switchaai-apt-source_1.0.0ubuntu1_all.deb
curl --fail --remote-name https://pkg.switch.ch/switchaai/ubuntu/dists/focal/main/binary-all/misc/switchaai-apt-source_1.0.0~ubuntu20.04.1_all.deb
Install repository package
sudo apt install ./switchaai-apt-source_1.0.0_all.deb
sudo apt install ./switchaai-apt-source_1.0.0ubuntu1_all.deb

Ubuntu's universe section is also required for Shibboleth. Make sure it is enabled in /etc/apt/sources.list.

sudo apt install ./switchaai-apt-source_1.0.0~ubuntu20.04.1_all.deb

Ubuntu's universe section is also required for Shibboleth. Make sure it is enabled in /etc/apt/sources.list.

Download & install repository package
  • Either follow the instructions on the Shibboleth Wiki Page Linux Installation to configure the shibboleth repository,
  • or if you are experienced, fetch the appropriate RPM repository file.
  • Refresh Repository
    sudo apt update
    sudo zypper ref -s
    sudo port sync
    Note
    The package repository on https://pkg.switch.ch/switchaai/ is operated for the SWITCH community and support is limited to SPs registered in the SWITCHaai federation. Use of the repository by other parties is permitted, but in this case it is provided as is and without any support.

    Installation

    Install the Shibboleth Service Provider.

    Shibboleth Service Provider Installation
    Option A: Upgrade from Previous Installation: If you upgrade from a previous installation (e.g. SP 3.0), run the following commands:
    sudo apt update
    sudo apt install --install-recommends shibboleth
    sudo apt full-upgrade
    sudo apt autoremove
    The above commands ensure that there are no conflicts because some packages were renamed for SP 3.
    For 32-bit OS:
    sudo yum install shibboleth
    For 64-bit OS:
    sudo yum install shibboleth.x86_64
    For 32-bit OS:
    sudo dnf install shibboleth
    For 64-bit OS:
    sudo dnf install shibboleth.x86_64
    DNF will then show a message like:
    Importing GPG key 0x7D0A1B3D:
    Userid     : "security:shibboleth OBS Project <security:shibboleth@build.opensuse.org>"
    Fingerprint: 6519 b5db 7c1c 8340 a954 ed00 73c9 3745 7d0a 1b3d
    From       : http://download.opensuse.org/repositories/security:/shibboleth/CentOS_8/repodata/repomd.xml.key
    Is this ok [y/N]: 
    Verify that the fingerprint of the repository signing key is 6519 b5db 7c1c 8340 a954 ed00 73c9 3745 7d0a 1b3d.
    If this is the case, answer with 'Y' for yes.
    sudo zypper install shibboleth
    sudo port install curl +ssl sudo port 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. Therefore, it is OK to agree that old packages (like libapache2-mod-shib2, libsaml8, libshibsp6, libxmltooling6, opensaml2-schemas, shibboleth-sp2-schemas) are removed. If asked whether you want to import the GPG key with userid "security:shibboleth OBS Project <security:shibboleth@build.opensuse.org>" and fingerprint: 6519 b5db 7c1c 8340 a954 ed00 73c9 3745 7d0a 1b3d answer with 'Y'.

    After installation of the package, you need to start the shibd daemon:
    sudo service shibd start

    After installation of the package, you need to start and enable the shibd daemon:

    sudo systemctl start shibd.service
    sudo systemctl enable shibd.service

    Shibboleth does not support the SP in conjunction with SELinux. Check out the Common Errors topic on SELinux.

    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.

    Option B: Fresh Installation: If no Service Provider was previously installed on the system, run:
    sudo apt update
    sudo apt install --install-recommends shibboleth
    Make Service Provider Start on Boot
    sudo launchctl load -Fw /Library/LaunchDaemons/org.macports.shibd.plist
    Create symlinks
    sudo ln -s /opt/local/etc/shibboleth /etc/shibboleth
    sudo ln -s /opt/local/var/log/shibboleth /var/log/shibboleth
    sudo ln -s /opt/local/etc/shibboleth/apache22.config /etc/apache2/other/shibboleth.conf
    
    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 = 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
    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/etc/default/shibd
    export http_proxy=proxy.example.org:8080
    Add the following lines in /Library/LaunchDaemons/org.macports.shibd.plist:
    ...
     <key>RunAtLoad</key> <false/>
        <key>OnDemand</key> <true/>
        <key>StandardErrorPath</key> <string>/dev/null</string>
        <key>UserName</key> <string>root</string>
             <key>Umask</key> <string>0022</string>
             <key>EnvironmentVariables</key>
             <dict>
                <key>http_proxy</key>
                <string>proxy.example.org:8080</string>
             </dict> 
    </dict>
    </plist>
    
    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 /opt/local/var/run/shibboleth C:\opt\shibboleth-sp\var\run\shibboleth
    Runtime directory where process ID and socket files are stored.
    /var/cache/shibboleth /opt/local/var/cache/shibboleth C:\opt\shibboleth-sp\var\cache\shibboleth
    Cache directory where metadata backup and CRL files are stored.
    /etc/init.d /Library/LaunchDaemons/
    Init script directory where the startup script for the shibd daemon is 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 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
    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 apache2ctl configtest
    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 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.

    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