Workshop 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 system.

• 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

• All the necessary libraries are already download and located at /usr/src. They are shibboleth-sp-1.3f.tar.gz, opensaml-1.1a.tar.gz, log4cpp-0.3.5rc1.tar.gz, xerces-c-src_2_6_1.tar.gz, xml-security-c-1.2.1.tar.gz)
• make the symlink to the folder (if not yet existed) in your /root folder

   ln -s /usr/src /root/software

• libcurl3 and its dependencies have been installed on your system, if not you can always do

   apt-get install -t unstable libcurl3 libcurl3-dev

• gcc-3.3 has also been installed in your system
• 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, configure and build it with the following:

cd /root/software
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`
echo $XERCESCROOT
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.3f.tar.gz, configure and build it with the following:

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

• • note on above, we're using apache2.2, hence the need to put --enable-apache-22 otherwise if you use apache2 then you need to use --enable-apache-20

• At this point Shibboleth SP Apache 2 module and the Shibboleth shibd daemon is built for your system.

---

Obtain SSL Certificate and the CA certificate (SKIP this if you've done it on IdP)

• 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. 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 "wsXX.mams.local" where XX is your group number.
• open up a browser and go to this URL http://www.federation.mams.local/mams-ca/CA-mams-sign.html with username workshop and passwd w0rksh0p
• 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
• 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 all occurrences of MY_DNS variable with the hostname of your SP machine
• Download and replace AAP.xml in $SHIB_SP_HOME/etc/shibboleth directory
• Your vmware is fully configured with ntpdate to synchronize its time correctly. You may want to configure it differently when you configure at your home institution.
• Manually download the Testbed Federation metadata for the first time.

  •  wget http://federation.mams.local/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/

  •  wget http://www.federation.org.au/twiki/pub/Federation/ManualInstallSP/shibboleth 

  •  chmod u+x shibboleth

  •  update-rc.d shibboleth defaults

Install Shibboleth Apache Module

• Create (or make sure its content the same) the Shibboleth configuration file /etc/apache2/mods-available/mod_shib.conf with the following:

  # 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>
  

• Create (or make sure its content the same) the Apache 2 configuration file that loads the Shibboleth module /etc/apache2/mods-available/mod_shib.load

    #
    # Load Shibboleth module for Apache2
    #
    LoadModule mod_shib /usr/local/shibboleth-sp/libexec/mod_shib_22.so

• 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 (make sure it has this content):

   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/003*, 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 

  •  ps aux|grep shib 

  • if you dont see the shib process, then something is not right, try to run it manually and see what's going on (refer to FAQ if failing)

    /usr/local/shibboleth-sp/sbin/shibd -fc /usr/local/shibboleth-sp/etc/shibboleth/shibboleth.xml

• Register yourself with the Federation (http://www.federation.org.au/FedManager/jsp/admin-main.jsp) 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 (use the IdP that you setup earlier with username staff and passwd test ) and you should then see your test web page.
• Other IdP available for testing (only access these IdPs outside of workshop environment as workshop machines are only available in local network):
  • idp: IDP-LDAP
  • username: staff, pgresearcher, librarian
  • password: test

• • idp: TestFed OpenIdP
  • username: register yourself on http://openidp.federation.org.au
  • password: your created password on registration

---

to top