SWITCH Shibboleth Service Provider (SP) 2.6 Configuration Guide

Table of contents

1. No entry yet.

Introduction

This guide describes how to configure the Shibboleth Service Provider (SP) 2.6 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 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 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.

Prerequisites

Service Provider Installed

For the following steps a Shibboleth Service Provider (SP) 2.6 must be installed on your system. If you have not yet installed the Service Provider, please have a look at the Service Provider 2.6 Installation Guide first.

Sudo

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.

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

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:

• C:\opt\shibboleth-sp\etc\shibboleth\/etc/shibboleth/shibboleth2.xml
• C:\opt\shibboleth-sp\etc\shibboleth\/etc/shibboleth/SWITCHaaiRootCA.crt.pem
• C:\opt\shibboleth-sp\etc\shibboleth\/etc/shibboleth/attribute-map.xml
• C:\opt\shibboleth-sp\etc\shibboleth\/etc/shibboleth/attribute-policy.xml

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.

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 (CentOS, RedHat, SuSE, OpenSUSE):

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

Or if the keygen.sh script does not exist with shib-keygen (Debian, Ubuntu):

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

Or a manual creation of the certificate with OpenSSL

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

This will generate a new pair of X.509 certificate and private key.

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

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

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

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

Download shibboleth2.xml

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

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

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

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:

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

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

The attribute map defines which attributes the Service Provider will be able to handle and under which name they are made available to a web application.

Note

This backwards-compatible attribute-map.xml should no longer be used since it is not compatible with Shibboleth Service Provider 3.x. This file includes the deprecated attribute aliases. It allows that an attribute is available under two names, a short name (recommended) and a legacy attribute name usually starting with Shib-. This version should only be used for existing Service Provider as a temporary measure before an application is adapted to use short attribute names. Adapt your applications to use the short attribute names, e.g. mail instead of Shib-InetOrgPerson-mail. Therefore, use this last chance to adapt your applications now!

Download Attribute Policy

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

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

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

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.

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 -k -o /etc/shibbolethSWITCHaaiRootCA.crt.pem http://ca.aai.switch.ch/SWITCHaaiRootCA.crt.pem

C:\'Program Files'\Shibboleth\SP\lib\curl.exe -k -o C:\opt\shibboleth-sp\etc\shibbolethSWITCHaaiRootCA.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 configuration then uses the SWITCHaai Root CA certificate like shown below:

<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="EntityRoleWhiteList">
       <RetainedRole>md:IDPSSODescriptor</RetainedRole>
       <RetainedRole>md:AttributeAuthorityDescriptor</RetainedRole>
    </MetadataFilter>
</MetadataProvider>

Configuration Test

After the configuration 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

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.

Apache Configuration Check

Also test the Apache configuration with the command:

sudo apache2ctl configtest

or

sudo apachectl configtest

The output of either of these commands should be:

Syntax OK

mod_shib Test

Restart the web server and the 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.

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.

If you need more information on how to register the Service Provider with the Resource Registry, 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.

1. 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.
2. On the Discovery Service/WAYF choose your HomeOrganization to authenticate.
   You should be redirected to the login page of your HomeOrganization.
3. Authenticate at your HomeOrganization to access the Session Handler.
4. 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 SWITCHaai federation are announced in the SWITCH edu-ID Newsletter.
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.

Common Problems

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 aai@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
• 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.

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