Switch Shibboleth Service Provider (SP) 3.4 Configuration Guide

Table of contents

No entry yet.

Note regarding Upgrades to Shibboleth SP 3

Shibboleth SP v3.4.1 was released on 10. January 2023.
Shibboleth SP v3 does support the SP v2 configuration format, therefore, the SP v2 configuration files are forward-compatible with SP v3.
However, we strongly recommend to apply the changes as described in the Switch Shibboleth SP Migration guide if your configuration is from a v2 installation. Otherwise, the shibd will clutter the log file with many deprecation warnings.

Note

Use this SP configuration guide only if you want to install a Shibboleth Service Provider for the Switch edu-ID Federation (in naming transition from SWITCHaai Federation) or the AAI Test Federation, both operated by Switch.
In all other cases, follow the installation and configuration instructions on the official Shibboleth Wiki of the Shibboleth Consortium or the deployment instructions of the federation into which the Service Provider should be integrated.

Introduction

This guide describes how to configure the Shibboleth Service Provider (SP) 3.4 for usage in the Switch edu-ID Federation 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 3.4 Installation Guide.
If you have an existing Service Provider that used an older version of Shibboleth, you should perform a clean configuration using this guide or alternatively, you could also try to upgrade the old configuration according to the Switch Shibboleth SP Migration Guide.

Prerequisites

Service Provider Installed: For the following steps a Shibboleth Service Provider (SP) 3.4 must be installed on your system. If you have not yet installed the Service Provider, please have a look at the Service Provider 3.4 Installation Guide first.
sudo: We recommend installing sudo for commands that require root privileges.
SSL enabled for Apache: Enable and configure the Apache SSL module mod_ssl to support HTTPS. By default, the SAML assertions containing user attributes are encrypted, so one could send them via the insecure HTTP protocol. However, successfully authenticated 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.

Requirements

The following software must be installed in order to operate a 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.
OpenSSL: 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.

Setup Profile

For custom-tailored configuration instructions matching the system to be configured, please first complete the form below.

Basic Configuration
Select the operating system:	Unix-based System (including macOS) Windows System
In which federation would you like to deploy your SP?
Hostname (Fully qualified domain name) of the service?
Set the `entityID` (unique identifier) of the Service Provider:
Note: entityID naming convention for Shibboleth SP instances `https://#service host name#/shibboleth`. In case the service host name (e.g., `elearning.example.org`) is different from the system name (e.g. `web-host27.example.org`), always prefer the service host name.
Filesystem path to the configuration directory:
Filesystem path to the X.509 key used by the Shibboleth SP:
Filesystem path to the X.509 certificate used by the Shibboleth SP:
Default URL to send the user after authentication: Ideally, this is a Shibboleth SP-protected page that initializes the user session.
Support contact email address of the resource: Will be shown in Shibboleth SP error messages
Advanced Configuration Options
Enable Metadata Attributes Support:	Configure Service Provider to extract public attributes from metadata. More ...
Extracted Metadata Attributes Info Since SP v2.5, the Shibboleth Service Provider can extract additional information about the Identity Provider of the current user from the SAML2 metadata files. This information then is made available to web applications like any other AAI attribute. In particular the metadata attributes typically include for Switch edu-ID Identity Providers: organization display name (available for all Switch edu-ID Identity Providers) organization web page (available for all Switch edu-ID Identity Providers) organization error/help URL organization privacy statement URL organization information URL organization logos (16x16px and typically 80x60px, available for all Switch edu-ID Identity Providers) organization contacts (support contact available for all Switch edu-ID Identity Providers) Note: Since SPv3.3, this feature generates `WARN Shibboleth.DEPRECATION : DOMAttributeDecoder` entries! For a demonstration how the metadata attributes can be used, access the AAI Attribute Viewer, log in and then see what attributes are available about you. Additional technical information about metadata attributes can be found on the Shibboleth Attribute Extractor wiki page.
Configure as "edu-ID-only" Service Provider:	Configure Service Provider for edu-ID extended attribute model. More ...
edu-ID Extended Model Info Enabling this option configures the Shibboleth SP to directly send all users to the edu-ID login service for authentication. The Service Provider will be configured to accept SAML assertions only from the edu-ID Identity Provider. It will be configured to support all edu-ID specific attributes, which are available for edu-ID users. Enabling this option requires that all user have or create a Switch edu-ID account! By definition, all users from organisations which already adopted edu-ID have a Switch edu-ID account. This option cannot be enabled when the service needs interfederation support or when the edu-ID classic attribute model is required.
Enable Interfederation/eduGAIN Support:	Configure Service Provider for Interfederation. More ...
Interfederation/eduGAIN Info Enabling the Interfederation/eduGAIN option allows a service protected by the Service Provider to be accessed not only by Switch edu-ID users but also by users from foreign SAML2 identity federations. Interfederation support is in particular enabled via the eduGAIN interfederation service. Before enabling this option, please first have a look at the AAI Interfederation page and contact the Switch edu-ID team for assistance. Enabling this option is recommended if the service shall also be used by users from non-Swiss organisations. Interfederation support for Federation Partner SPs is a service option. Ask for the conditions. This option cannot be enabled when the service is an edu-ID-only service or it is configured for the AAI Test Federation.

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.
Store the following files into the configuration directory /etc/shibboleth/:

