Author: Valéry Tschopp <tschopp@switch.ch> - SWITCH
Author: Lukas Hämmerle <haemmerle@switch.ch> - SWITCH
$Date: 2005/04/22 15:40:44 $
$Revision: 1.8 $
This document is a detailed deployment configuration of Shibboleth Target 1.2.1 within the SWITCHaai Federation on a Unix system, in particular Debian GNU/Linux 3.0 (woody) or Sun Solaris 8 and 9.
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.1 requires that you previously installed it in /opt/shibboleth-1.2.1. Please refer to the Compilation and Installation Guides for Shibboleth Target 1.2.1 on Debian or Shibboleth Target 1.2.1 on Solaris documents.
To configure your resource within another federation or for other platform than Debian or Solaris, please refer directly to the original Internet2's Shibboleth Target 1.2.1 Deployment Guide.
You need a SWITCHpki server certificate to deploy the Shibboleth Target 1.2.1 within the SWITCHaai federation. Please refer to SWITCHpki web page for more informations.
Your SWITCHpki server certificate file must contains the certificate and the whole CA certificate chain.
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"> <Path>/etc/apache/ssl.key/YOUR_CERTIFICATE.key</Path> </Key>
To integrate your Resource within the SWITCHaai Federation you must configure the Shibboleth Target 1.2.1 as a member of the federation.
You can download shib-target-1.2.1-switchaai.tar.gz containing the default SWITCHaai files for your Shibboleth Target 1.2.1 configuration.
These configuration files must be stored in /opt/shibboleth-1.2.1/etc/shibboleth directory.
Once you have downloaded the sample configuration files and stored them in /opt/shibboleth-1.2.1/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.1/etc/shibboleth/shibboleth.switchaai.xml
SWITCHaai config file for Shibboleth 1.2.1
date: 20040615
-->
<ShibbolethTargetConfig xmlns="urn:mace:shibboleth:target:config:1.0"
logger="/opt/shibboleth-1.2.1/etc/shibboleth/shibboleth.logger"
clockSkew="180">
<Extensions>
<Library path="/opt/shibboleth-1.2.1/libexec/xmlproviders.so" fatal="true"/>
</Extensions>
<SHAR logger="/opt/shibboleth-1.2.1/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.1/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.1/etc/shibboleth/shireError.html"
rm="/opt/shibboleth-1.2.1/etc/shibboleth/rmError.html"
access="/opt/shibboleth-1.2.1/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.1/etc/shibboleth/AAP.switchaai.xml"/>
<!-- SWITCHaai Federation Metadata: sites -->
<FederationProvider type="edu.internet2.middleware.shibboleth.common.provider.XMLMetadata"
uri="/opt/shibboleth-1.2.1/etc/shibboleth/sites.switchaai.xml"/>
<!-- SWITCHaai Federation Metadata: trust -->
<TrustProvider type="edu.internet2.middleware.shibboleth.common.provider.XMLTrust"
uri="/opt/shibboleth-1.2.1/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">
<!-- Server Certifcate with CA Chain -->
<Path>/etc/apache/ssl.crt/YOUR_CERTIFICATE.crt</Path>
</Certificate>
</FileResolver>
</Credentials>
</CredentialsProvider>
</ShibbolethTargetConfig>
On Debian the Shibboleth SHAR must be started with the /etc/init.d/shibboleth script.
You can use the sample startup script init.d-shibboleth as example. Don't forget to update your system configuration to run this script on system startup.
#! /bin/bash
#
# /etc/init.d/shibboleth for Debian
#
# start/stop script for Shibboleth Target 1.2 SHAR process
#
# Created: 20041021 - 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.2
#
SHIB_HOME=/opt/shibboleth-1.2.1
SHIB_ETC=$SHIB_HOME/etc/shibboleth
SHIB_CONFIG=$SHIB_ETC/shibboleth.switchaai.xml
LD_LIBRARY_PATH=$SHIB_HOME/lib
DAEMON=$SHIB_HOME/bin/shar
NAME=shar
DESC="Shibboleth SHAR 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|configtest}" >& 2
exit 1
;;
esac
exit 0
The Apache 1.3 webserver must be configured to load the Shibboleth Target 1.2.1 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.1 module, configure it and ensure that SSL is correctly configured.
Load the Shibboleth Target 1.2.1 module in the Dynamic Shared Object section of the /etc/apache/httpd.conf configuration file 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.1/libexec/mod_shib_13.so
To configure the module add the following lines to your /etc/apache/httpd.conf file:
# # SWITCHaai # # Shibboleth 1.2.1 Target config # ShibConfig /opt/shibboleth-1.2.1/etc/shibboleth/shibboleth.switchaai.xml ShibSchemaDir /opt/shibboleth-1.2.1/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>
On Debian the Apache 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 init.d-apache to correctly set the LD_LIBRARY_PATH.
#! /bin/bash
#
# apache Start the apache HTTP server.
#
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 1.2.1
# set LD_LIBRARY_PATH to load Shibboleth module.
#
SHIB_HOME=/opt/shibboleth-1.2.1
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 -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
;;
reload)
echo -n "Reloading $NAME configuration"
start-stop-daemon --stop --pidfile $PIDFILE --signal USR1 --exec $DAEMON
;;
reload-modules)
echo -n "Reloading $NAME modules"
start-stop-daemon --stop --pidfile $PIDFILE --oknodo --retry 30
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
The actual SWITCHaai Federation Metadata files (sites.xml and trust.xml) must be retrieved with the siterefresh tool installed with the Shibboleth framework.
The script siterefresh.sh is a wrapper script for the Shibboleth siterefresh tool. This script can simply be installed as a cron job and automatically runs once a day or once a week.
To verify the signatures and integrity of the metadata files, you must download the SWITCHaai Signer Certificate SWITCHpki-wayf1.switch.ch.crt and store it in under /etc/shibboleth/wayf1.switch.ch.crt.
The script will first download and verfiy the signature of the sites and trust files. Then it will compare the actual local sites and trust with the new ones. If the downloaded metadata files are newer than the local ones, the script does a backup of the old ones and replaces them.
#! /bin/sh # # SWITCHaai Federation Metadata (1.1 and 1.2) # # Shibboleth Target 1.1: # Sites File: http://wayf1.switch.ch/SWITCHaai/sites.xml # Trust File: http://wayf1.switch.ch/SWITCHaai/trust.xml # # Shibboleth Target 1.2: # Sites File: http://www.switch.ch/aai/federation/pilot/sites-1.2.xml # Trust File: http://www.switch.ch/aai/federation/pilot/trust-1.2.xml # # SWITCHaai Signer certificate: # http://www.switch.ch/aai/federation/pilot/SWITCHpki-wayf1.switch.ch.crt # # Valery Tschopp - SWITCH # set -x ## # Configure directories and path ## SHIB_HOME=/opt/shibboleth-1.2.1 SHIB_ETC=/etc/shibboleth LD_LIBRARY_PATH=$SHIB_HOME/lib export LD_LIBRARY_PATH ## # Configure sites and trust download URLs and local names ## SITES_URL=http://www.switch.ch/aai/federation/pilot/sites-1.2.xml TRUST_URL=http://www.switch.ch/aai/federation/pilot/trust-1.2.xml SITES_NAME=$SHIB_ETC/sites.switchaai.xml TRUST_NAME=$SHIB_ETC/trust.switchaai.xml ## # Configure signer certificate ## SIGNER_CRT=$SHIB_ETC/wayf1.switch.ch.crt [ -x $SHIB_HOME/bin/siterefresh ] || exit 0 ############################################ # Get new versions NOW=`date +%Y%m%d%H%M` # logging echo "$NOW: siterefresh starts" >> \ $SHIB_HOME/var/log/shibboleth/siterefresh.log echo "Retrieve Sites file: $SITES_URL" $SHIB_HOME/bin/siterefresh \ --url $SITES_URL \ --out $SITES_NAME.$NOW \ --schema $SHIB_ETC \ --cert $SIGNER_CRT # abort on error [ "$?" -ne "0" ] && exit $? echo "Retrieve Trust file: $TRUST_URL" $SHIB_HOME/bin/siterefresh \ --url $TRUST_URL \ --out $TRUST_NAME.$NOW \ --schema $SHIB_ETC \ --cert $SIGNER_CRT # abort on error [ "$?" -ne "0" ] && exit $? ############################################ # Make backups [ ! -d "$SHIB_ETC/backup" ] && mkdir $SHIB_ETC/backup # Compare new to existing. If same, delete new, if not replace existing # and backup new. for file in $SITES_NAME $TRUST_NAME ; do if [ -r $file.$NOW ] ; then if cmp -s $file.$NOW $file ; then echo "Unchanged $file.$NOW" rm -f $file.$NOW # logging echo "$NOW: unmodified $file" >> \ $SHIB_HOME/var/log/shibboleth/siterefresh.log else echo "New $file.$NOW" cp $file.$NOW $SHIB_ETC/backup mv -f $file.$NOW $file # logging echo "$NOW: new $file installed" >> \ $SHIB_HOME/var/log/shibboleth/siterefresh.log fi else echo "Retrieval of $file.$NOW failed." # logging echo "$NOW: retrival of $file failed" >> \ $SHIB_HOME/var/log/shibboleth/siterefresh.log fi done # logging echo "$NOW: siterefresh end." >> \ $SHIB_HOME/var/log/shibboleth/siterefresh.log
More information about SWITCHaai Metadata.
$Id: deploy-target-1.2.1-unix.html,v 1.8 2005/04/22 15:40:44 schnell Exp $