This pages requires Javascript! If javascript is not enabled, most functions will not work.
Shibboleth Service Provider (SP) 3.4 Installation Guide
Table of contents
- Introduction
- Recommendations
- Installation
- Quick Test
- Service Provider Configuration
- Additional Information
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.
1. 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 please report 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:
Red Hat Enterprise Linux 7/8/9, Rocky Linux 8/9, Ubuntu 22/23/24, Debian 11/12 or CentOS Linux 7 or Amazon Linux 2/2023
Windows Server 2008 and later (32-bit and 64-bit Windows)
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.
copypop-up
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
2. 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
copypop-up
apt install sudo
Red Hat Enterprise Linux, CentOS
copypop-up
yum install sudo
Red Hat Enterprise Linux, Rocky Linux
copypop-up
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
copypop-up
apt install curl
Red Hat Enterprise Linux, CentOS 7
copypop-up
sudo yum install curl
Red Hat Enterprise Linux, Rocky Linux 8/9
copypop-up
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.
3. Installation
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.- For Debian and Ubuntu install the
shibboleth
package with:
- For Debian and Ubuntu install the
sudo apt install libapache2-mod-shib
- For Redhat, Centos, Rocky Linux, Amazon Linux fetch the appropriate RPM repository file and then install the
shibboleth
package with:
配置 repo 目录:/etc/yum.repo.d/shibboleth.repo
2.1. Centos9 (RHEL 9)
[shibboleth]
name=Shibboleth (rockylinux9)
# Please report any problems to https://shibboleth.atlassian.net/jira
type=rpm-md
mirrorlist=https://shibboleth.net/cgi-bin/mirrorlist.cgi/rockylinux9
gpgcheck=1
gpgkey=https://shibboleth.net/downloads/service-provider/RPMS/repomd.xml.key
https://shibboleth.net/downloads/service-provider/RPMS/cantor.repomd.xml.key
enabled=1
2.2. Centos8 (RHEL 8)
[shibboleth]
name=Shibboleth (rockylinux8)
# Please report any problems to https://shibboleth.atlassian.net/jira
type=rpm-md
mirrorlist=https://shibboleth.net/cgi-bin/mirrorlist.cgi/rockylinux8
gpgcheck=1
gpgkey=https://shibboleth.net/downloads/service-provider/RPMS/repomd.xml.key
https://shibboleth.net/downloads/service-provider/RPMS/cantor.repomd.xml.key
enabled=1
2.3. Centos7 (RHEL 7)
[shibboleth]
name=Shibboleth (CentOS_7)
# Please report any problems to https://shibboleth.atlassian.net/jira
type=rpm-md
mirrorlist=https://shibboleth.net/cgi-bin/mirrorlist.cgi/CentOS_7
gpgcheck=1
gpgkey=https://shibboleth.net/downloads/service-provider/RPMS/repomd.xml.key
https://shibboleth.net/downloads/service-provider/RPMS/cantor.repomd.xml.key
enabled=1
安装命令:
sudo yum install shibboleth
- 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, - After having installed the package, you need to start and enable the
shibd
daemon:
sudo systemctl start shibd.service
sudo systemctl enable shibd.service
- The Shibboleth Consortium does not support the SP in conjunction with SELinux. Check out the Common Errors topic on SELinux.
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
3.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.
/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.
4. 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
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.
5. 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.
- To create a new configuration, please continue with the SP Configuration Guide for new installations. This is the recommended way.
- 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.
6. Additional Information
6.1. References
- Shibboleth Service Provider - Installation Instructions: Comprehensive installation instructions for various operating systems
- Shibboleth Service Provider - Configuration: Comprehensive reference documentation for
shibboleth2.xml
- Shibboleth Service Provider - Apache Configuration: Documentation for Apache directives provided by Shibboleth
- Shibboleth Service Provider - IIS Configuration: IIS Shibboleth ISAPI filter documentation
- Apache - General Documentation: General Apache documentation
- RPMInstall: Installing the Shibboleth SP from RPM
- IIS 7.x - SSL documentation: SSL for IIS 7.x documentation
- IIS 8.x - SSL documentation: SSL for IIS 8.x documentation
6.2. Version Information
Copyright: Switch
Author: aai@switch.ch
URL: [https://help.switch.ch/aai/guides/sp/installation/](https://help.switch.ch/aai/guides/sp/installation/)
转至:https://help.switch.ch/aai/guides/sp/installation/?os=unix