Upgrade to the latest version of the Shibboleth Service Provider
(Debian GNU/Linux from sources)

Alessandra Scicchitano

Note For general information about the deployment of Shibboleth within the SWITCHaai Federation, please consult the deployment section of the SWITCHaai website.

1. Prerequisites

This guide describes how to upgrade to the current version of the Service provider 2.4.2

It is assumed that a working Service Provider 2.x with working certificates has been installed and registered already with the Resource Registry.
If the Service Provider you have is 1.3.x, please use the migration guide you find here Shibboleth 2.x migration

2. Upgrade procedure

2.1 Backup

Before upgrading a Service Provider, it is recommended to create a backup of all necessary configuration files.
We strongly suggest to backup the entire/etc/shibboleth.
If your shibboleth directory is not /etc/shibboleth but /etc/shibboleth2, then backup /etc/shibboleth2 and rename the entire directory as /etc/shibboleth.

2.2 Source code download

Define and create the build directory: 
export MYBUILD=~/shibsp2.4.3-build
mkdir $MYBUILD
Download and extract the needed sources: 
wget http://shibboleth.net/downloads/log4shib/latest/log4shib-1.0.4.tar.gz -P $MYBUILD
wget http://shibboleth.net/downloads/c++-opensaml/latest/xmltooling-1.4.2.tar.gz -P $MYBUILD
wget http://shibboleth.net/downloads/c++-opensaml/latest/opensaml-2.4.3.tar.gz -P $MYBUILD
wget http://shibboleth.net/downloads/service-provider/latest/shibboleth-sp-2.4.3.tar.gz -P $MYBUILD
wget http://mirror.switch.ch/mirror/apache/dist/santuario/c-library/xml-security-c-1.6.1.tar.gz -P $MYBUILD

for f in $MYBUILD/*.tar.gz; do tar -xzvf $f -C $MYBUILD; done

2.3 Build

Define some required environment variables. Just adjust SHIB_HOME if the target directory is somewhere else: 
export SHIB_HOME=/opt/shibboleth-sp-2.4.3
Create the target directory: 
mkdir $SHIB_HOME
1. Log4Shib: 
cd $MYBUILD/log4shib-1.0.4/
./configure --prefix=$SHIB_HOME --disable-static --disable-doxygen
make
make install
2. XML-Security:
xml-security 1.6.1 is required to be able to block weak crypto algorithms. 
cd $MYBUILD/xml-security-c-1.6.1/
./configure --prefix=$SHIB_HOME
make
make install
3. XML-Tooling: 
cd $MYBUILD/xmltooling-1.4.2/
./configure --prefix=$SHIB_HOME --with-log4shib=$SHIB_HOME --with-xmlsec=$SHIB_HOME -C
make
make install
4. OpenSAML: 
cd $MYBUILD/opensaml-2.4.3/
./configure --prefix=$SHIB_HOME --with-log4shib=$SHIB_HOME -C
make 
make install
5. Shibboleth Service Provider: 
cd $MYBUILD/shibboleth-2.4.3/
./configure --prefix=$SHIB_HOME --enable-apache-22 \
--with-log4shib=$SHIB_HOME --with-xmltooling=$SHIB_HOME --with-saml=$SHIB_HOME -C
make
make install

2.4 Define the current Shibboleth SP release

Create a symlink to the current installation: 
if [ -L /opt/shibboleth-sp] ; then rm /opt/shibboleth-sp ; fi;
ln -sf $SHIB_HOME /opt/shibboleth-sp

2.5 Shibboleth Apache module

Check the file /etc/apache2/mods-available/shib.load. You should have exactly this line in the file. Be careful that the path should contain shibboleth-sp and not shibboleth-sp2 or something else: 
# Load the shibboleth module

LoadModule mod_shib /opt/shibboleth-sp/lib/shibboleth/mod_shib_22.so
Enable the Shibboleth Apache module: 
a2enmod shib

2.6 Install Shibboleth daemon

Copy the distribution init script: 
cp $SHIB_HOME/etc/shibboleth/shibd-debian /etc/init.d/shibd
Adjust the init script: 
PATH=/sbin:/bin:/usr/sbin:/usr/bin
DESC="Shibboleth 2 daemon"
NAME=shibd
SHIB_HOME=/opt/shibboleth-sp
SHIBSP_CONFIG=/etc/shibboleth/shibboleth2.xml
LD_LIBRARY_PATH=$SHIB_HOME/lib
DAEMON=$SHIB_HOME/sbin/shibd
SCRIPTNAME=/etc/init.d/$NAME
PIDFILE=/var/run/$NAME.pid

...
Install the init script: 
chmod +x /etc/init.d/shibd
update-rc.d shibd defaults

2.7 Shibboleth service provider

The main configuration of the Shibboleth Service Provider is done in /etc/shibboleth/shibboleth2.xml.
Go to the 1. Setup Profile of the deployment guide, provide all the information about your environment, click on the Update Setup Profile button and from
the "Quick download of configuration files" section download the file /etc/shibboleth/shibboleth2.xml that now will contain all your info.
Store this file in /etc/shibboleth.

Download the attribute-map file, which contains the attribute definitions and defines the mapping from attributes to the web server HTTP environment variables: 
wget -nc https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/sp/deployment/download/attribute-map.xml \
-P /etc/shibboleth/

Download the attribute filtering policy: 
 wget -nc  https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/sp/deployment/download/attribute-policy.xml /
-P /etc/shibboleth/
Warning If you previously added specific configurations to your old shibboleth2.xml file or changed details in the attribute-map.xml or attribute-policy.xml, then you should reapply those changes manually to the new files.

3. Run & Test

Test the configuration file: 
/opt/shibboleth-sp/sbin/shibd -t -c /etc/shibboleth/shibboleth2.xml
Note If the output is only one line containing the following message, everything is as expected: 
overall configuration is loadable, check console for non-fatal problems
If there is any ERROR message it is strongly recommended to analyze and solve the problem. WARN messages should be examined and resolved as well, even if the generally indicate less serious problems.

Start the Shibboleth daemon: 
/etc/init.d/shibd restart
Test configuration and restart Apache: 
apache2ctl configtest
apache2ctl restart
Use the status URL https://your_service_provider.org/Shibboleth.sso/Status for a quick test. This URL returns basic information about the Service Provider setup as an XML document.
In case you haven't configured yet, this URL can only be access by localhost and the Resource Registry, the IP address of your host has to be added to the access control list (acl) of the Status
handler in /etc/shibboleth/shibboleth2.xml: 
...
<!-- Status reporting service. -->
<Handler type="Status" Location="/Status" acl="127.0.0.1 (add here your IPAddress)"/>
...
Warning If the acl attribute is removed, anyone is permited to access the status handler. Please consider that the status handler can return some potentially sensitive information about the setup including software and library version information. This information could be used by an attacker to compromise the system in the worst case.

4. References