This guide describes the installation & configuration of a
Shibboleth Sevice Provider (SP) 2.3.1
on a Debian GNU/Linux 5.0 from sources.
It covers the installation of the Shibboleth Webserver authentication module as
well as the Shibboleth daemon and its configuration for the SWITCHaai
federation.
For further information about Shibboleth Sevice Provider, take a look at the
references.
Assumption
Before starting to install Shibboleth Sevice Provider,
assure that the following prerequisites are met:
A proper certificate
For decrypting the assertions and/or provide an SSL connection to the
resource, a certificate is required.
Please refer to
http://www.switch.ch/aai/certificates/ for further information about
certificates.
You can use the same certificate for the SSL webserver connection and for Shibboleth
Service Provider.
It is also possible to create a self-signed certificate for communciation usage between the Shibboleth components.
If you need that opportunity, please follow the steps described below.
Before starting to build and configure the Shibboleth Sevice Provider, assure that the following prerequisites are met:
sudo
Allows to run commands as user with root privileges
Apache HTTP 2.2
sudo aptitude install apache2
For configuration, see at the Apache HTTP documentation in the references.
OpenSSL
For working with x509 certificates
sudo aptitude install openssl
NTP
Servers running Shibboleth must have their system time synchronized in order to avoid clock-skew errors:
sudo aptitude install ntp
Shibboleth build environment
Since the Shibboleth Service Provider is implemented in C/C++, some C/C++ build tools are needed:
sudo aptitude install gcc g++ make
The Shibboleth service provider is linked against some external libraries. The needed header files and libraries are:
sudo aptitude install libssl0.9.8 libssl-dev sudo aptitude install libcurl3 libcurl3-dev sudo aptitude install libxerces-c28 libxerces-c2-dev sudo aptitude install libxml-security-c14 libxml-security-c-dev sudo aptitude install apache2-threaded-dev
for f in $MYBUILD/*.tar.gz; do tar -xzvf $f -C $MYBUILD; done
3.2 Build
Define some required environment variables. Just adjust SHIB_HOME if the target directory is somewhere else:
export SHIB_HOME=/opt/shibboleth-sp-2.3.1/
Create the target directory:
sudo mkdir $SHIB_HOME
1. Log4Shib:
cd $MYBUILD/log4shib-1.0.4/
./configure --disable-static --disable-doxygen --prefix=$SHIB_HOME
make
sudo make install
2. XML-Tooling:
cd $MYBUILD/xmltooling-1.3.3/
./configure --with-log4shib=$SHIB_HOME --prefix=$SHIB_HOME -C
make
sudo make install
3. OpenSAML:
cd $MYBUILD/opensaml-2.3/
./configure --prefix=$SHIB_HOME --with-log4shib=$SHIB_HOME -C
make
sudo make install
4. Shibboleth Service Provider:
cd $MYBUILD/shibboleth-2.3.1/
./configure --with-saml=$SHIB_HOME --enable-apache-22 --with-log4shib=$SHIB_HOME --with-xmltooling=$SHIB_HOME --prefix=$SHIB_HOME -C
make
sudo make install
3.3 Define the current Shibboleth SP release
Symlink the current installation:
if [ -L /opt/shibboleth-sp2 ] ; then sudo rm /opt/shibboleth-sp2 ; fi;
sudo ln -sf $SHIB_HOME /opt/shibboleth-sp2
For creating a self signed certificate follow these steps:
cd /etc/shibboleth/
sudo sh /opt/shibboleth-sp-2.3.1/etc/shibboleth/keygen.sh -h sp.example.org -y 3 -e https://sp.example.org/shibboleth
4.2 Logging
The Shibboleth Apache module log is configured by /etc/shibboleth/native.logger
The Shibboleth daemon and the transaction log are configured by /etc/shibboleth/shibd.logger
For testing purposes, there is the status URL https://sp.example.org/Shibboleth.sso/Status,
which returns information about the setup as an XML response.
For accessing the status URL, the accessing host has to be enabled in /etc/shibboleth/shibboleth2.xml:
In order to activate your Service Provider within the federation you need to register it with the Resource Registry.
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).
Log in via SWITCHaai|AAITest. Use your 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.
Click on the tab Resource Administration
Click on Add a Resource Description
Click on Run Shibboleth 2.x assistant
Fill out all forms that are marked incomplete. Some forms do not need to be filled out completely.
After you have completed all sections (they should all be marked as 'optional' or 'ok'),
click on Submit for Approval.
A Resource Registration Authority administrator then has to approve the Resource Description in order to make it active.
Simple Test Resource
For a real test that shows if the Service Provider retrieves any attributes
from an Identity Provider,
you first must protect a resource,
e.g. https://sp.example.org/secure/.
This can be accomplished by adding
the following directives to the Apache site config,
e.g. /etc/apache2/sites-enabled/sp.example.org:
After restarting Apache, try to access: https://sp.example.org/secure/,
the authentication should be initiated and you should be redirected either to the WAYF
or to an Identity Provider.
Upon successful authentication, you will probably encounter a 404
(File not found) error, because there might be no /secure.
Anyway, if you can access
https://sp.example.org/Shibboleth.sso/Session
to get information about the session like the issuer (IdP) and released
attributes,
this proofs the proper operation of the Service Provider.
If more testing is needed, e.g. to get the values of the released attributes, add a simple PHP script into the secure/ directory, like that index.php:
This PHP script has to be placed in a Shibboleth protected directory (e.g. /secure from above).
If successfully authenticated and authorized, you should see some environment variables contain your user attributes.
6. Troubleshooting
6.1 Logfiles
If some of the above tests are not successful, we recommend to do the following:
Scan the logfiles. They can be found at the path set in the property log4j.appender.native_log.fileName
defined in /etc/shibboleth/native.logger and the path log4j.appender.shibd_log.fileName
set in
/etc/shibboleth/shibd.logger for WARN and ERROR messages.
Most probably /var/log/shibboleth/native.log and /var/log/shibboleth/shibd.log.
Check /var/log/apache2/error.log and /var/log/apache2/access.log
Set the log level (log4j.rootCategory) of /etc/shibboleth/native.logger and
/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
Following is a list of common problems that you may check:
No log files are written
Check the permissions of the log files or the path for the log files set in /etc/shibboleth/native.logger
or /etc/shibboleth/shibd.logger .
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
/etc/shibboleth/shibboleth2.xml: