URL: http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/sp/install-sp-1.3-debian.html Author: Valery Tschopp - SWITCH Author: Lukas Haemmerle - SWITCH Author: Patrik Schnellmann - SWITCH $Date: 2007/10/19 11:39:52 $ $Revision: 1.62 $
Please remember that since April 2007 there is Debian 4.0 (etch) available and we recommend to upgrade your Debian installation to this new release. Have a look at the installation guide for Debian 4.0 (etch).
This guide describes Debian specific installation of a Shibboleth Service Provider 1.3 and its configuration for the SWITCHaai Federation. It covers installation on Debian GNU/Linux 3.1 (Sarge) with Apache 1.3 or Apache 2.0/2.2. This guide also successfully does for a manual installation of the Shibboleth SP on Debian 4.0 (etch).
More extensive information can be found in the Shibboleth Wiki Service Provider Installation of Internet2.
Note: If you want to join the AAI-Test Federation instead of the production SWITCHaai Federation, please consult the AAI-Test Reconfiguration Guide after following the instructions on this page.
Note: For general information about the deployment of Shibboleth within the SWITCHaai Federation, please consult the Deployment section of the SWITCHaai website (http://www.switch.ch/aai/).
The Shibboleth Service Provider (SP) 1.3 is implemented in C/C++ as an Apache
authentification module mod_shib and a separate daemon shibd.
The example values used in this guide are:
www.example.ch~/build-shibboleth-1.3As indicated in the title, this guide applies to Debian 3.1 (sarge) and contains some references to Debian specific tools.
apachelibapache-mod-sslopensslntp-server (or any other package which provides time-synchronization)sudoThis section briefly mentions the needed steps to get a server certificate, which is needed for Shibboleth. For a full documentation how to get SWITCHpki certificates, see http://www.switch.ch/aai/certificates/get-switchpki-certificate.html
$ openssl genrsa -out www.example.ch.key 2048
$ openssl req -new -key www.example.ch.key -out www.example.ch.csr
www.example.ch.crt.
After having generated a certificate, you either can install the Service Provider with Debian packages (A.) or manually install (B.) the Service Provider. A is recommended because it is much easier not only for installation but also for package updates.
Since November 2006 SWITCH has been provided Debian packages for the Shibboleth Service Provider 1.3. The goal of these packages is to have an easy and convenient way to install and upgrade the Service Provider. However, since Debian 4.0 (etch) there are official packages in the Debian repository. Therefore, there is no need anymore to provide own packages for Debian, which is why SWITCH won't provide own packages for Debian (etch) anymore.
If you decide to nevertheless use the Debian packages for sarge, add the following
line to the file /etc/apt/sources.list of your Debian installation:
deb http://www.switch.ch/aai/debian-repository sarge/binary/
Then run
$ apt-get updateto update your repository with the available package list. To configure a Service Provider for the SWITCHaai Federation or the AAI Test Federation, one can use either of these commands
$ apt-get remove --purge shibboleth-sp
Then, remove the repository http://www.switch.ch/aai/debian-repository from your /etc/apt/sources.list.
The installation of the Service Provider with Debian packages is pretty straight forward. On a Debian 4.0 (etch) system run:
$ apt-get install libapache2-mod-shibAfter the installation is over, continue to the registration in the the Resource Registry of this Service Provider and after the resource description was approved, download and install the custom configuration for this Service Provider from the Resource Registry.
The installation requires to compile the Shibboleth Service Provider 1.3 and some libraries from the sources. 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: /opt/shibboleth-1.3
$ export SHIB_HOME=/opt/shibboleth-1.3
You may also include the following lines in /etc/profile for a system wide settings or in ~/.bashrc for your personal settings:
SHIB_HOME=/opt/shibboleth-1.3 export SHIB_HOME
To build the Shibboleth SP 1.3 you need a build directory. In this guide we use: ~/build-shibboleth-1.3
$ mkdir ~/build-shibboleth-1.3
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:
$ sudo apt-get install gcc g++ makeInstalling these packages will also install a lot of other dependent packages.
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:
$ sudo apt-get install libssl0.9.7 libssl-devInstalling these packages will also install a lot of other dependent packages.
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:
$ sudo apt-get install libcurl3 libcurl3-devInstalling these packages could also install other dependent packages.
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: Internet2's Shibboleth Project is using a snapshot release of log4cpp. 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:
$ cd ~/build-shibboleth-1.3 $ wget http://shibboleth.internet2.edu/downloads/log4cpp-0.3.5rc1.tar.gz $ tar xvzf log4cpp-0.3.5rc1.tar.gz $ cd log4cpp-0.3.5rc1 $ ./configure --prefix=$SHIB_HOME --disable-static --disable-doxygen $ make $ sudo make install
make install will install the log4cpp shared library in /opt/shibboleth-1.3.
Therefore, you must have write access to this directory.
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/ For the Shibboleth SP do not use the unpatched version of the xerces-c project homepage.
Shibboleth SP 1.3 requires the special library Xerces-C++ version 2.7.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:
$ cd ~/build-shibboleth-1.3 $ wget http://shibboleth.internet2.edu/downloads/xerces-c-src_2_7_1.tar.gz $ tar xvzf xerces-c-src_2_7_1.tar.gz $ cd xerces-c-src_2_7_1 $ export XERCESCROOT=`pwd` $ cd src/xercesc $ ./runConfigure -p linux -c gcc -x g++ -r pthread -P $SHIB_HOME $ make $ sudo env XERCESCROOT=$XERCESCROOT make installThe Xerces-C++ shared library is now installed in
/opt/shibboleth-1.3
The XML Security C++ library is an open source 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:
$ cd ~/build-shibboleth-1.3 $ export XERCESCROOT=`pwd`/xerces-c-src_2_7_1 $ wget http://xml.apache.org/dist/security/c-library/xml-security-c-1.2.1.tar.gz $ tar xvzf xml-security-c-1.2.1.tar.gz $ cd xml-security-c-1.2.1/src $ ./configure --prefix=$SHIB_HOME --without-xalan $ make $ sudo env XERCESCROOT=$XERCESCROOT make installThe XML-Security shared library is now installed in
/opt/shibboleth-1.3
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.1b library is required by Shibboleth SP 1.3.
To build and install the OpenSAML library:
$ cd ~/build-shibboleth-1.3 $ wget http://shibboleth.internet2.edu/downloads/opensaml-1.1b.tar.gz $ tar xvzf opensaml-1.1b.tar.gz $ cd opensaml-1.1 $ ./configure --prefix=$SHIB_HOME --with-log4cpp=$SHIB_HOME -C $ make $ sudo make installThe OpenSAML shared library is now installed in
/opt/shibboleth-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 1.3: 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:
$ sudo apt-get install apache-dev
Apache 2.0 / 2.2: If you have installed the Debian Apache 2.0 or 2.2 web server, then install
the development package containing apxs2 and the Apache2 header files.
Use apt-get to install the Apache2 development package:
$ sudo apt-get install apache2-threaded-dev
Building the Shibboleth Daemon shibd, the Apache modules, and the shared
libraries is more or less like building OpenSAML.
Upgrade Warning:
If you are upgrading your current installation, please backup your current /etc/shibboleth directory. Otherwise your current local configuration files could be overwritten and lost.
Apache 1.3: To build and install the Shibboleth Service Provider for Apache 1.3:
$ cd ~/build-shibboleth-1.3
$ wget http://shibboleth.internet2.edu/downloads/shibboleth-sp-1.3f.tar.gz
$ tar xvzf shibboleth-sp-1.3f.tar.gz
$ cd shibboleth-1.3
$ ./configure --prefix=$SHIB_HOME \
--with-log4cpp=$SHIB_HOME \
--enable-apache-13 --with-apxs=/usr/bin/apxs \
--disable-mysql
$ make
$ sudo make install
Apache 2.0: To build and install the Shibboleth Service Provider for Apache 2.0:
$ cd ~/build-shibboleth-1.3
$ wget http://shibboleth.internet2.edu/downloads/shibboleth-sp-1.3f.tar.gz
$ tar xvzf shibboleth-sp-1.3f.tar.gz
$ cd shibboleth-1.3
$ ./configure --prefix=$SHIB_HOME \
--with-log4cpp=$SHIB_HOME \
--enable-apache-20 \
--with-apxs2=/usr/bin/apxs2 --with-apr=/usr/bin/apr-config \
--disable-mysql
$ make
$ sudo make install
Apache 2.2: To build and install the Shibboleth Service Provider for Apache 2.2:
$ cd ~/build-shibboleth-1.3
$ wget http://shibboleth.internet2.edu/downloads/shibboleth-sp-1.3f.tar.gz
$ tar xvzf shibboleth-sp-1.3f.tar.gz
$ cd shibboleth-1.3
$ ./configure --prefix=$SHIB_HOME \
--with-log4cpp=$SHIB_HOME \
--enable-apache-22 \
--with-apxs22=/usr/bin/apxs2 --with-apr=/usr/bin/apr-config \
--disable-mysql
$ make
$ sudo make install
/opt/shibboleth-1.3.
This section briefly mentions the needed steps to get a server certificate. For a full documentation how to get SWITCHpki certificates, see http://www.switch.ch/aai/certificates/get-switchpki-certificate.html
$ openssl genrsa -out www.example.ch.key 2048
$ openssl req -new -key www.example.ch.key -out www.example.ch.csr
www.example.ch.crt.
On Debian, all the system configuration files are stored in the directory /etc.
Create a directory to store the Shibboleth configuration files and download the related SWITCHaai configuration files.
$ sudo mkdir /etc/shibboleth
$ cd /etc/shibboleth
$ wget http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/sp/shibboleth.xml
$ wget http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/sp/AAP.switchaai.xml
$ wget http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/sp/shibboleth.logger
$ wget http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/sp/native.logger
$ wget http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/sp/shibd.logger
$ wget -O metadata.switchaai.xml \
http://www.switch.ch/aai/federation/SWITCHaai/metadata.switchaai_signed.xml
$ cp /opt/shibboleth-1.3/etc/shibboleth/sessionError.html .
$ cp /opt/shibboleth-1.3/etc/shibboleth/metadataError.html .
$ cp /opt/shibboleth-1.3/etc/shibboleth/rmError.html .
$ cp /opt/shibboleth-1.3/etc/shibboleth/accessError.html .
The /var/log/shibboleth logging directory doesn't exist. You have
to create it and grant the user running Apache write access to it.
$ sudo mkdir /var/log/shibboleth $ sudo chgrp www-data /var/log/shibboleth $ sudo chmod g+w /var/log/shibboleth
Copy the private key and certificate to the /etc/shibboleth directory:
$ sudo cp www.example.ch.key /etc/shibboleth/ $ sudo cp www.example.ch.crt /etc/shibboleth/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.
This is the main configuration file for the Service Provider and is already preconfigured for the SWITCHaai federation.
Edit the /etc/shibboleth/shibboleth.xml file and configure your SP 1.3:
providerId: This URN is the unique identifier of your resource
within the federation. It's value should be 'stable'. It should not change,
even when you have to move your resource from one host to another one. So
choosing a 'service name' is preferred over a host name.https://<HOSTNAME>/shibboleth
<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="/opt/shibboleth-1.3/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/shib-shar.sock"/>
<!-- <TCPListener address="127.0.0.1" port="12345" acl="127.0.0.1"/> -->
<!--
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="true"/>
</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="www.example.ch">
<Path name="secure" authType="shibboleth" requireSession="true" exportAssertion="true">
<!-- Example shows a subfolder on the SSL port assigned to a separate <Application> -->
<Path name="foo-admin" applicationId="foo-admin"/>
</Path>
</Host>
</RequestMap>
</RequestMapProvider>
<Implementation>
<ISAPI normalizeRequest="true">
<!--
Maps IIS Instance ID values to the host scheme/name/port/sslport. The name is
required so that the proper <Host> in the request map above is found without
having to cover every possible DNS/IP combination the user might enter.
The port and scheme can usually be omitted, so the HTTP request's port and
scheme will be used.
<Alias> elements can specify alternate permissible client-specified server names.
If a client request uses such a name, normalized redirects will use it, but the
request map processing is still based on the default name attribute for the
site. This reduces duplicate data entry in the request map for every legal
hostname a site might permit. In the example below, only sp.example.org needs a
<Host> element in the map, but spalias.example.org could be used by a client
and those requests will map to sp.example.org for configuration settings.
-->
<Site id="1" name="www.example.ch">
<!-- <Alias>www-alias.example.ch</Alias> -->
</Site>
</ISAPI>
</Implementation>
</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://www.example.ch/shibboleth"
homeURL="https://www.example.ch/"
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 if the value of checkAddress is set to "false", this has a slightly negative
impact on the security of the SP. This security feature checks the user's IP address
at the SP and compares it with the IP address used at the IdP. If they don't match, an error
is thrown. This rather strict security feature can cause problems for users behind proxies
or for users with IPv6 addresses. Therefore, this setting is deactivated per default.
To compensate the slightly reduced security the consistentAddress feature is activated
in the default configuration.
The consistentAddress feature is available as of version 1.3c for the element.
It defaults to true when not present and ensures that once a session cookie is
issued to a client, any further use of that session cookie must be from a client with the
same network address. This raises the bar for session hijackers to the level of network
address spoofing, which may or may not be simple to do, but is definitely harder than
stealing cookies and relies on a different set of attacking skills.
On the other hand the consistentAddress may also cause problems for users whose IP changes
during the session (e.g. for AOL users or for users behind proxies
which have multiple IP addresses).
For additional information about the checkAddress and the consistentAddress setting have
a look at https://spaces.internet2.edu/display/SHIB/AddressChecking
-->
<Sessions lifetime="7200" timeout="3600" checkAddress="false"
handlerURL="/Shibboleth.sso" handlerSSL="false"
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 directs users to a specific SWITCHaai WAYF service. -->
<SessionInitiator id="SWITCHaai" isDefault="true"
Location="/WAYF/SWITCHaai"
Binding="urn:mace:shibboleth:sp:1.3:SessionInit"
wayfURL="https://wayf.switch.ch/SWITCHaai/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="YOUR_EMAIL_ADDRESS"
logoLocation="YOUR_LOGO_LOCATION"
styleSheet="YOUR_STYLESHEET_LOCATION"/>
<!-- Indicates what credentials to use when communicating -->
<CredentialUse TLS="switchaai" Signing="switchaai">
<!-- RelyingParty elements can customize credentials for specific IdPs/sets. -->
<!--
<RelyingParty Name="urn:mace:switch.ch:aaitest" TLS="aaitest" Signing="aaitest"/>
-->
</CredentialUse>
<!-- AAP can be inline or in a separate file -->
<AAPProvider type="edu.internet2.middleware.shibboleth.aap.provider.XMLAAP"
uri="/etc/shibboleth/AAP.switchaai.xml"/>
<!-- Operational config consists of metadata and trust providers. Can be external or inline. -->
<!-- SWITCHaai federation metadata (production) -->
<MetadataProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata"
uri="/etc/shibboleth/metadata.switchaai.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.
-->
<!-- SWITCHaai federation -->
<saml:Audience>urn:mace:switch.ch:SWITCHaai</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/foo-admin/Shibboleth.sso" handlerSSL="true"
cookieProps="; path=/secure/foo-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="switchaai">
<Key>
<Path>/etc/shibboleth/www.example.ch.key</Path>
</Key>
<Certificate>
<!-- Certificate and the whole chain -->
<Path>/etc/shibboleth/www.example.ch.crt</Path>
</Certificate>
</FileResolver>
</Credentials>
</CredentialsProvider>
</SPConfig>
This file implements the AAI Attribute Specifications and maps the attributes to Apache environment variables. For more information about the specification, see the PDF document: http://www.switch.ch/aai/docs/AAI_Attr_Specs.pdf.
Important: The SWITCHaai federation metadata must be periodically updated to keep your resource up-to-date with the current state of the federation. See the SWITCHaai Federation Metadata Update Guide for more information.
If it is not already done, download the loggers configuration files shibboleth.logger,
native.logger and
shibd.logger and store them in
/etc/shibboleth directory.
The Shibboleth SP will log in the /var/log/shibboleth directory.
The Shibboleth SP 1.3 daemon shibd must run in parallel with Apache.
Download the Debian shibboleth startup script
and store it in the /etc/init.d directory.
$ cd /etc/init.d $ sudo wget http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/sp/shibboleth
/etc/init.d/shibboleth
#! /bin/sh
#
# /etc/init.d/shibboleth for Debian
#
# start/stop script for Shibboleth ServiceProvider 1.3 daemon
#
# Created: 20050602 - Valery Tschopp - SWITCH
#
# HOWTO INSTALL:
# root:/etc/init.d# update-rc.d shibboleth defaults 95 15
PATH=/bin:/usr/bin:/sbin:/usr/sbin
#
# Shibboleth 1.3
#
SHIB_HOME=/opt/shibboleth-1.3
SHIB_ETC=/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 Debian update-rc.d tool to register the /etc/init.d/shibboleth
script as a system startup script:
$ sudo update-rc.d shibboleth defaults
Adding system startup for /etc/init.d/shibboleth ...
/etc/rc0.d/K20shibboleth -> ../init.d/shibboleth
/etc/rc1.d/K20shibboleth -> ../init.d/shibboleth
/etc/rc6.d/K20shibboleth -> ../init.d/shibboleth
/etc/rc2.d/S20shibboleth -> ../init.d/shibboleth
/etc/rc3.d/S20shibboleth -> ../init.d/shibboleth
/etc/rc4.d/S20shibboleth -> ../init.d/shibboleth
/etc/rc5.d/S20shibboleth -> ../init.d/shibboleth
Finally start the Shibboleth 1.3 Daemon:
$ sudo /etc/init.d/shibboleth start
Starting Shibboleth 1.3 Daemon: shibd.
The Apache 1.3 or Apache 2.0 / 2.2 webserver must be configured to load the Shibboleth SP 1.3 module.
Note: Although it is possible to use Shibboleth on a web server withouth SSL, for security considerations it is strongly recommended to configure your web server for https.
Please refer to the Apache documentation on how to do that. You can use the same certificate for the web server as you use for Shibboleth. This guide assumes that you have configured your web server for HTTPS.
First create a symbolic link in the /usr/lib/apache/1.3 directory:
$ sudo ln -s /opt/shibboleth-1.3/libexec/mod_shib_13.so /usr/lib/apache/1.3/mod_shib_13.so
Download the Shibboleth module descriptor 500mod_shib_13.info for Apache 1.3 and store it in the /usr/lib/apache/1.3 directory.
$ cd /usr/lib/apache/1.3 $ sudo wget http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/sp/500mod_shib_13.info
/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:
$ sudo /usr/sbin/apache-modconf apache enable mod_shib_13
Replacing config file /etc/apache/modules.conf with new version
Download the Shibboleth module configuration mod_shib.conf
and store it in the /etc/apache/conf.d directory.
$ cd /etc/apache/conf.d $ sudo wget http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/sp/mod_shib.conf
/etc/apache/conf.d/mod_shib.conf
##
# SWITCHaai
#
# Shibboleth SP 1.3
##
# Shibboleth SP 1.3 config
ShibConfig /etc/shibboleth/shibboleth.xml
ShibSchemaDir /opt/shibboleth-1.3/share/xml/shibboleth
<Files *.sso>
SetHandler shib-handler
</Files>
##
# example: /aai location is protected by shibboleth
#<Location /aai>
# AuthType shibboleth
# ShibRequireSession On
# require valid-user
#</Location>
On Debian the Apache 1.3 webserver is started with the /etc/init.d/apache
script. The script must be modified and the environment variable LD_LIBRARY_PATH
set to be able to load the Shibboleth module.
You can use the sample startup script apache to
correctly set the LD_LIBRARY_PATH .
Begining of file: /etc/init.d/apache
#!/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=/opt/shibboleth-1.3
LD_LIBRARY_PATH=${SHIB_HOME}/libexec:${SHIB_HOME}/lib
export LD_LIBRARY_PATH
Finally restart your Apache 1.3 webserver:
$ sudo /etc/init.d/apache restart
Restarting apache.
Download the Shibboleth module configuration mod_shib.conf
and store it in the /etc/apache2/mods-available directory.
$ cd /etc/apache2/mods-available $ sudo wget http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/sp/mod_shib.conf
/etc/apache2/mods-available/mod_shib.conf
##
# SWITCHaai
#
# Shibboleth SP 1.3
##
# Shibboleth SP 1.3 config
ShibConfig /etc/shibboleth/shibboleth.xml
ShibSchemaDir /opt/shibboleth-1.3/share/xml/shibboleth
<Files *.sso>
SetHandler shib-handler
</Files>
##
# example: /aai location is protected by shibboleth
#<Location /aai>
# AuthType shibboleth
# ShibRequireSession On
# require valid-user
#</Location>
Download the Shibboleth module loader mod_shib.load
and store it in the /etc/apache2/mods-available directory.
$ cd /etc/apache2/mods-available $ sudo wget http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/sp/mod_shib.load
/etc/apache2/mods-available/mod_shib.load
# # Load Shibboleth module for Apache2 # LoadModule mod_shib /opt/shibboleth-1.3/libexec/mod_shib_20.so
To enable the Shibboleth module for Apache2, use the Debian a2enmod tool:
$ sudo a2enmod mod_shib
Module mod_shib installed; run /etc/init.d/apache2 force-reload to enable.
On Debian the Apache 2.0 / 2.2 webserver is started with the /etc/init.d/apache2
script. The script read the /etc/apache2/envvars to set optional environment variables. /etc/apache2/envvars must be modified and the environment variable LD_LIBRARY_PATH set to be able to load the Shibboleth module.
You can use this sample to correctly set the LD_LIBRARY_PATH for Shibboelth.
Content of file: /etc/apache2/envvars
# Copyright 2001-2005 The Apache Software Foundation or its licensors, as
# applicable.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
SHIB_HOME=/opt/shibboleth-1.3
LD_LIBRARY_PATH=${SHIB_HOME}/libexec:${SHIB_HOME}/lib
export LD_LIBRARY_PATH
Finally restart your Apache 2.0 / 2.2 webserver:
$ sudo /etc/init.d/apache2 restart
Forcing reload of web server: Apache2.
In order to release attributes to your Service Provider the Shibboleth Identity Provider (Home Organization) needs to know all Service Providers they can communicate with. Therefore, they have to regularely update their metadata files. There is a tool called 'Resource Registry' (also see the information about the Resource Registry) whose purpose is to have an up-to date list of all Identity Provider and Service Provider in the SWITCHaai Federation.
It is vital that you register your Service Provider in the AAI Resource Registry.
To register a resource, go to the AAI Resource Registry and log in via AAI. After you are logged in, you can 'add a Resource Description'. You have to provide some technical details about your Service Provider (Resource) and then finally submit the Resource Description to the Resource Registry Authority Admin of your Home Organization. This person then has to approve your Resource before it gets active, which means that the Identity Providers receive the metadata of your Service Provider.
Protecting certain directories or pages with Shibboleth can be done via the web server or within an application itself.
Using the web server, e.g. Apache one can define rules like:
AuthType shibboleth
ShibRequireSession On
ShibRedirectToSSL 443
ShibRequireAll On
require affiliation student
require homeOrganization unizh.ch ethz.ch
in the Apache configuration file or in .htaccess files.
Within an application you can access all available Shibboleth attributes as environment variables (e.g. for PHP in $_SERVER or for Perl in %ENV). This allows much more flexible authorization of users than with the web server's access rules.
You find more detailed instructions on how to protect a Resource with Shibboleth on our Shibboleth Service Provider Access Rules page.
-- $Id: install-sp-1.3-debian.html,v 1.62 2007/10/19 11:39:52 schnell Exp $