This guide describes the installation & configuration of a Shibboleth Sevice Provider (SP) 2.0 on a Debian GNU/Linux 4.0
It covers the installation of the Shibboleth Apache HTTP authentication module as well as the Shibboleth daemon and its configuration for the SWITCHaai federation.
The example values used in this guide are:
www.example.org
The DNS name of the resource (Service Provider).
https://www.example.org/shibboleth
The provider Id of the Service Provider.
For further information about Shibboleth Sevice Provider, take a look at the references.
2. Prerequisites
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 apt-get install apache2
For configuration, see at the Apache HTTP documentation in the references.
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 Apache mod-ssl and for Shibboleth Service Provider.
OpenSSL
For working with x509 certificates
sudo apt-get install openssl
NTP
Servers running Shibboleth must have their system time synchronized in order to avoid clock-skew errors:
sudo apt-get install ntp
Shibboleth build environment
Since the Shibboleth Service Provider is implemented in C/C++, some C/C++ build tools are needed:
sudo apt-get install gcc g++ make
The Shibboleth service provider is linked against some external libraries. The needed header files and libraries are:
sudo apt-get install libssl0.9.8 libssl-dev sudo apt-get install libcurl3 libcurl3-dev sudo apt-get install apache2-threaded-dev
cd $MYBUILD/log4shib-1.0/
./configure --disable-static --disable-doxygen --prefix=$SHIB_HOME
make
sudo make install
2. XercesC:
cd $MYBUILD/xerces-c-src_2_8_0/src/xercesc/
./runConfigure -p linux -r pthread -P $SHIB_HOME
make
sudo env XERCESCROOT=$XERCESCROOT make install
3. XML-Security:
cd $MYBUILD/xml-security-c-1.4.0
./configure --without-xalan --prefix=$SHIB_HOME
make
sudo env XERCESCROOT=$XERCESCROOT make install
4. XML-Tooling:
cd $MYBUILD/xmltooling-1.0/
./configure --with-log4shib=$SHIB_HOME --prefix=$SHIB_HOME -C
make
sudo make install
5. OpenSAML:
cd $MYBUILD/opensaml-2.0/
./configure --prefix=$SHIB_HOME --with-log4shib=$SHIB_HOME -C
make
sudo make install
6. Shibboleth Service Provider:
cd $MYBUILD/shibboleth-2.0/
./configure --with-saml=$SHIB_HOME --enable-apache-22 --with-log4shib=$SHIB_HOME --prefix=$SHIB_HOME -C
make
sudo make install
# Global Configuration
# This is the XML file that contains all the global, non-apache-specific
# configuration. Look at this file for most of your configuration parameters.
ShibConfig /etc/shibboleth2/shibboleth2.xml
# Used for example logo and style sheet in error templates.
<IfModule mod_alias.c>
<Location /shibboleth-sp>
Allow from all
</Location>
Alias /shibboleth-sp/main.css /opt/shibboleth-sp2/share/doc/shibboleth/main.css
Alias /shibboleth-sp/logo.jpg /opt/shibboleth-sp2/share/doc/shibboleth/logo.jpg
</IfModule>
Adjust the Apache configuration /etc/apache2/envvars:
...
...
# This file is generated from envvars-std.in
#
export LD_LIBRARY_PATH=/opt/shibboleth-sp2/lib
The Shibboleth Apache module log is configured by /etc/shibboleth2/native.logger
The Shibboleth daemon and the transaction log are configured by /etc/shibboleth2/shibd.logger
4.2 Shibboleth service provider
The main configuration of the Shibboleth Service Provider is done in /etc/shibboleth2/shibboleth2.xml
Adjust the custom values. Take the appropiate values for the resource configuration within the
production federation (SWICTHaai)
or the test federation (AAI Test).
Download the attribute map, where the attribute definition and its map to the HTTP-Header names are done:
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.0 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.
For testing purposes, there is the status URL https://www.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/shibboleth2/shibboleth2.xml:
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://www.example.org/secure/. This can be accomplished by adding
the following directives to the Apache site config, e.g. /etc/apache2/sites-enabled/www.example.org:
After restarting Apache, try to access: https://www.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://www.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/shibboleth2/native.logger and the path log4j.appender.shibd_log.fileName set in /etc/shibboleth2/shibd.logger for WARN and ERROR messages.
Check /var/log/apache2/error.log and /var/log/apache2/access.log
Set the log level (log4j.rootCategory) of /etc/shibboleth2/native.logger and /etc/shibboleth2/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/shibboleth2/native.logger or /etc/shibboleth2/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.