Manual Installation of Shibboleth Service Provider

Below are step-by-step instructions on building and configuring a Shibboleth SP on a Debian Linux system to be part of the MAMS Testbed Federation. A lot of the materials here follow the great documetations of the SwitchAAI project with modifications for our Tested Federation. The instructons are aimed at system administrators who are familiar with the operations of building modules for Apache 2 as well as deploying applications on Apache 2.

---

Prerequisites

• Debian Linux system: while the instructions below are specific to the Debian system, it should be quite simple for most administrators to modify it slightly for use on other Linux distributions such as SUSE or RedHat^?.

• GNU gcc/g++ compiler. It is recommended that gcc version 3.35 be used.

• Apache 2 with SSL and its development libraries. For Debian, the package apache2-threaded-dev provides the necessary Apache 2 development libraries and tools while libssl > 0.9.7 will provide the required openssl library support.

• A test account at an IdP in the Federation. This will allow you to test your SP installation.

• Ntp tools to synchronize time with a remote time server (eg. ntpdate)

• wget (or something similar) to download files from a webserver on a command line.

• A public IP address and a public DNS name for the systen.

• Firewall open for the following ports on the IdP machines:
  • TCP destination ports (ie. ports on the IdP machine) 80, 443.
  • UDP source port (ie. port on the remote host) 123.

---

Build and Install the Shibboleth Apache 2 Module

• Download the following packages into a temporary working directory:
  • Shibboleth SP: shibboleth-sp-1.3f.tar.gz
  • OpenSAML Library: opensaml-1.1a.tar.gz
  • Log4CPP Library: log4cpp-0.3.5rc1.tar.gz
  • Xerces-C++ Library: xerces-c-src_2_6_1.tar.gz
  • XML-Security C++: xml-security-c-1.2.1.tar.gz
• Make sure that you have the Debian libcurl library and development packages:

  • $apt-get install -t unstable libcurl3 libcurl3-dev

• Note that the above command may prompt you to install additional dependencies packages automatically for you.
• For the purpose of this install we will build Shibboleth SP and its required libraries in /usr/local/shibboleth-sp. We will refer to this directory as SHIB_SP_HOME:

  • $export SHIB_SP_HOME=/usr/local/shibboleth-sp

• Untar log4cpp-0.3.5rc1.tar.gz, go into that directory, configure and build it with the following:

apt-get -t unstable install gcc-3.3 g++-3.3
tar xzvf log4cpp-0.3.5rc1.tar.gz
cd log4cpp-0.3.5rc1
./configure --disable-static --without-ca-bundle --enable-thread --prefix=$SHIB_SP_HOME
make
make install

• Untar xerces-c-src_2_6_1.tar.gz, configure and build it with the following:

tar xvzf xerces-c-src_2_6_1.tar.gz
cd xerces-c-src_2_6_1
export XERCESCROOT=`pwd`
cd src/xercesc
./runConfigure -p linux -c gcc -x g++ -r pthread -P $SHIB_SP_HOME
make
make install

• Untar xml-security-c-1.2.1.tar.gz, configure and build it with the following:

tar xvzf xml-security-c-1.2.1.tar.gz
cd xml-security-c-1.2.1/src
./configure --prefix=$SHIB_SP_HOME --without-xalan
make
make install

• Untar opensaml-1.1a.tar.gz, configure and build it with the following:

tar xvzf opensaml-1.1a.tar.gz
cd opensaml-1.1
./configure --prefix=$SHIB_SP_HOME --with-log4cpp=$SHIB_SP_HOME -C
make
make install

• Untar shibboleth-sp-1.3e.tar.gz, configure and build it with the following:

tar xvzf shibboleth-sp-1.3e.tar.gz
cd shibboleth-1.3
./configure --prefix=$SHIB_SP_HOME --with-log4cpp=$SHIB_SP_HOME --enable-apache-20 --with-apxs2=/usr/bin/apxs2 --disable-mysql
make 
make install

• At this point Shibboleth SP Apache 2 module and the Shibboleth shibd daemon is built for your system.
• Make sure that you use --enable-apache-22 if you are compiling against Apache 2.2

Obtain SSL Certificate and the CA certificate

• If you already have certificates for your system (either from installing the IdP on the same system). you can skip this section on getting SSL certificate.

• To configure Apache 2 with SSL and also later for the SP, you need to first obtain a certificate. For Level-1 of the Testbed Federation, we accept certificates signed by commercial certificate authorities and by our own MAMS Testbed Federation Level-1 Certificate Authority. If you already have a commercial certificate, you can skip this section(however, you have to make sure that your commercial certificate has client-ssl purpose, otherwise SP back channel won't work. More info about how to obtain correct certificate, please refer to How to Migrate from Level 1 to Level 2 of the Testbed Federation). For Level 2 and Level 3 of the Testbed Federation we only accept certificates signed by commercial certicificate authorities.

• Generate a your key and certificate request using openssl:

mkdir /etc/certs && cd /etc/certs
openssl req -newkey rsa:1024 -nodes -keyout mykey.pem -out newreq.pem
cat newreq.pem

• • Make sure that when you answer the question above when it comes to setting the Common Name, you enter the machine's Fully Qualified Domain Name such as "myhost.edu.au"
• On the SP machine, open up a browser and go to this URL http://www.federation.org.au/CA/CA-sign.html
• Open the file newreq.pem with a text editor and copy the section between:

   -----BEGIN CERTIFICATE REQUEST-----

   ......                          

   -----END CERTIFICATE REQUEST----- 

• Make sure you also include the above lines when copying.
• Paste the information into the form on the browser and hit Submit. Copy the resultant certificate into a file and call it mycert.pem.
• Make sure that your SP user (or whatever user that you use for SP shibd daemon) has access to these certificate files
• Note that if you do not run the browser from the same machine as your SP, you will not be able to obtain a certificate
• Download the level-1 CA certificate from this URL: http://www.federation.org.au/level-1-ca.crt into /etc/certs directory
• Check that at this point you have the three files:
  • Your SP x509 certificate: mycert.pem
  • Your SP key: mykey.pem
  • Level-1 CA x509 certificate: level-1-ca.crt

Configuring Shibboleth SP

• Download and replace shibboleth.xml in $SHIB_SP_HOME/etc/shibboleth directory
• Edit the file shibboleth.xml and replace MY_DNS variable with the hostname of your SP machine
• Download and replace AAP.xml in $SHIB_SP_HOME/etc/shibboleth directory
• Ensure that cron service is enabled on your system.
• Install ntpdate time synchronization tool:

  • $apt-get install ntpdate

• Under the /etc/cron.hourly directory, create a new script, called ntpdate.sh, with the following content:

      #!/bin/sh

      /usr/sbin/ntpdate 128.250.37.2 129.127.28.4

• Note the above script uses the ntpdate command to update your system clock every hour so that your machine's clock is kept up to date.
• Make sure the script is executable, and then manually execute it for the first time.
• Manually download the Testbed Federation metadata for the first time.

  • $wget https://www.federation.org.au/level-1/level-1-metadata.xml -O /usr/local/shibboleth-sp/etc/shibboleth/level-1-metadata.xml

Shibboleth Startup Scripts

• Download the script, shibboleth, to start-up the shibboleth daemon automatically by placing it in /etc/init.d. Make sure to make the script executable and register it with the system startup:

  • $cd /etc/init.d/

  • $chmod u+x shibboleth

  • $update-rc.d shibboleth defaults

Install Shibboleth Apache 2.0 Module

• Create the Shibboleth configuration file, mod_shib.conf, /etc/apache2/mods-available directory, with the following:

cat -<<TEXT > /etc/apache2/mods-available/mod_shib.conf

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

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

• Create the Apache 2 configuration file that loads the Shibboleth module, mod_shib.load, also in the directory /etc/apache2/mods-available directory

cat -<<TEXT > /etc/apache2/mods-available/mod_shib.load
    #
    # Load Shibboleth module for Apache2
    #
    LoadModule mod_shib /usr/local/shibboleth-sp/libexec/mod_shib_20.so
TEXT

• Enable Shibboleth module with Apache 2:

  • $a2enmod mod_shib

• Apache 2 must be modified and the environment variable LD_LIBRARY_PATH set to be able to load the Shibboleth module. This is done by adding the following to /etc/apache2/envvars:

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

Protecting A Web Directory with Shibboleth

• Here we will test whether Shibboleth works by using it to protect static web contents.
• Create the directory in /var/www/secure. Inside that directory create a new file called index.html with any text you wish, e.g. "Hello World"
• In the file /etc/apache2/sites-enabled/000-default, add the following just before the closing VirtualHost^? element:

      <Location /secure>
         AuthType shibboleth
         ShibRequireSession On
         require valid-user
      </Location>

• Restart Shibboleth daemon and Apache 2 daemon:

  • $/etc/init.d/shibboleth start

  • $/etc/init.d/apache2 restart 

• Register yourself with the Federation if you have not done so. Add a new organization (if you haven't done so) and add a new SP to the organization. The details of your SP is:
  • Certificate CN: MY_DNS
  • Artifact Consumer Service URL: https://MY_DNS/Shibboleth.sso/SAML/Artifact
  • Assertion Consumer Service URL: https://MY_DNS/Shibboleth.sso/SAML/POST
  • Service URL: https://MY_DNS/secure
  • Federation Level: 1
  • You can leave the service desciption field empty
• Configure your system to regularly download the latest Federation metadata by following this guide here.
• Test your newly installed Shibboleth SP by opening a browser from you local computer and point it to the URL "http://MY_DNS/secure". When redirected to the WAYF, select the IdP where you have the test account, log in with your credentials and you should then see your test web page.

---

-- ChiNguyen - 15 Feb 2006
to top