This guide describes the installation and configuration of a
Shibboleth Sevice Provider (SP)
2.4.3 on a Windows with IIS system.
It covers the installation of the Shibboleth web server module as
well as the Shibboleth daemon and their configuration for the SWITCHaai or AAI Test
federation.
For further information about the Shibboleth Sevice Provider, please have a
look at the references.
Assumptions
Please ensure that the following prerequisites are met before proceeding
with the installation of the Shibboleth Service Provider:
X.509 certificate
A valid certificate is required for decrypting SAML assertions and/or
establishing SSL connections to Identity Providers.
Please refer to
http://www.switch.ch/aai/certificates/ for further information about
certificates and certificate requirements.
The same certificate can be used by the web server and by the Shibboleth
Service Provider. However, it is recommended that Shibboleth uses a self-signed certificate whereas the web server should use a certificate from a well-known CA.
Please follow the steps described below to create a self-signed certificate for between the Shibboleth components.
See
SWITCHaai Certificate Acceptance Policy.
The following issues are known and should be taken into account when
installing a Shibboleth Service Provider:
libcurl SSL/TLS support
The Shibboleth Service Provider requires that the libcurl library is
linked against openssl and not gnutls.
1. Setup Profile
In order make configuration easier and more convenient we kindly ask you to
provide some information about your environment. This allows aut-generating
and custom-tailoring some of the configuration files.
1.1 Quick download of configuration files
If you are in a hurry and know the whole setup process, you can download
all relevant configuration files directly here:
Before starting to build and configure the Shibboleth Sevice Provider, assure that the following prerequisites are met:
IIS 6
The server has to be configured as a Web Server by selecting the "Internet Information Service (IIS)" option in the Windows Component selection tool.
Assure that IIS 6 is properly configured and working.
Service Packs
It is strongly recommended to have an up-to-date system before starting the installation.
NTP
The Windows Time service (w32time) has to be activated and well configured.
Servers running Shibboleth should have their system time synchronized in order to avoid clock-skews.
Choose C:\opt\shibboleth-sp\ as destination folder
Check 'Install Shibd daemon' and choose 1600 as port number
Check 'Install ISAPI module' and choose .sso as file extension
Finish the installation
Restart your computer
3.2 Webserver Configuration
After rebooting, IIS should be configured for basic support (if you asked it to do so).
If you have problems, need to manually configure it or want to verify what happened, the IIS steps are described here.
For an instant test, if the Shibboleth deamon and ISAPI Filter are working access with your browser to https://localhost/Shibboleth.sso/Metadata. This URL should return the dynamically generated XML metadata of this Service Provider.
3.3 Prepare Logging
Check C:\opt\shibboleth-sp\var\log\shibboleth\, if the logfiles are created. If not check the permissions.
The Shibboleth daemon log (shibd.log) and the transaction log (transaction.log) are configured in the file C:\opt\shibboleth-sp\etc\shibboleth\shibd.logger:
According to the convention, the entityID should have the form of a URL. If the entityID is used as a URL (https://sp.example.org/shibboleth), this URL should return an entity's metadata. In order for this to work, the web server must be configured accordingly.
In IIS it is possible to create a folder shibboleth with the
following properties: (Credits to Mathias Rufer from UNINE)
Make sure to set all the SSLCertificateFiles to the right ones.
Use the status URL https://sp.example.org/Shibboleth.sso/Metadata for a quick test. This URL should return the dynamically generated XML metadata of this Service Provider.
AAI Resource Registry
In order to activate the Service Provider within the federation it is necessary to register it with the Resource Registry. After this procedure, the metadata of this Service Provider will be included in the federation metadata. Therefore, all AAI components will learn about this new Service Provider.
The purpose of the Resource Registry is to have an up-to date list of all Identity Providers and Service Providers in the SWITCHaai Federation.
(See the information about the Resource Registry) in order to generate federation metadata and various configuration files.
Log in with a SWITCHaai or AAI Test account. Use organisation account to get access. In case your organisation doesn't operate yet an AAI Identity Provider,
please ask aai@switch.ch for an account.
SWITCHaai accounts can also be used to manage AAI Test resources but not vice versa.
Click on the tab Resources
Click on Add a Resource Description
Click on Run Shibboleth 2.x wizard
Fill out all forms that are marked incomplete. Some forms do not need to be filled out completely.
After completing all sections (they should all be marked as 'optional' or 'ok'),
click on Submit for Approval.
A Resource Registration Authority administrator of your organization then has to approve the Resource Description in order to make it active. Only after this step, its description will be included in federation metadata.
6. Troubleshooting
6.1 Logfiles
If some of the above tests are unsuccessful, we recommend the following procedure:
Have a look at the logfiles. They can be found at the path set in the property log4j.appender.native_log.fileName
defined in C:\opt\shibboleth-sp\etc\shibboleth\native.logger and the path log4j.appender.shibd_log.fileName
set in
C:\opt\shibboleth-sp\etc\shibboleth\shibd.logger for WARN and ERROR messages.
Most probably C:\opt\shibboleth-sp\var\log\shibboleth\native.log and C:\opt\shibboleth-sp\var\log\shibboleth\shibd.log.
Set the log level (log4j.rootCategory) of C:\opt\shibboleth-sp\etc\shibboleth\native.logger and
C:\opt\shibboleth-sp\etc\shibboleth\shibd.logger to DEBUG.
Once the problem is solved, don't forget to set it back to WARN or INFO to prevent your log files from growing too big.
6.2 Common problems
Find below a list of common problems and possible solutions:
No log files are written
Check the permissions of the log files or the path for the log files set in C:\opt\shibboleth-sp\etc\shibboleth\native.logger
or C:\opt\shibboleth-sp\etc\shibboleth\shibd.logger . If shibd is not run as root user, you might have to adapt the owner of the log directory and files to the user that runs shibd.
No attributes/Certificates problems
Check the Apache SSL certificate with the https://tools.switch.ch/certchaintest/
to make sure the full certificate chain up to the root CA certificate is attached to your certificate.
Some good practices according Service Provider productionalization:
BEST CURRENT PRACTICES for operating a SWITCHaai Service Provider
The document describes best current practices for operating a Service Provider (SP) within the SWITCHaai federation in production use. It is meant to cover service management and operational related aspects as well as the technical infrastructure for successfully operating an SP.
Subscribe to the SWITCHaai mailing lists
Important information about the SWITCHaai federation are distributed
by the AAI-Operations mailing list.
Therefore the administrator of the Service Provider should
subscribe to the list.
News and announcements are sent by the
AAI-Announce mailing list.
You might subscribe to it as well.
Customizing error pages
The error pages and messages can be configured in
C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml: