Shibboleth Service Provider (SP) 2.5 Installation Guide

Table of contents

1. No entry yet.

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:

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.

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.

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

yum 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-get install curlsudo yum 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 IIS

The IIS website should have an appropriate x509 certificate installed and SSL enabled.

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.

Mac Ports

To install the Shibboleth Service Provider package on Mac OS X, the package management system Mac Ports must be installed. If not yet installed, please install Mac Ports on the system. Prerequisite for using Mac Ports is that the Apple Developer Tools (e.g. XCode) are installed on the system as Mac Ports 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 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.

Installation

Install the Service Provider by:

Shibboleth Service Provider Installation

sudo apt-get install shibboleth

For 32-bit OS:

sudo yum install shibboleth

For 64-bit OS:

sudo yum install shibboleth.x86_64

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. It is therefore ok to agree that old versions (like libapache2-mod-shib2 libshibsp4 opensaml2-schemas shibboleth-sp2-schemas) are removed.

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. To disable SELinux, configure SELINUX=disabled in /etc/selinux/config and reboot the system.

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.

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 Shib 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.
   
   Install the Service Provider into the default location to C:\opt\shibboleth-sp
   For the 64-bit installer package only: "Run as 32-Bit" should be unchecked unless Shibboleth is used with a 32-bit application pool
   "Install ISAPI modules into IIS" should be checked
   IIS Script Extension should be the default ".sso"
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 2 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

• In 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.
• In IIS 7: Click on the server name, open ISAPI Filters.
  You should see Name = Shibboleth, Executable = C:\opt\shibboleth-sp\lib64\shibboleth\isapi-shib.dll for a 64-bit install.

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.

/var/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.

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

or

sudo apachectl configtest

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.

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.

Additional Information

References

• Shibboleth Service Provider - Installation Instructions: Comprehenisve 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 2.2 - General Documentation: General Apache documentation
• NativeSPLinuxRPMInstall: 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

Version Information

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