Author: Valéry Tschopp <tschopp@switch.ch> - SWITCH
Date: 20040729
$Revision: 1.7 $
This document is a detailed deployment configuration of Shibboleth Target 1.2 within the SWITCHaai Federation on a Debian GNU/Linux 3.0r2 (woody) stable.
Note: For general information about the deployment of Shibboleth within the SWITCHaai Federation, please consult the Deployment section of our website.
The deployment configuration of the Shibboleth Target 1.2 requires that you previously installed it in /opt/shibboleth-1.2. Please refer to Install Shibboleth Target 1.2 documentation.
To configure your resource within another federation or for other platform than Debians stable, please refer directly to the original Shibboleth Target 1.2 deployment guide.
You need a SWITCHpki server certificate to deploy the Shibboleth Target 1.2 within the SWITCHaai federation. Please refer to SWITCHpki web page for more informations.
Due to a known bug in Shibboleth 1.2 SHAR your server certificate MUST contain only one certificate block and not the whole certificate chain.
root:/etc/apache/ssl.crt# openssl x509 -in YOUR_CERTIFICATE.crt -out YOUR_CERTIFICATE.crt
Should you protect your private key with DES/3DES, remember to add the attribute "password" to the "Key" tag in the file "shibboleth.switchaai.xml" within the "Credentials" element.
<Key format="PEM" password="YOUR_PRIVATEKEY_PASSWORD">
To integrate your Resource within the SWITCHaai Federation you must configure the Shibboleth Target 1.2 as a member of the federation.
You can download shib-target-1.2-switchaai.tar.gz containing the default SWITCHaai files for your Shibboleth Target 1.2 configuration.
These sample files must be stored in /opt/shibboleth-1.2/etc/shibboleth directory.
Once you have downloaded the sample configuration files and stored them in /opt/shibboleth-1.2/etc/shibboleth, you must edit some of them to reflect your current configuration.
Highlighted in RED are the values you must modify.
Highlighted in BLUE are the values related to SWITCHaai configuration.
<!--
/opt/shibboleth-1.2/etc/shibboleth/shibboleth.switchaai.xml
SWITCHaai config file for Shibboleth 1.2
date: 20040615
-->
<ShibbolethTargetConfig xmlns="urn:mace:shibboleth:target:config:1.0"
logger="/opt/shibboleth-1.2/etc/shibboleth/shibboleth.logger"
clockSkew="180">
<Extensions>
<Library path="/opt/shibboleth-1.2/libexec/xmlproviders.so" fatal="true"/>
</Extensions>
<SHAR logger="/opt/shibboleth-1.2/etc/shibboleth/shar.logger">
<UnixListener address="/tmp/shar-1.2-socket"/>
<MemorySessionCache cleanupInterval="300" cacheTimeout="3600" AATimeout="30" AAConnectTimeout="15"
defaultLifetime="1800" retryInterval="300" strictValidity="false" propagateErrors="true"/>
</SHAR>
<SHIRE logger="/opt/shibboleth-1.2/etc/shibboleth/shire.logger">
<RequestMapProvider type="edu.internet2.middleware.shibboleth.target.provider.XMLRequestMap">
<RequestMap applicationId="default">
<Host name="localhost" scheme="https">
<Path name="secure" requireSession="true" exportAssertion="true"/>
</Host>
<Host name="localhost" scheme="http">
<Path name="secure" requireSession="true" exportAssertion="true"/>
</Host>
</RequestMap>
</RequestMapProvider>
</SHIRE>
<Applications xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
id="default"
providerId="urn:mace:switch.ch:SWITCHaai:pilot:YOUR_FQDN_HOSTNAME">
<Sessions lifetime="7200" timeout="3600" checkAddress="true"
wayfURL="https://wayf1.switch.ch/SWITCHaai/WAYF"
shireURL="/Shibboleth.shire" shireSSL="false"/>
<!--
YOU SHOULD CUSTOMIZED THE ERRORS PAGES! You can add attributes with values that can be plugged
into your templates.
-->
<Errors shire="/opt/shibboleth-1.2/etc/shibboleth/shireError.html"
rm="/opt/shibboleth-1.2/etc/shibboleth/rmError.html"
access="/opt/shibboleth-1.2/etc/shibboleth/accessError.html"
supportContact="YOUR_EMAIL_ADDRESS"
logoLocation="/logo.gif"
styleSheet="/styles.css"/>
<CredentialUse TLS="SWITCHpki" Signing="SWITCHpki">
</CredentialUse>
<!-- SWITCHaai attribute acceptance policy -->
<AAPProvider type="edu.internet2.middleware.shibboleth.target.provider.XMLAAP"
uri="/opt/shibboleth-1.2/etc/shibboleth/AAP.switchaai.xml"/>
<!-- SWITCHaai Federation Metadata: sites -->
<FederationProvider type="edu.internet2.middleware.shibboleth.common.provider.XMLMetadata"
uri="/opt/shibboleth-1.2/etc/shibboleth/sites.switchaai.xml"/>
<!-- SWITCHaai Federation Metadata: trust -->
<TrustProvider type="edu.internet2.middleware.shibboleth.common.provider.XMLTrust"
uri="/opt/shibboleth-1.2/etc/shibboleth/trust.switchaai.xml"/>
<!-- SWITCHaai Federation identifier -->
<saml:Audience>urn:mace:switch.ch:SWITCHaai:pilot</saml:Audience>
</Applications>
<CredentialsProvider type="edu.internet2.middleware.shibboleth.common.Credentials">
<Credentials xmlns="urn:mace:shibboleth:credentials:1.0">
<!-- Define path to your SWITCHpki private key and server certificate -->
<FileResolver Id="SWITCHpki">
<Key format="PEM">
<Path>/etc/apache/ssl.key/YOUR_CERTIFICATE.key</Path>
</Key>
<Certificate format="PEM">
<Path>/etc/apache/ssl.crt/YOUR_CERTIFICATE.crt</Path>
</Certificate>
</FileResolver>
</Credentials>
</CredentialsProvider>
</ShibbolethTargetConfig>
The Apache 1.3 webserver must be configured to load the Shibboleth Target 1.2 module. You can use the sample configuration httpd.switchaai.conf to adapt your own configuration.
You must update your Apache webserver configuration to load the Shibboleth Target 1.2 module, configure it and ensure that SSL is correctly configured.
Load the Shibboleth Target 1.2 module in the Dynamic Shared Object section of /etc/apache/httpd.conf by adding a LoadModule directive:
#
# Dynamic Shared Object (DSO) Support
#
# To be able to use the functionality of a module which was built as a DSO you
# have to place corresponding `LoadModule' lines at this location so the
# directives contained in it are actually available _before_ they are used.
# Please read the file README.DSO in the Apache 1.3 distribution for more
# details about the DSO mechanism and run `apache -l' for the list of already
# built-in (statically linked and thus always available) modules in your apache
# binary.
#
...
LoadModule ssl_module /usr/lib/apache/1.3/mod_ssl.so
# Shibboleth 1.2 Target module
LoadModule mod_shib /opt/shibboleth-1.2/libexec/mod_shib_13.so
To configure the module add the following lines to your /etc/apache/httpd.conf file:
#
# SWITCHaai
#
# Shibboleth 1.2 Target config
#
ShibConfig /opt/shibboleth-1.2/etc/shibboleth/shibboleth.switchaai.xml
ShibSchemaDir /opt/shibboleth-1.2/etc/shibboleth
<Files *.shire>
SetHandler shib-shire-post
</Files>
#
# sample Shibboleth secured directory
#
<Directory /opt/www/shibboleth>
AuthType shibboleth
ShibRequireSession On
require valid-user
</Directory>
Ensure that Apache uses the correct Certificate chain, Certificate Authority bundle file and correct verify depth:
# Server Certificate Chain: # Point SSLCertificateChainFile at a file containing the # concatenation of PEM encoded CA certificates which form the # certificate chain for the server certificate. SSLCertificateChainFile /etc/apache/ssl.crt/switchpki-chain.crt # Certificate Authority (CA): # Set the CA certificate verification path where to find CA # certificates for client authentication or alternatively one # huge file containing all of them (file must be PEM encoded) SSLCACertificateFile /etc/apache/ssl.crt/ca-bundle.switchaai.crt # Client Authentication (Type): # Client certificate verification type and depth. Types are # none, optional, require and optional_no_ca. Depth is a # number which specifies how deeply to verify the certificate # issuer chain before deciding the certificate is not valid. #SSLVerifyClient require SSLVerifyDepth 10
On Debian the Apache webserver is started with the /etc/init.d/apache script. The script must be modified to also start the Shibboleth 1.2 SHAR process.
You can use the sample startup script apache.switchaai to start both Apache webserver and the Shibboleth SHAR:
#! /bin/bash # # apache Start the apache HTTP server. # extended for Shibboleth to handle the SHAR process. # NAME=apache PATH=/bin:/usr/bin:/sbin:/usr/sbin DAEMON=/usr/sbin/apache SUEXEC=/usr/lib/apache/suexec PIDFILE=/var/run/$NAME.pid CONF=/etc/apache/httpd.conf APACHECTL=/usr/sbin/apachectl # # Shibboleth Target adds-on # SHIB_HOME=/opt/shibboleth-1.2 SHIBCONFIG=$SHIB_HOME/etc/shibboleth/shibboleth.switchaai.xml export SHIBCONFIG SHARNAME=shar SHARDAEMON=$SHIB_HOME/bin/shar LD_LIBRARY_PATH=$SHIB_HOME/lib:$SHIB_HOME/libexec export LD_LIBRARY_PATH trap "" 1 export LANG=C export PATH test -f $DAEMON || exit 0 test -f $APACHECTL || exit 0 test -f $SHARDAEMON || exit 0 # ensure we don't leak environment vars into apachectl APACHECTL="env -i LANG=${LANG} PATH=${PATH} $APACHECTL" if egrep -q -i "^[[:space:]]*ServerType[[:space:]]+inet" $CONF then exit 0 fi if [ -e /etc/apache/apache_not_to_be_run ]; then echo "Apache Webserver not started (/etc/apache/apache_not_to_be_run)" exit 0 fi case "$1" in start) echo "Starting Shibboleth SHAR daemon: $SHARNAME" start-stop-daemon --start --name $SHARNAME --background --quiet --exec $SHARDAEMON echo -n "Starting web server: $NAME" start-stop-daemon --start --pidfile $PIDFILE --exec $DAEMON ;; stop) echo "Stopping web server: $NAME" start-stop-daemon --stop --pidfile $PIDFILE --oknodo --exec $DAEMON echo -n "Stopping Shibboleth SHAR daemon: $SHARNAME" start-stop-daemon --stop --name $SHARNAME --oknodo --exec $SHARDAEMON ;; reload) echo -n "Reloading $NAME configuration" start-stop-daemon --stop --pidfile $PIDFILE --signal USR1 --exec $DAEMON ;; reload-modules) echo -n "Reloading $NAME modules - restarting $SHARNAME" start-stop-daemon --stop --name $SHARNAME --oknodo --retry 30 start-stop-daemon --stop --pidfile $PIDFILE --oknodo --retry 30 start-stop-daemon --start --name $SHARNAME --background --quiet --exec $SHARDAEMON start-stop-daemon --start --pidfile $PIDFILE --exec $DAEMON ;; restart) $0 reload-modules exit $? ;; force-reload) $0 reload-modules exit $? ;; *) echo "Usage: /etc/init.d/$NAME {start|stop|reload|reload-modules|force-reload|restart}" exit 1 ;; esac if [ $? == 0 ]; then echo . exit 0 else echo failed exit 1 fi
$Id: deploy-target-1.2-debian.html,v 1.7 2005/04/22 15:40:44 schnell Exp $