SWITCH Shibboleth Service Provider (SP) 2.5 Configuration Guide
Table of contents
No entry yet.
This guide describes how to configure the Shibboleth Service Provider (SP) 2.5 for usage in the SWITCHaai or AAI Test federations.
Only the configuration of the Service Provider is covered. If the Service Provider has not yet been installed, first follow the Service Provider 2.5 Installation Guide. If you have an existing Service Provider that used an older version of Shibboleth, you might perform a clean configuration using this guide or alternatively, you could also try to upgrade the old configuration using to the Service Provider 2.5 configuration migration guide.
Best Current Practices (BCP) for operating a SWITCHaai Service Provider
Before installing and configuring a Service Provider, we recommend to have a look at chapter 4. Operation of the Current Best Practices document. It makes useful recommendations regarding the security, availability and general operation of the Service Provider.
Service Provider Installed
For the following steps a Shibboleth Service Provider (SP) 2.5 must be installed on your system. If you have not yet installed the Service Provider, please have a look at the Service Provider 2.5 Installation Guide first.
We recommend installing sudo for commands that require root privileges.
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, successfully authenticated Shibboleth users accessing a web page via HTTP are prone to session hijacking attacks.
SSL enabled for IIS
The IIS website should have an appropriate x509 certificate installed and SSL enabled.
The following software must be installed in order to operate a Shibboleth Service Provider.
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.
For verifying certificate fingerprints or for certificate inspection OpenSSL is required.
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.
Before continuing to the next section, please ensure that the requirements above are met on the system where the Shibboleth Service Provider is installed on.
Examine and Update Setup
After completing and verifying the setup information above, click on the button "Update Configuration Guide with above Data"
Quick Configuration Files Download
If you are in a hurry and know the whole setup process, you can download all configuration files directly and store them in /etc/shibboleth:
X.509 certificate for SAML message signing/encrypting
The Shibboleth daemon (shibd) needs an X.509 certificate for signing and encrypting SAML messages. SWITCH recommends to use a dedicated self-signed certificate, which is independently configured from the SSL/TLS certificate used by the Web server.
The web server can use any certificate for providing TLS/SSL. But the Shibboleth Service Provider also needs a certificate for signing and decrypting messages. The Service Provider can either use the same certificate as is used for the web server (provided it meets the AAI X.509 Certificate Requirements) or one can create an independent self-signed certificate for usage by the Shibboleth Service Provider only. SWITCH recommends to use a self-signed certificate for usage by the Shibboleth Service Provider.
Open the shibboleth2.xml and review the Shibboleth configuration. You might want to change some settings for more advanced use cases like defining multiple Shibboleth applications. If you are using IIS with multiple sites, make sure to review the <Site> element and its id value. Shibboleth requires the site ID value. The site id for the default IIS Site is one 1, which is also the default value used in the Shibboleth configuration. For all other Sites, the site ID can be seen via the Site Advanced Settings
There are two more federation-specific files that need to be deployed for the proper attribute handling in the federation.
Download Attribute Map
Use CURL (or your web browser) to download the attribute-map.xml file to the configuration directory:
The attribute policy defines which attributes and which values the Service Provider will accept from which Identity Provider. Attributes and values that don't match the rules are filtered out by the Service Provider.
In order to validate the federation metadata files downloaded by the Service Provider
Download Root Certificate
Open a terminal window and use CURL (or your web browser) to download the root certificate to the configuration directory:
This message demonstrates that the Shibboleth module is loaded by the webserver and is communicating with the shibd process.
Register Service Provider
To integrate the Service Provider into the federation, it needs to be registered with the Resource Registry, so that its metadata is added to the officially distributed federation metadata. This step is a prerequisite for successfully communicating with the identity providers in the federation.
To register the Service Provider you need to create a new Resource Description by:
Log in using an account of the SWITCHaai federation (even if you want to register a resource for the AAI Test federation).
In case you don't have an AAI account yet and if you represent an existing Federation Partner (or its contractor), please ask firstname.lastname@example.org for a Virtual Home Organization (VHO) account. If your company is not yet a SWITCHaai Federation Partner, please have a look at the page for new Federation Partners, if appropriate. Technical contacts of Federation Partners can request VHO accounts like described above.
In order to create a new Resource Description, click on the Run Shibboleth 2.x wizard and provide the URL https://yourhost.example.org/Shibboleth.sso/Metadata as metadata handler URL.
If the wizard complains that it cannot download the metadata this may be because the host is not reachable from the Internet. In this case, open the above link in the web browser and copy & paste the XML metadata into the text area of the Resource Registry.
Complete the remaining forms that are marked incomplete. Some forms are optional but it still is recommended to complete them.
If all sections are completed and their status is either ok or optional, click on the button Submit for Approval.
It is recommended to provide a short comment for what purpose this Resource Description was created.
A Resource Registration Authority (RRA) administrator of your organization or from SWITCH then will approve the new Resource Description after examination. Only after the Resource Description has been approved it becomes active and only after this step it will be included in federation metadata. After approval it may take up to two hours until the Service Provider can be used because all Identity Provider first have to refresh the federation metadata.
After the Resource Description in the Resource Registry was approved by an RRA administrator, you have to wait two hours before you can continue (to allow the Identity Providers to download the latest metadata). You can then test whether the Service Provider is correctly deployed by accessing the Session Initiator Handler URL.
On the Discovery Service/WAYF choose your HomeOrganization to authenticate.
You should be redirected to the login page of your HomeOrganization.
Authenticate at your HomeOrganization to access the Session Handler.
What you should see there is the session information containing the used Identity Provider, authentication instant and at the bottom the available attributes. The number of attributes is depending on which attributes were declared as required and desired during the registration at the Resource Registry. An example screenshot of the session handler is given below.
Configure your application
Some applications, e.g. Learning Management Systems, have options to enable Shibboleth, which means you might configure a data mapping between the AAI attributes and your application.
Important general announcements concerning the SWITCHaai federation are announced on the AAI-Announce mailing list.
Technical information like security advisories and short-term recommendations are published on the AAI-Operations mailing list.
It is recommended that the administrators of the Service Provider subscribe to both lists.
If the access via Shibboleth did not work as expected, find below some instructions on how to debug problems.
In case of problems, it is best to try these steps.
In the command line, execute the following command to see whether the Shibboleth Service Provider can load the default configuration:
sudo shibd -t
If the last line of the output is the following message, everything is as expected:
overall configuration is loadable, check console for non-fatal problems
If there are any ERROR messages, it is strongly recommended to have a look at the problem. Messages with log level WARN are generally not problematic but it also is recommended to examine the problem.
Examine the Shibboleth Service Provider daemon log file. By default it can be found at: /var/log/shibbolethC:\opt\shibboleth-sp\var\log\shibboleth\.
The exact location of the log files is defined in the shibd.logger configuration file.
Open the log file with lesswith a text editor like Notes, scroll down to the end of the log file and locate messages with the log level ERROR or WARN.
Sometimes it helps to temporarily increase the log level (log4j.rootCategory) in shibd.logger to DEBUG. This results in a much more verbose output after a restart of the Service Provider.
Don't forget to reset the log level back to WARN or INFO once the issue has been resolved. Otherwise Shibboleth might remove older messages from the log files to keep the log files at a fixed maximum size.
Find below a list of common problems and possible solutions:
Identity Provider complains No return endpoint available for relying party after authentication
This means that the Identity Provider has no metadata for your Service Provider yet, either because you have not registered the Service Provider yet with the Resource Registry, because the Resource Description has not been yet approved or because the Identity Provider has not yet downloaded the metadata file containing the Service Provider description.
Service Provider complains Unable to resolve any key decryption keys after authentication
This means that the Service Provider uses a different pair of X.509 certificate/key than was used to register the Service Provider with the Resource Registry. Please compare the certificate used by the Service Provider with the certificate that you used to create the Resource Description. Most likely, they are not the same.
The Service Provider complains Can't connect to listener process
This means that the mod_shib module cannot communicate with the shibd process. Either because shibd is not running (check that the process is running) or because they use different configuration files (e.g. in /etc/shibboleth/shibboleth2.xml and /etc/shibboleth/shibboleth2.xml)
No attributes are available at the Service Provider after authentication
Access the session handler of the Service Provider after authentication at: https://yourhost.example.org/Shibboleth.sso/Session
If there are no attributes listed there, the most likely reason is that the Identity Provider did not release any attributes because it does not belong to the intended audience. Check the Resource Description in the Resource Registry and make sure that the Identity Provider you used to authenticate belongs to the intended audience.
All error pages and messages shown by Shibboleth can be customized. The default template files *.html can all be found in the configuration directory /etc/shibboleth. The most important templates are: accessError.html, attrChecker, localLogout and sessionError. In these templates one can use various parameters that are made available by the Service Provider. Have a look at the Shibboleth Template documentation.