X.509 certificate for SAML message signing/encrypting

The Shibboleth daemon (shibd) needs an X.509 keypair for signing and encrypting SAML messages. Switch recommends to use a dedicated self-signed certificate, independently configured from the SSL/TLS certificate used by the Web server. Checkout the Certificate Overview to better understand the role the certificates play in this context.
The web server can use any certificate for providing TLS/SSL. In addition, the Shibboleth SP also needs a keypair with 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 SWITCHaai Certificate Acceptance Policy) or one can create an independent self-signed certificate for usage by the Shibboleth SP only. Switch recommends to use a long-lived, self-signed certificate for usage by the Shibboleth SP.

Generate Certificate and Key

The goal of this step is to create an X.509 certificate that meets the SWITCHaai Certificate Acceptance Policy (key size 3072 bits, 10 years validity). Open a terminal window and run the following command:

Depending on your operating system, the script to generate a new certificate is named differently. Run either of the two commands:

With keygen.sh (Red Hat Enterprise, Rocky, CentOS):

sudo /etc/shibboleth/keygen.sh -f -u shibd -h yourhost.example.org -y 10 -o /etc/shibboleth/

Or with shib-keygen (Debian, Ubuntu):

sudo shib-keygen -f -u _shibd -h yourhost.example.org -y 10 -o /etc/shibboleth/

Or by manually generating a self-signed certificate with OpenSSL

C:\opt\shibboleth-sp\etc\shibboleth\keygen.bat -f -h yourhost.example.org -y 10 -o C:\opt\shibboleth-sp\etc\shibboleth\

This generated a new pair of X.509 self-signed certificate named sp-cert.pem and private key named sp-key.pem in the /etc/shibboleth/ directory.

BTW: A useful OpenSSL command to inspect the certificate's content:

openssl x509 -in /etc/shibboleth/sp-cert.pem -text -noout

C:\'Program Files'\Shibboleth\SP\lib\openssl.exe x509 -in C:\opt\shibboleth-sp\etc\shibboleth\sp-cert.pem -text -noout

Shibboleth SP Configuration

This chapter describes how to configure the Shibboleth Service Provider for usage in the federation.

Configuration Files

In this section all the federation-specific configuration files are downloaded and deployed. In particular shibboleth2.xml, the main configuration of the Shibboleth Service Provider. The name was not changed despite incrementing the major version number for SP v3.

Download shibboleth2.xml

Use curl (or your web browser) to download the Shibboleth main configuration file shibboleth2.xml to the configuration directory:

sudo curl --output /etc/shibbolethshibboleth2.xml 'download/customize.php/shibboleth2.xml'

C:\'Program Files'\Shibboleth\SP\lib\curl.exe --output C:\opt\shibboleth-sp\etc\shibbolethshibboleth2.xml 'download/customize.php/shibboleth2.xml'

Open the shibboleth2.xml file 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:

sudo curl --output /etc/shibbolethattribute-map.xml 'download/customize.php/attribute-map.xml'

C:\'Program Files'\Shibboleth\SP\lib\curl.exe --output C:\opt\shibboleth-sp\etc\shibbolethattribute-map.xml 'download/customize.php/attribute-map.xml'

The attribute-map.xml file defines which attributes the Service Provider will be able to handle and under which name they are made available to web applications.

Download Attribute Policy

