Install Shibboleth Service Provider 1.3 on Debian 3.1 (sarge)

Authors: Brusten Philip & Van der Velpen Jan
Last modified: Tuesday, 27-Mar-2007 11:32:01 CEST
based on: http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/sp/install-sp-1.3-debian.html

Introduction
Prerequisites
Shibboleth SP 1.3 installation
- Using Debian packages
- Compiling from source
SSL certificates
Shibboleth SP 1.3 initial configuration
Apache configuration

Apache startup scripts
Apache 1.3 configuration
Apache 2.0 configuration

Firewall settings
K.U.Leuven Shibboleth registry

Introduction

This guide describes Debian specific installation of a Shibboleth Service Provider 1.3 and its configuration for the KULeuven Federation. It covers installation on Debian GNU/Linux 3.1 (Sarge) with Apache 1.3.

In-depth information can be found at the Shibboleth Wiki from Internet2. Please also read the document Shibboleth from an application's point of view: "Shibboleth... a new way of thinking" before you start your installation of the Shibboleth SP software.

The Shibboleth Service Provider (SP) 1.3 is implemented in C/C++ as an Apache authentication module mod_shib and a separate daemon shibd.

The example values used in this guide are:

SUBDOMAIN.kuleuven.be: The DNS name of the Resource (Service Provider).

Prerequisites

As indicated in the title, this guide applies to Debian 3.1 (sarge) and contains some references to Debian specific tools.

Apache + mod_ssl: Recommended Apache version >= 1.3.33, Debian Package: apache
Recommended mod_ssl version >= 2.8.22, Debian Package: libapache-mod-ssl
Apache webserver will use mod_ssl to handle HTTPS connections.
or Apache-ssl version >=1.3.33 (uses Ben-ssl which is a little less compatible with mod_shib), Debian Package: apache-ssl: This version needs some unusual tweaking for SSL to work correctly with mod_shib. (This is explained in the example configuration files)
or Apache2: Debian package: apache2-mpm-worker. The hybrid multiprocess/multithreaded worker mpm is preferred because else Apache2 has to load all (Shibboleth) configuration data for each request. (see http://httpd.apache.org/docs/2.0/mpm.html). However you will need to use the prefork if you are using Apache modules that cannot handle multithreading properly (like mod_phpX when not using cgi; see http://be.php.net/manual/en/faq.installation.php#faq.installation.apache2).
OpenSSL: Recommended Version >= 0.9.7, Debian Package: openssl
The OpenSSL tools will be used to handle server certificates.
NTP: Debian Package: ntp-server (or any other package which provides time-synchronization)
Servers running Shibboleth should have their system time synchronized in order to avoid clock-skews. Check if your server is synchronizing correctly. An NTP query from a client (like our server) is performed on a remote NTP-server that runs on port 123.

Installation of Shibboleth SP 1.3

Using debian packages

We have provided some precompiled debian packages needed for the installation of Shibboleth Service Provider 1.3.
You can easily install them using apt-get.
You must add our Debian repository to your source list of apt: /etc/apt/sources.list

...
deb http://shib.kuleuven.be/debian-repository binary/
...

(note: For now this repository can only be accessed from inside the KULeuven network.)

This repository contains 6 packages:

liblog4cpp: A C++ library for flexible logging
libxerces26-shib: Xerces-C++ is a validating XML parser written in C++
libxmlsecurity: An implementation of the XML Digital Signature specification
libopensaml: An implementation of the Security Assertion Markup Language Specification
shibboleth-sp: Shibboleth service provider with Apache modules
shibboleth-sp-kul: Contains Shibboleth SP configuration files adapted for K.U.Leuven (shibboleth.xml, AAP.xml, *.logger, metadata.*.xml)

After you added our repository you must update your package list:

root# apt-get update

You can query a package for more info (version, description, dependencies, ...) :

root# apt-cache query <package name>

You can install the packages separately or just install the latest package in the dependency hierarchie. All dependencies on that latest package will be resolved automatically.

root# apt-get install shibboleth-sp-kul

These debian packages will be maintained so they will be updated when there are new updates available. You can run these updates with the following commands:

root# apt-get update
root# apt-get upgrade

Once you installed Shibboleth Service Provider you only need to take a look at the following sections: SSL certificates, Shibboleth SP 1.3 initial configuration, Firewall settings, K.U.Leuven Shibboleth registry.

Compiling from source

The installation from source you must compile the Shibboleth Service Provider 1.3 and some libraries. Therefore, you need to install the necessary building tools and development libraries on your compile host.

The Shibboleth SP 1.3 will be installed under: /usr/local/shib-sp

root# export SHIB_HOME=/usr/local/shib-sp

You may also include the following lines in /etc/profile:

SHIB_HOME=/usr/local/shib-sp
export SHIB_HOME

Debian C/C++ Compilers and Building Tools

Building the required libraries and the Shibboleth SP 1.3 require at least the gcc 3.0 compiler. The GNU make building tool is also required.

The default Debian 3.1 compiler is gcc/g++ version 3.3.5. This compiler have been used to build all official Debian packages, therefore, it is highly recommended to use this default compiler.

Use apt-get to install the gcc, g++ and make packages:

root# apt-get install gcc g++ make
...

Installing these packages will also install a lot of other dependent packages.

Install OpenSSL library

OpenSSL is a toolkit implementing the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) protocols as well as a full-strength general purpose cryptography library.

The default Debian 3.1 OpenSSL library is version 0.9.7, this library meets the requirement of Shibboleth SP 1.3. You must also install the development package to be able to compile the further required libraries.

Use apt-get to install the libssl 0.9.7 and the libssl development packages:

root# apt-get install libssl0.9.7 libssl-dev
...

Installing these packages will also install a lot of other dependent packages.

Install libcurl library

cURL is a tool for transferring files with URL syntax, supporting HTTPS certificates, HTTP POST, HTTP PUT, FTP uploading, kerberos, HTTP form based upload, proxies, cookies, user+password authentication, file transfer resume, http proxy tunneling and a busload of other useful tricks. Project homepage: http://curl.haxx.se/libcurl

The libcurl 7.14.0 is the preferred version to build Shibboleth SP 1.3. But any version from about 7.11.1 on will work.

As the default Debian 3.1 libcurl is version 7.13.2, this library meets the requirement of Shibboleth SP 1.3. You must also install the development package to be able to compile the further required libraries.

Use apt-get to install the libcurl 7.13.2 and the libcurl development packages:

root# apt-get install libcurl3 libcurl3-dev
...

Installing these packages could also install other dependent packages.

Build and Install log4cpp library

Log4cpp is an opensource library of C++ classes for flexible logging to files, syslog, IDSA and other destinations. It is modeled after the Log4j Java library, staying as close to their API as is reasonable. Project homepage: http://log4cpp.sourceforge.net/

Note: Unfortunately this project is in a limbo state and pending future decisions, Internet2's Shibboleth Project is using a snapshot release. With this latest snapshot, scripts have been fixed on the supported platforms and some bug fixes have been added.

Shibboleth SP 1.3 requires the special library log4cpp version 0.3.5rc1 available from Internet2.

To build and install the log4cpp library:

user$ wget http://shibboleth.internet2.edu/downloads/log4cpp-0.3.5rc1.tar.gz
...
user$ tar xvzf log4cpp-0.3.5rc1.tar.gz
...
user$ cd log4cpp-0.3.5rc1
user$ ./configure --prefix=$SHIB_HOME --disable-static --disable-doxygen
...
user$ make
...
user$ make install
...

make install will install the log4cpp shared library in /usr/local/shib-sp. Therefore, you must have write access to this directory.

Build and Install Xerces-C++ library

Xerces-C++ is an opensource validating XML parser written in a portable subset of C++. Xerces-C++ makes it easy to give your application the ability to read and write XML data. Project homepage: http://xml.apache.org/xerces-c/

Note: As the latest version 2.6 of Xerces-C++ is incompatible with Shibboleth, a special 2.6.1 release of Xerces-C++ with fixes applied has been created by the Internet2's Shibboleth Project for use with OpenSAML and Shibboleth. The OpenSAML configure script will detect and block the use of 2.6.0. For the most part, any prior version since 2.3.0 should also work.

Shibboleth SP 1.3 requires the special library Xerces-C++ version 2.6.1 available from Internet2.
Make sure you set the environment variable XERCESCROOT (don't forget the C) as appropriate.

To build and install the Xerces-C++ library:

user$ wget http://shibboleth.internet2.edu/downloads/xerces-c-src_2_6_1.tar.gz
...
user$ tar xvzf xerces-c-src_2_6_1.tar.gz
...
user$ cd xerces-c-src_2_6_1
user$ export XERCESCROOT=`pwd`
user$
user$ cd src/xercesc
user$ ./runConfigure -p linux -c gcc -x g++ -r pthread -P $SHIB_HOME
...
user$ make
...
user$ make install
...

The Xerces-C++ shared library is now installed in /usr/local/shib-sp

Build and install XML-security C++ library

The XML Security C++ library is an opensource implementation of the XML Digital Signature specification. Project homepage: http://xml.apache.org/security/

Shibboleth SP 1.3 requires version 1.2.1 of the XML Security library.
You'll also need to set the XERCESCROOT environment variable as before.

To build and install the XML-Security C++ library:

user$ export XERCESCROOT=`pwd`/xerces-c-src_2_6_1
user$
user$ wget http://xml.apache.org/dist/security/c-library/xml-security-c-1.2.1.tar.gz
...
user$ tar xvzf xml-security-c-1.2.1.tar.gz
...
user$ cd xml-security-c-1.2.1/src
user$ ./configure --prefix=$SHIB_HOME --without-xalan
...
user$ make
...
user$ make install
...

The XML-Security shared library is now installed in /usr/local/shib-sp

Build and install OpenSAML library

SAML (Security Assertion Markup Language) is a standard for the formation and exchange of authentication, attribute, and authorization data as XML. OpenSAML is an opensource library which can be used to build, transport, and parse SAML 1.0 and 1.1 messages. It is able to store the individual information fields that make up a SAML message, build the correct XML representation, and parse XML back into the individual fields before handing it off to a recipient. OpenSAML supports the SOAP binding for the exchange of SAML request and response objects. Project homepage: http://www.opensaml.org/

The OpenSAML 1.1a library is required by Shibboleth SP 1.3.

To build and install the OpenSAML library:

user$ wget http://shibboleth.internet2.edu/downloads/opensaml-1.1a.tar.gz
...
user$ tar xvzf opensaml-1.1a.tar.gz
...
user$ cd opensaml-1.1
user$ ./configure --prefix=$SHIB_HOME --with-log4cpp=$SHIB_HOME -C
...
user$ make
...
user$ make install
...

The OpenSAML shared library is now installed in /usr/local/shib-sp

Build and install Shibboleth SP 1.3

The Shibboleth SP 1.3 is an Apache dynamic loadable module. Therefore, it must be linked against Apache server and requires the Apache apxs or Apache2 apxs2 tool as well as the Apache header files.

Apache development packages

If you have installed the default Debian Apache 1.3 web server, then install the development package containing apxs and the Apache header files.

Use apt-get to install the Apache 1.3 development package:
```
root# apt-get install apache-dev
...
```
If you have installed the Debian Apache 2.0 web server, then install the development package containing apxs2 and the Apache2 header files.
Use apt-get to install the Apache2 development package: (if you use a prefork apache2 you need to replace apache2-threaded-dev with apache2-prefork-dev)
```
root# apt-get install apache2-threaded-dev
...
```

Installing these packages will also install a lot of other dependent packages.

Shibboleth SP 1.3

Building the Shibboleth daemon shibd, the Apache modules, and the shared libraries is more or less like building OpenSAML.

If you have installed the Apache2 web server, then add the option --enable-apache-20 --with-apxs2=/usr/bin/apxs2 to the configure script.

To build and install the Shibboleth Service Provider:

user$ wget http://shibboleth.internet2.edu/downloads/shibboleth-sp-1.3a.tar.gz
...
user$ tar xvzf shibboleth-sp-1.3a.tar.gz
...
user$ cd shibboleth-1.3
user$ ./configure --prefix=$SHIB_HOME --with-log4cpp=$SHIB_HOME \
 [Apache1.3] --enable-apache-13 --with-apxs=/usr/bin/apxs \
 [Apache2.0] --enable-apache-20 --with-apxs2=/usr/bin/apxs2 \
             --disable-mysql
...
user$ make
...
user$ make install
...

The Shibboleth Service Provider (Shibboleth Daemon, Apache module, libraries, ... ) is now fully installed under /usr/local/shib-sp

SSL certificates

This section briefly mentions the needed steps to get a server certificate.

Generate certificate

Generate an unencrypted private key in PEM format (default AES-256):
```
$ openssl genrsa -out /etc/pki/SUBDOMAIN.kuleuven.be.key 1024
```

Create a Certificate Signing Request (CSR):

$ openssl req -new -key /etc/pki/SUBDOMAIN.kuleuven.be.key -out /etc/pki/SUBDOMAIN.kuleuven.be.csr

Members of the K.U.Leuven can post their CSR at https://certificates.kuleuven.be. The certificate will be signed by "Cybertrust Educational CA" http://secure.globalsign.net/cacert/sureserverEDU.pem.
Wait for a reply with your new public certificate. That will take some time (typically a day or two). When you receive it, save the signed certificate to /etc/pki/SUBDOMAIN.kuleuven.be.crt.

Shibboleth SP 1.3 initial configuration

Debian Directories

(note: you can skip this section when you have installed Shibboleth SP with the debian packages)

On Debian, all the system configuration files are stored in the directory /etc. Create a symbolic link to ease the Shibboleth configuration.

root# ln -s /usr/local/shib-sp/etc/shibboleth /etc/shibboleth

The /var/log/shibboleth logging directory doesn't exist yet so you have to create it yourself. Note that you can specify the logging directories in the.logger files. We chose to log directly to the directory at /var/log because you might have created another partition for the logs, and so symlinking from the Shibboleth home would not be great in that case.
The logger takes care of rotating the logfiles when necessary by itself. Only the root user has to read/write to this main directory.

root# mkdir /var/log/shibboleth

Because the Shibboleth Apache module runs as the www-data user on Debian, you have to grant this user write access to a logging directory. It is wise to choose another directory for this. You should also create this directory and set the correct permissions for it.

root# mkdir /var/log/shibboleth/httpd
root# chown www-data /var/log/shibboleth/httpd

Key and Certificate

Make sure the permissions are set correctly. Only the user running Apache must be able to read the private key. Other users don't need to access the key file, so setting the correct ownership and access permissions is highly recommended.

shibboleth.xml

Download the shibboleth.xml file and save it as /etc/shibboleth/shibboleth.xml . This is the main configuration file for the Service Provider and is already preconfigured for the KULeuven federation.

Edit the /etc/shibboleth/shibboleth.xml file and configure your SP 1.3:

providerId: This is the unique identifier of your resource within the federation. Its value should be 'stable'. It should not change. For the "default" application you should choose the hostname (though this is not necessary for Shibboleth to work). When a more specific application is added later, you should choose the full URL for that application.
Set it to https://SUBDOMAIN.kuleuven.be
Replace every other entries with the correct values.

<SPConfig xmlns="urn:mace:shibboleth:target:config:1.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="urn:mace:shibboleth:target:config:1.0 shibboleth-targetconfig-1.0.xsd"
   clockSkew="180"
   logger="/etc/shibboleth/shibboleth.logger">

	<!-- These extensions are "universal", loaded by all Shibboleth-aware processes. -->
	<Extensions>
		<Library path="/usr/local/shib-sp/libexec/xmlproviders.so" fatal="true"/>
	</Extensions>

	<!-- The Global section pertains to shared Shibboleth processes like the shibd daemon. -->
	<Global logger="/etc/shibboleth/shibd.logger">

		 <!-- Only one listener can be defined. -->
		<UnixListener address="/var/run/shibd.sock"/>
		 <!--
		See deploy guide for details, but:
			cacheTimeout - how long before expired sessions are purged from the cache
			AATimeout - how long to wait for an AA to respond
			AAConnectTimeout - how long to wait while connecting to an AA
			defaultLifetime - if attributes come back without guidance, how long should they last?
			strictValidity - if we have expired attrs, and can't get new ones, keep using them?
			propagateErrors - suppress errors while getting attrs or let user see them?
			retryInterval - if propagateErrors is false and query fails, how long to wait before trying again

		Only one session cache can be defined.
		-->
		<MemorySessionCache cleanupInterval="300" cacheTimeout="3600"
		   AATimeout="30" AAConnectTimeout="15"
		   defaultLifetime="1800" retryInterval="300"
		   strictValidity="false" propagateErrors="false"/>
	</Global>

	<!-- The Local section pertains to resource-serving processes (often process pools) like web servers. -->
	<Local logger="/etc/shibboleth/native.logger" localRelayState="true">
		<!--
		To customize behavior, map hostnames and path components to applicationId and other settings.
		The following provider types are available with the delivered code:
		type="edu.internet2.middleware.shibboleth.sp.provider.NativeRequestMapProvider"

		- Web-server-specific plugin that allows native commands (like Apache's
		ShibRequireSession) to override or supplement the XML syntax. The Apache
		version also supplies an htaccess authz plugin for all content.

		type="edu.internet2.middleware.shibboleth.sp.provider.XMLRequestMapProvider"
		- portable plugin that does not support the older Apache-specific commands and works
		the same on all web platforms, this plugin does NOT support htaccess files
		for authz unless you also place an <htaccess/> element somewhere in the map

		By default, the "native" plugin (the first one above) is used, since it matches older
		behavior on both Apache and IIS.
		-->
		<RequestMapProvider type="edu.internet2.middleware.shibboleth.sp.provider.NativeRequestMapProvider">
			<RequestMap applicationId="default">
				<!--
				This requires a session for documents in /secure on the containing host with http and
				https on the default ports. Note that the name and port in the <Host> elements MUST match
				Apache's ServerName and Port directives or the IIS Site name in the <ISAPI> element
				below.
				-->
				<Host name="SUBDOMAIN.kuleuven.be">
					<Path name="secure" authType="shibboleth" requireSession="true" exportAssertion="true">
						<!-- Example shows a subfolder on the SSL port assigned to a separate <Application> -->
						<!-- <Path name="admin" applicationId="foo-admin"/> -->
					</Path>
				</Host>
			</RequestMap>
		</RequestMapProvider>
	</Local>
	 <!--
	The Applications section is where most of Shibboleth's SAML bits are defined.
	Resource requests are mapped in the Local section into an applicationId that
	points into to this section.
	-->
	<Applications id="default"
	  providerId="https://SUBDOMAIN.kuleuven.be"
	  homeURL="https://SUBDOMAIN.kuleuven.be/"
	  xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
	  xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">

		<!--
		Controls session lifetimes, address checks, cookie handling, and the protocol handlers.
		You MUST supply an effectively unique handlerURL value for each of your applications.
		The value can be a relative path, a URL with no hostname (https:///path) or a full URL.
		The system can compute a relative value based on the virtual host. Using handlerSSL="true"
		will force the protocol to be https. You should also add a cookieProps setting of "; secure"
		in that case. Note that while we default checkAddress to "false", this has a negative
		impact on the security of the SP. Stealing cookies/sessions is much easier with this
		disabled.
		-->
		<Sessions lifetime="7200" timeout="3600" checkAddress="false"
		   handlerURL="/Shibboleth.sso" handlerSSL="true"
		   idpHistory="true" idpHistoryDays="7">
			 <!--
 			SessionInitiators handle session requests and relay them to a WAYF or directly
			to an IdP, if possible. Automatic session setup will use the default or first
			element (or requireSessionWith can specify a specific id to use). Lazy sessions
			can be started with any initiator by redirecting to it. The only Binding supported
			is the "urn:mace:shibboleth:sp:1.3:SessionInit" lazy session profile using query
			string parameters:
			  * target the resource to direct back to later (or homeURL will be used)
	 		  * acsIndex optional index of an ACS to use on the way back in
			  * providerId optional direct invocation of a specific IdP
			-->

			<!-- This default example directs users to a specific IdP's SSO service. -->
			<SessionInitiator id="kuleuven" isDefault="true"
			   Location="/WAYF/kuleuven"
			   Binding="urn:mace:shibboleth:sp:1.3:SessionInit"
			   wayfURL="https://idp.kuleuven.be/shibboleth-idp/SSO"
			   wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest"/>
	
			<!-- This example directs users to a specific federation's WAYF service. -->
			<!--
			<SessionInitiator id="kulassoc" isDefault="true"
			   Location="/WAYF/kulassoc"
			   Binding="urn:mace:shibboleth:sp:1.3:SessionInit"
			   wayfURL="https://wayf.associatie.kuleuven.be/shibboleth-wayf/WAYF"
			   wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest"/>
			-->
			<!--
			md:AssertionConsumerService elements replace the old shireURL function with an
			explicit handler for particular profiles, such as SAML 1.1 POST or Artifact.
			The isDefault and index attributes are used when sessions are initiated
			to determine how to tell the IdP where and how to return the response.
			-->
			<md:AssertionConsumerService Location="/SAML/POST" index="1" isDefault="true"
			   Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post"/>
			<md:AssertionConsumerService Location="/SAML/Artifact" index="2"
			   Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01"/>
			 <!--
			md:SingleLogoutService elements are mostly a placeholder for 2.0, but a simple
			cookie-clearing option with a ResponseLocation or a return URL parameter is
			supported via the "urn:mace:shibboleth:sp:1.3:Logout" Binding value.
			-->
			<md:SingleLogoutService Location="/Logout"
			   Binding="urn:mace:shibboleth:sp:1.3:Logout"/>
		</Sessions>
		 <!--
		You should customize these pages! You can add attributes with values that can be plugged
		into your templates. You can remove the access attribute to cause the module to return a
		standard 403 Forbidden error code if authorization fails, and then customize that condition
		using your web server.
		-->
		<Errors session="/etc/shibboleth/sessionError.html"
		   metadata="/etc/shibboleth/metadataError.html"
		   rm="/etc/shibboleth/rmError.html"
		   access="/etc/shibboleth/accessError.html"
		   supportContact="root@localhost"
		   logoLocation="/shibboleth-sp/logo.jpg"
		   styleSheet="/shibboleth-sp/main.css"/>

		<!-- Indicates what credentials to use when communicating -->
		<CredentialUse TLS="cred4kuleuven" Signing="cred4kuleuven">
		</CredentialUse>
		<!-- AAP can be inline or in a separate file -->
		<AAPProvider type="edu.internet2.middleware.shibboleth.aap.provider.XMLAAP"
		   uri="/etc/shibboleth/AAP.xml"/>

		<!-- KULeuven federation metadata -->
		<MetadataProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata"
		   uri="/etc/shibboleth/metadata.xml"/>

		<!-- The standard trust provider supports SAMLv2 metadata with path validation extensions. -->
		<TrustProvider type="edu.internet2.middleware.shibboleth.common.provider.ShibbolethTrust"/>
		 <!--
		Zero or more SAML Audience condition matches (mainly for Shib 1.1 compatibility).
		If you get "policy mismatch errors, you probably need to supply metadata about
		your SP to the IdP if it's running 1.2. Adding an element here is only a partial fix.
		-->
		<!-- KULeuven federation -->
		<saml:Audience>urn:mace:kuleuven.be:kuleuven</saml:Audience>

		<!-- KULassociatie federation -->
		<!--<saml:Audience>urn:mace:kuleuven.be:kulassoc</saml:Audience>-->
		 <!--
		You can customize behavior of specific applications here. The default elements inside the
		outer <Applications> element generally have to be overridden in an all or nothing fashion.
		That is, if you supply a <Sessions> or <Errors> override, you MUST include all attributes
		you want to apply, as they will not be inherited. Similarly, if you specify an element such as
		<MetadataProvider>, it is not additive with the defaults, but replaces them.

		Note that each application must have a handlerURL that maps uniquely to it and no other
		application in the <RequestMap>. Otherwise no sessions will reach the application.
		If each application lives on its own vhost, then a single handler at "/Shibboleth.sso"
		is sufficient, since the hostname will distinguish the application.

		The example below shows a special application that requires use of SSL when establishing
		sessions, restricts the session cookie to SSL and a specific folder, and inherits most other
		behavior except that it requests only EPPN from the origin instead of asking for all attributes.
		Note that it will inherit all of the handler endpoints defined for the default application
		but will append them to the handlerURL defined here.
		-->
		<!--
		<Application id="foo-admin">
			<Sessions lifetime="7200" timeout="3600" checkAddress="true"
			   handlerURL="/secure/admin/Shibboleth.sso" handlerSSL="true"
			   cookieProps="; path=/secure/admin; secure"/>
			<saml:AttributeDesignator AttributeName="urn:mace:dir:attribute-def:eduPersonPrincipalName"
			   AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri"/>
		</Application>
		-->
	</Applications>
 
	<!-- Define all the private keys and certificates here that you reference from <CredentialUse>. -->
	<CredentialsProvider type="edu.internet2.middleware.shibboleth.common.Credentials">
		<Credentials xmlns="urn:mace:shibboleth:credentials:1.0">
			<FileResolver Id="cred4kuleuven">
				<Key>
					<Path>/etc/pki/SUBDOMAIN.kuleuven.be.key</Path>
				</Key>

				<Certificate>
				<!-- Certificate and the whole chain -->
					<Path>/etc/pki/SUBDOMAIN.kuleuven.be.crt</Path>
				</Certificate>
			</FileResolver>

		</Credentials>
	</CredentialsProvider>

	<!-- Specialized attribute handling for cases with complex syntax. -->
	<AttributeFactory AttributeName="urn:oid:1.3.6.1.4.1.5923.1.1.1.10"
	   type="edu.internet2.middleware.shibboleth.common.provider.TargetedIDFactory"/>

</SPConfig>

AAP.xml

You can download our default Attribute Acceptance Policy file AAP.xml and save it as /etc/shibboleth/AAP.xml.

This file implements the (K.U.Leuven) attribute specifications and maps each Shibboleth attribute to a HTTP header and a so called "alias".

Federation Metadata

Metadata on an SP describes every IdP that can be used to access this resource. So every time there is a new IdP, you need to update the metadata of all involved SP's.

We have provided a metadata file that contains all IdPs of the Federation Associatie K.U.Leuven. We have commented out all IdPs except the IdP of the K.U.Leuven. If you want to add another IdP to your trust, just uncomment his entry. The metadata file can be downloaded from metadata.xml, please save it as /etc/shibboleth/metadata.xml.

Loggers Configuration

Download the loggers configuration files shibboleth.logger, native.logger and shibd.logger and save them in /etc/shibboleth directory.

The Shibboleth SP will log in the /var/log/shibboleth directory. The apache user (typically www-data) must have write permission on this folder because the apache module mod_shib will write to native.log in this directory.

Shibboleth Daemon Startup Script

The Shibboleth SP 1.3 daemon shibd must run in parallel with Apache.

Download the Debian shibd startup script and save it in the /etc/init.d directory.
Content of file: /etc/init.d/shibd

#! /bin/sh
#
# /etc/init.d/shibd for Debian
#
# start/stop script for Shibboleth ServiceProvider 1.3 daemon
#
# Created: 20050602 - Valery Tschopp - SWITCH
# Adapted for KULeuven (20050920)
#
# HOWTO INSTALL:
# root:/etc/init.d# update-rc.d shibd defaults 

PATH=/bin:/usr/bin:/sbin:/usr/sbin

#
# Shibboleth 1.3
#
SHIB_HOME=/usr/local/shib-sp
SHIB_ETC=$SHIB_HOME/etc/shibboleth

SHIB_CONFIG=$SHIB_ETC/shibboleth.xml

LD_LIBRARY_PATH=$SHIB_HOME/lib

DAEMON=$SHIB_HOME/sbin/shibd
NAME=shibd
DESC="Shibboleth 1.3 Daemon"

test -x $DAEMON || exit 0

set -e

case "$1" in
 start)
	echo -n "Starting $DESC: $NAME"
	start-stop-daemon --start --quiet --pidfile /var/run/$NAME.pid \
	--background --make-pidfile \
	--exec $DAEMON -- -fc $SHIB_CONFIG
	echo "."
	;;
 stop)
	echo -n "Stopping $DESC: $NAME"
	start-stop-daemon --stop --quiet --pidfile /var/run/$NAME.pid \
	--exec $DAEMON
	echo "."
	;;
 restart)
	# Restart
	$0 stop
	sleep 1
	$0 start
	;;
 configtest)
	echo "Check config for $DESC: $NAME"
	start-stop-daemon --start \
	--exec $DAEMON -- -tc $SHIB_CONFIG
	echo "Done."
	;;
 *)
	N=/etc/init.d/$NAME
	# echo "Usage: $N {start|stop|restart|reload|force-reload}" >&2
	echo "Usage: $N {start|stop|restart|configtest}" >&2

	exit 1
	;;
esac

exit 0

Use the Debian update-rc.d tool to register the /etc/init.d/shibd script as a system startup script:

root# update-rc.d shibd defaults 20 95
 Adding system startup for /etc/init.d/shibd ...
 /etc/rc0.d/K20shibd -> ../init.d/shibd
 /etc/rc1.d/K20shibd -> ../init.d/shibd
 /etc/rc6.d/K20shibd -> ../init.d/shibd
 /etc/rc2.d/S20shibd -> ../init.d/shibd
 /etc/rc3.d/S20shibd -> ../init.d/shibd
 /etc/rc4.d/S20shibd -> ../init.d/shibd
 /etc/rc5.d/S20shibd -> ../init.d/shibd

The Shibboleth daemon should be started before the webserver loads the module. If the daemon is not running the server will start up successfully, but all Shibboleth requests will display an error until the daemon is running.
You can check the Shibboleth configuration with the Shibboleth daemon. It is wise to do so before restarting your webserver if you are installing in a production environment:

root# /usr/local/shib-sp/sbin/shibd -t
overall configuration is loadable, check console for non-fatal problems
shibd shutdown complete

You can also run shibd in console mode like the output advises to check:

root# /usr/local/shib-sp/sbin/shibd
loading new logging configuration from /etc/shibboleth/shibd.logger
New logging configuration loaded, check log destination for process status...

(press ctrl-c to exit the daemon process)

Finally start the Shibboleth 1.3 daemon as a background process with the init script:

root# /etc/init.d/shibd start
Starting Shibboleth 1.3 Daemon: shibd.

Apache configuration

The Shibboleth module for Apache is a loadable DSO module that is built using apxs. The module provides the necessary directives to make it configurable from the main Apache configuration. Some of these directives can also be used in .htaccess files.

To make Shibboleth work for the Apache webserver, it should load this module and configure it correctly. This chapter describes how you can make that happen for Apache 1.3 and Apache 2.0 .

Apache startup scripts

The adjustments described in this chapter may not be necessary. These changes help the module to find its shared libraries at runtime. After compiling, the binaries will contain the correct paths so these aren't really necessary then (--rpath is used). As an alternative to the solution in this guide, you can also consider editing /etc/ld.so.conf (and running ldconfig) to make these settings system-wide. This solution solves everything for Apache. (note that the shibd also sets the LD_LIBRARY_PATH)

On Debian the Apache 1.3 webserver is started with the /etc/init.d/apache script.
The Apache-SSL 1.3 webserver is started with /etc/init.d/apache-ssl.
Apache 2.0 is started with /etc/init.d/apache2.
Your startup script(s) should be modified as shown below (only the highlighted lines need to be added/edited):

#!/bin/bash
#
# apache Start the apache HTTP server.
#
# The variables below are NOT to be changed. They are there to make the
# script more readable.

NAME=apache
DAEMON=/usr/sbin/$NAME
PIDFILE=/var/run/$NAME.pid
CONF=/etc/$NAME/httpd.conf
APACHECTL=/usr/sbin/${NAME}ctl
# note: SSD is required only at startup of the daemon.
SSD=`which start-stop-daemon`
ENV="env -i LANG=C PATH=/bin:/usr/bin:/usr/local/bin"

SHIB_HOME=/usr/local/shib-sp
LD_LIBRARY_PATH=${SHIB_HOME}/libexec:${SHIB_HOME}/lib
export LD_LIBRARY_PATH
...

It is not necessary to restart the webserver after these adjustements. You will restart it after modifying its configuration, which you can now do safely.

Apache 1.3 Configuration

General, non-Debian-specific instructions for apache httpd v1.3 (see below if you want to use the Debian scripts):

You can use the LoadModule directive in Apache's main configuration file to load the Shibboleth module for Apache, as shown below. Note that loading the module HAS to be done AFTER the ClearModuleList directive. The Shibboleth project advises you to append this configuration to the end of your main Apache configuration. You can also consider using the Include directive, or put a symlink in an included directory since this configuration file is already installed as /usr/local/shib-sp/etc/shibboleth/apache.config.

# ADD THIS TO THE END OF YOUR APACHE'S HTTPD.CONF

######
## SHIB Config
######

#
# Load the Shibboleth module.
#
LoadModule mod_shib /usr/local/shib-sp/libexec/mod_shib_13.so

#
# 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.
#
ShibSchemaDir /usr/local/shib-sp/share/xml/shibboleth
ShibConfig /usr/local/shib-sp/etc/shibboleth/shibboleth.xml

#
# An Apache handler needs to be established for the "handler" location.
# This applies the handler to any requests for a resource with a ".sso"
# extension.
#
<Files *.sso>
SetHandler shib-handler
</Files>
#
# Another way of addressing this is to apply Shibboleth
# globally to the site in "lazy" session mode:
# <Location />
# AuthType shibboleth
# require shibboleth
# </Location>

#
# Used for example logo and style sheet in error templates.
#
<IfModule mod_alias.c>
  Alias /shibboleth-sp/main.css /usr/local/shib-sp/doc/shibboleth/main.css
  Alias /shibboleth-sp/logo.jpg /usr/local/shib-sp/doc/shibboleth/logo.jpg
</IfModule>

##
# Configure the module for content
#
# You can now do most of this in shibboleth.xml using the RequestMap
# but you MUST enable AuthType shibboleth for the module to process
# any requests, and there MUST be a require command as well. To
# enable Shibboleth but not specify any session/access requirements
# use "require shibboleth".
#
<Location /secure>
  AuthType shibboleth
  ShibRequireSession On
  require valid-user
</Location>

If you want to use Debian-specific packages, scripts and configuration:
note: the apache-ssl package can use all the modules that are located in the apache install directory. So it is sufficient to create a symbolic link in the install directory of apache (and NOT in the install directory of apache-ssl). Note that the configuration of this package is located at /etc/apache-ssl and that its startup script is /etc/init.d/apache-ssl.

First create a symbolic link in the /usr/lib/apache/1.3 directory.
This symbolic link is needed for the Debian-specific apache-modconf tool. This tool will search apache's module directory for the right module and its descriptor.
```
root# ln -s /usr/local/shib-sp/libexec/mod_shib_13.so /usr/lib/apache/1.3/mod_shib_13.so
```

Download the Shibboleth module descriptor 500mod_shib_13.info for usage with apache-modconf and save it in the /usr/lib/apache/1.3 directory.
Content of file: /usr/lib/apache/1.3/500mod_shib_13.info

LoadModule: mod_shib /usr/lib/apache/1.3/mod_shib_13.so
Directives:
 ShibConfig
 ShibSchemaDir
 ShibURLScheme
 ShibDisable
 ShibApplicationId
 ShibBasicHijack
 ShibRequireSession
 ShibRequireSessionWith
 ShibExportAssertion
 ShibRequireAll
Description: Shibboleth Daemon for SP 1.3

Register the Shibboleth module mod_shib_13 in Apache 1.3 with the Debian apache-modconf tool. This also inserts an entry for the module in /etc/apache/modules.conf so it will be loaded at the startup of the webserver. (if you get no message it means that the command has failed)
```
root# /usr/sbin/apache-modconf apache enable mod_shib_13
Replacing config file /etc/apache/modules.conf with new version
```
if you are using the apache-ssl package, you should change the command to "apache-modconf apache-ssl enable mod_shib_13"

Download the Shibboleth module configuration mod_shib.conf and save it in the /etc/apache/conf.d directory.
(you can find a similar version at /usr/local/shib-sp/etc/shibboleth/apache.config but that also contains the Loadmodule directive and it does not contain the ShibURLScheme directive)
Content of file: /etc/apache/conf.d/mod_shib.conf


##
# adapted for KULeuven
#
# Shibboleth SP 1.3
##
# Shibboleth SP 1.3 config
ShibSchemaDir /usr/local/shib-sp/share/xml/shibboleth
ShibConfig /usr/local/shib-sp/etc/shibboleth/shibboleth.xml

<Files *.sso>
  SetHandler shib-handler
</Files>

# *Velpi*
# when using Debian's apache-ssl package the next directive is NECESSARY
# it makes the SAML post use SSL, even when HandlerSSL="false"
# when set HandlerSSL="true" without this directive, apache fails to load...
# see Shibboleth-internet2 mailinglist "apache-ssl 1.3.33 debian (Sarge) oddity"
ShibURLScheme https

#
# Used for example logo and style sheet in error templates.
#
# 
#   Alias /shibboleth-sp/main.css /usr/local/shib-sp/doc/shibboleth/main.css
#   Alias /shibboleth-sp/logo.jpg /usr/local/shib-sp/doc/shibboleth/logo.jpg
#  

##
# example:
# /secure location is protected by shibboleth
# this location can be accessed by any user within the KULeuven federation
<Location /secure>
  AuthType shibboleth
  ShibRequireSession On
  require valid-user
</Location>

Restart your Apache 1.3 webserver to apply the changes (consider apache -t first):

root# /etc/init.d/apache restart
Restarting apache.

Apache 2.0 Configuration

The Apache 2.0 webserver must be configured to load the Shibboleth SP 1.3 module. If your setup does not support https yet, read this document first: http://shib.kuleuven.be/docs/apache2-ssl.shtml.

The Shibboleth module configuration is included in the Shibboleth distribution so you can consider a Include directive or symlinking to /usr/local/shib-sp/etc/shibboleth/apache2.config. The configuration should be saved as /etc/apache/conf.d/mod_shib.conf. (If you really want to use Debian-specific tools like a2en you can tear this file apart into shib.load and shib.conf and put them in the /etc/apache2/modules-available directory)

root# cp /usr/local/shib-sp/etc/shibboleth/apache2.config /etc/apache2/conf.d/mod_shib.conf

Content of file: /etc/apache2/conf.d/mod_shib.conf


# ADD THIS TO THE END OF YOUR APACHE'S HTTPD.CONF

######
## SHIB Config
######

#
# Load the SHIBBOLETH module
#
LoadModule mod_shib /usr/local/shib-sp/libexec/mod_shib_20.so

#
# 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.
#
ShibSchemaDir /usr/local/shib-sp/share/xml/shibboleth
ShibConfig /usr/local/shib-sp/etc/shibboleth/shibboleth.xml

#
# Used for example logo and style sheet in error templates.
#
<IfModule mod_alias.c>
  Alias /shibboleth-sp/main.css /usr/local/shib-sp/doc/shibboleth/main.css
  Alias /shibboleth-sp/logo.jpg /usr/local/shib-sp/doc/shibboleth/logo.jpg
</IfModule>

#
# Configure the module for content
#
# You can now do most of this in shibboleth.xml using the RequestMap
# but you MUST enable AuthType shibboleth for the module to process
# any requests, and there MUST be a require command as well. To
# enable Shibboleth but not specify any session/access requirements
# use "require shibboleth".
#
<Location /secure>
  AuthType shibboleth
  ShibRequireSession On
  require valid-user
</Location>

Restart your Apache 2.0 webserver to apply the changes (consider apache -t first):

root# /etc/init.d/apache2 restart
Restarting apache.

Firewall settings

inbound traffic:
- webserver: port 80 and/or 443 are used by any browser-user
outbound:
- Shibboleth daemon (shibd): has to be able to connect to every remote IdP in the federation on port 8443 for attribute fetching
- NTP: a query from a client (like our server) is performed on a remote NTP-server that runs on port 123.

note: unless you are working in a clustered environment, you should not use the deamon on port 1600. On *nix environments you should use a local socket for communication between the webserver's module and the Shibboleth Daemon.

K.U.Leuven Shibboleth Registry

In order to fetch attributes from the Shibboleth Identity Provider, your Service Provider needs to know the location and ports of the IdP. All involved Idp's also need some information about your SP. Once you have completed your setup of the Shibboleth SP, you should email us (shib@kuleuven.be) so we can update all involved metadata.

Install Shibboleth Service Provider 1.3 on Debian 3.1 (sarge)

Table of contents

Introduction

Prerequisites

Installation of Shibboleth SP 1.3

Using debian packages

Compiling from source

Debian C/C++ Compilers and Building Tools

Install OpenSSL library

Install libcurl library

Build and Install log4cpp library

Build and Install Xerces-C++ library

Build and install XML-security C++ library

Build and install OpenSAML library

Build and install Shibboleth SP 1.3

Apache development packages

Shibboleth SP 1.3

SSL certificates

Generate certificate

Shibboleth SP 1.3 initial configuration

Debian Directories

Key and Certificate

shibboleth.xml

AAP.xml

Federation Metadata

Loggers Configuration

Shibboleth Daemon Startup Script

Apache configuration

Apache startup scripts

Apache 1.3 Configuration

Apache 2.0 Configuration

Firewall settings

K.U.Leuven Shibboleth Registry