Use curl (or your web browser) to download the attribute-policy.xml file to the configuration directory:

sudo curl --output /etc/shibbolethattribute-policy.xml 'download/customize.php/attribute-policy.xml'

C:\'Program Files'\Shibboleth\SP\lib\curl.exe --output C:\opt\shibboleth-sp\etc\shibbolethattribute-policy.xml 'download/customize.php/attribute-policy.xml'

The attribute-policy.xml file 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.

Metadata Validation

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:

sudo curl --output /etc/shibboleth/SWITCHaaiRootCA.crt.pem http://ca.aai.switch.ch/SWITCHaaiRootCA.crt.pem

C:\'Program Files'\Shibboleth\SP\lib\curl.exe --output C:\opt\shibboleth-sp\etc\shibboleth\SWITCHaaiRootCA.crt.pem http://ca.aai.switch.ch/SWITCHaaiRootCA.crt.pem

Curl is bundled with the Windows version of the Service Provider. It can be found in the shibboleth-sp\sbin\ directory of your Shibboleth installation.

Compare the certificate fingerprint with the fingerprint of the SWITCHaai Root CA certificate shown on https://www.switch.ch/pki/aai/:

openssl x509 -in /etc/shibboleth/SWITCHaaiRootCA.crt.pem -noout -fingerprint -sha256

C:\'Program Files'\Shibboleth\SP\lib\openssl.exe x509 -in C:\opt\shibboleth-sp\etc\shibboleth\SWITCHaaiRootCA.crt.pem -noout -fingerprint -sha256

The SHA-256 fingerprint should match exactly:

SHA256 Fingerprint=37:DC:E4:D7:1C:24:42:32:6A:0F:85:B6:12:00:22:C7:54:AA:FF:B2:8C:BF:CF:69:EB:F3:F7:31:90:3C:09:5A

The Metadata Provider configuration in the shibboleth2.xml file refers to the local copy of the SWITCHaai Root CA certificate as trust root:

<MetadataProvider type="XML"
                  validate="true"
                  url="http://metadata.aai.switch.ch/metadata.switchaai%2Bidp.xml"
                  backingFilePath="metadata.switchaai+idp.xml"
                  reloadInterval="3600">
    <MetadataFilter type="RequireValidUntil"
                    maxValidityInterval="604800"/>
    <MetadataFilter type="Signature" verifyBackup="false" >
        <TrustEngine type="StaticPKIX"
                     certificate="SWITCHaaiRootCA.crt.pem"
                     verifyDepth="2"
                     checkRevocation="fullChain"
                     policyMappingInhibit="true"
                     anyPolicyInhibit="true">
              <TrustedName>SWITCHaai Metadata Signer</TrustedName>
              <PolicyOID>2.16.756.1.2.6.7</PolicyOID>
       </TrustEngine>
    </MetadataFilter>
    <MetadataFilter type="EntityRole">
       <RetainedRole>md:IDPSSODescriptor</RetainedRole>
       <RetainedRole>md:AttributeAuthorityDescriptor</RetainedRole>
    </MetadataFilter>
</MetadataProvider>

Note

If configured according to this guide, the Shibboleth SP will automatically, regularly download metadata and CRL files. These files are by default stored in the directory /var/cache/shibboleth/C:\opt\shibboleth-sp\var\cache\shibboleth\. This differs from previous installations where the metadata file used to be in the configuration directory /etc/shibboleth/.

Configuration Test

After the configuration a quick test shows whether the Service Provider was installed properly.

Shibboleth Configuration Check

On the command line, execute the following command to see whether the Shibboleth Service Provider can load the default configuration:

sudo shibd -t

C:\opt\shibboleth-sp\sbin\shibd.exe -check

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 unproblematic. Anyhow, it is recommended to examine the problem. E.g. since SPv3.3 the MetadataGenerator handler causes a WARN Shibboleth.DEPRECATION : MetadataGenerator handler message. The MetadataGenerator handler is useful for the initial registration in the Resource Registry with the SAML2 metadata wizard. Thereafter, consider to disable this handler in shibboleth2.xml to suppress the message.
Finally restart the shibd daemon to activate the configuration changes applied above.

Apache Configuration Check

Also test the Apache configuration with the command:

sudo apache2ctl configtest

sudo apachectl configtest

The output of either of these commands should be:

Syntax OK

mod_shib Test

Restart the web server, then access the URL: https://yourhost.example.org/Shibboleth.sso/Session.
The web server (or Shibboleth module respectively) should return a page that says:

A valid session was not found.

This message demonstrates that the Shibboleth module is loaded by the webserver and is communicating with the shibd process.
In case your web server returns a 404 Not found error message instead, check out the Properly Routing Handler URLs section in the Shibboleth Wiki.

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:

Go to the AAI Resource Registry.
Log in using an existing an account of one of the Switch edu-ID organisations or select the Switch edu-ID if you don't have an account at one of the listed organisations.
In case you don't have an AAI account yet, you may want to create a Switch edu-ID account beforehand.
In order to create a new Resource Description, click on the Run Shibboleth 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.

If you need additional guidance on how to register the Service Provider with the Resource Registry, please also have a look at the Resource Registration Screencast.

Login Test

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.

Access the URL https://yourhost.example.org/Shibboleth.sso/Login?target=https%3A%2F%2Fyourhost.example.org%2FShibboleth.sso%2FSession
You should be redirected to the Discovery Service/WAYF.
On the Discovery Service/WAYF choose your Home Organization to authenticate.
You should be redirected to the login page of your Home Organization.
Authenticate at your Home Organization 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.

Access Control

Now you should be able to use Shibboleth to perform access control and to use SAML attributes in your web applications as is described in the following.

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. For other applications one may need/want to implement access control based on attributes on his own. In this case, ensure that these directories, or individual pages where the attributes should be available, are processed by the Shibboleth SP. This can be achieved with:
Apache:
Adding the following directives to the Apache configuration:

<Location /my-directory/>
  AuthType shibboleth
  ShibRequestSetting requireSession true
  Require shibboleth
</Location>

Microsoft IIS:
Change the RequestMap element in shibboleth2.xml like below to make IIS activate Shibboleth for the directory my-directory and its subdirectories.

<Host name="yourhost.example.org">
    <Path name="my-directory" authType="shibboleth" requireSession="true" />
</Host>

Create Access Control Rules

If you don't want to allow just any AAI user, you might want to configure some Shibboleth Access Control Rules. Otherwise your application is NOT protected.

Subscribe to the AAI mailing lists

Important general announcements concerning the Switch edu-ID federation are announced in the Switch edu-ID News.
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.

Troubleshooting

If the access via Shibboleth did not work as expected, find below some instructions on how to debug problems.

Debugging Instructions

In case of problems, it is best to try these steps.

On the command line, execute the following command to see whether the Shibboleth Service Provider can load the default configuration:
```
sudo shibd -t
```
```
C:\opt\shibboleth-sp\sbin\shibd.exe -check
```
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.
If you applied changes to any configuration file, restart the shibd daemon to activate them.
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.

Common Problems

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. It could also mean that you made a typo in a service location URL when the SP was registered in the AAI Resource Registry.
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_shibIIS Shib module cannot communicate with the shibd process. Either because shibd is not running (check that the process is running), because SELinux in enforcing mode blocks it or because they use different configuration files (e.g. /etc/shibboleth/shibboleth2.xml and /opt/local/etc/shibboleth/shibboleth2.xml).
The Shibboleth Wiki provides hints how to fix the SELinux issue with an SELinux policy module.
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. Use the Attribute Release Inspector in the AAI Resource Registry and check if the Identity Provider you used to authenticate has the necessary attribute release rules for your service. A likely reason for not receiving attributes is that the "Intended Audience" settings don't include the Identity Provider that was used for authentication.
Interfederation enabled SP on a system with systemd fails to start or restart shibd: On systems with systemd, starting or restaring the shibd process might timeout and fail. Loading and verifying very large SAML Metadata files could be the cause, namely on interfederation enabled SPs. Read Increase startup timeout in the Shbboleth Wiki.

In case you don't understand or don't find the cause of the error, have a look at the Shibboleth Wiki Common SP Errors web page or contact eduid-support@switch.ch.

Additional Information

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
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

Advanced Configuration

Error Pages Customization: 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.
Discovery Service Options: In order to further improve the user experience of the Home Organisation selection process, you might consider adding the Switch Embedded WAYF or the Shibboleth Embedded Discovery Service to your web application.

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.

URL: index.html
Author: eduid-support@switch.ch