Installing a Shibboleth Target

Installing a Shibboleth Target can be broken down into three stages. The installation results in getting a service provider to use Shibboleth in order to identify users and authorise use.

Installing the software

Installing Shibboleth software has been convered in more detail in other documentation produced by the IAMSECT project[2]. The following steps will allow you to complete an installation from source.

Sources and software

The SWITCH install documentation[3] offers a succinct set of instructions for installing the pre-requisite software. There is little there which is debian-specific. The following software can be installed from the vendor or the software author:

  • gcc, g++, make etc. – to build the source packages

  • apache(-dev) : i.e. webserver + apxs (either 1 or 2)

  • libssl(-dev)

  • libcurl

  • libxml-security-c

  • mod_ssl

The following software must be obtained from http://wayf.internet2.edu/shibboleth/

  • log4cpp – via shib because the project is in a ‘limbo state’

  • xerces-c – latest official xerces-c release has a bug which breaks shib. This version doesn’t

  • opensaml

  • shibboleth

Installation order

The software must be installed in the following order: first gcc, g++, make etc., then apache + apache-dev (axps), followed by libssl + libssl-dev (headers), and finally libcurl.

Debian:

# aptitude install c++-compiler make apache apache-dev libssl-dev libcurl-dev libapache-mod-ssl

Redhat/fedora:

# up2date g++ gcc make httpd httpd-devel openssl openssl-devel curl curl-devel mod_ssl

Next, prepare the directory where the other software goes

# mkdir -p /opt/shibboleth-1.2.1
# cd /opt
# ln -s shibboleth-1.2.1 shibboleth
# cd shibboleth
        

log4cpp

# wget http://wayf.internet2.edu/shibboleth/log4cpp-0.3.5rc1.tar.gz
# tar xvzf log4cpp-0.3.5rc1.tar.gz # cd log4cpp-0.3.5rc1
# ./configure --prefix=/opt/shibboleth --with-pthreads --disable-static --disable-doxygen 
# make && make install
        

xerces-c

# wget http://wayf.internet2.edu/shibboleth/xerces-c-src_2_6_1.tar.gz 
# 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 -r pthread -P /opt/shibboleth
# make && make install 
# cd ../../..
        

Note

The -c and -x args, defining the C and C++ compilers, can be dropped if they are the default ones on the system anyway (and should be on any of the targets to set up)

libxml-security-c

# wget \
http://xml.apache.org/dist/security/c-library/old/xml-security-c-1.1.0.tar.gz
# tar xvzf xml-security-c-1.1.0.tar.gz 
# cd xml-security-c-1.1.0/src 
# ./configure --prefix=/opt/shibboleth --without-xalan
# make && make install 
# cd ../..
          

Note

The above relies on the variable $XERCESCROOT defined in the previous section, just in case you do things in a different order

opensaml

# wget http://wayf.internet2.edu/shibboleth/archive/opensaml-1.0.1.tar.gz
# tar xvzf opensaml-1.0.1.tar.gz # cd opensaml-1.0.1
# ./configure --prefix=/opt/shibboleth   \
             --with-curl=/opt/shibboleth \
             --with-log4cpp=/opt/shibboleth
# make && make install 
# cd ..
          

shibboleth

# wget http://wayf.internet2.edu/shibboleth/archive/shibboleth-1.2.1a.tar.gz
# tar xvzf shibboleth-1.2.1a.tar.gz 
# cd shibboleth-1.2.1 
# ./configure --prefix=/opt/shibboleth \
              --enable-apache-20 \
              --with-apxs2 \
              --with-log4cpp=/opt/shibboleth-1.2.1
# make && make install
          

Note

for apache 1.x, use --enable-apache --with-apxs rather than --enable-apache-20 --with-apxs2.

Test install

Visit the URL of your protected resource. You should be sent off to your origin and asked to log in. On successful login, you should be directed back towards the target, and see the desired page. If the desired page prints out environment variables as suggested, you should see some that correspond to attributes that the origin is releasing.

Setting up a dummy service

In order to test the target software, you need a site setup to protect. A simple ‘hello world’ page would suffice but isn’t very interesting. You could use the following to provide a shibboleth-protected server status page:

      <Location /server-status> 
       SetHandler server-status 
       AuthType shibboleth 
       ShibRequireSession On 
       require valid-user 
      </Location>
      

Another good choice would be a CGI or PHP script (or similar) which will print out the environment variables. The following PHP script for example

<?php phpinfo(); ?>

Then, the attributes that are provided to the application will be visible on the page.

After following this configuration list, test install again, as in the section called “Test install”.

Getting the Shibboleth configuration right

ADD TEXT: what are we configuring? what are our expectations for the target?

Log permissions
root# cd /opt/shibboleth-1.2.1/var/log 
root# chown root:apache shibboleth 
root# chmod 775 shibboleth
        

Where ‘apache’ is the username the httpd runs under. `apache’ on redhat; `www-data’ on debian; /opt/shibboleth-1.2.1 is the root under which the shibboleth-specific software was installed.

Paths

Type the following in .profile:

source ~/.bashrc

Stick the following in .bashrc:

export PATH=/opt/shibboleth/bin:$PATH
Initialisation scripts

The system init scripts need adjusting, so that:

  • apache is able to load the Shibboleth libraries on startup

  • apache is started after the shibd component of Shibboleth

This is achieved by modifying the /etc/init.d/apachescript (plus indicates added lines):

          ... 
          start() }
           echo -n $"Starting $prog: " 
           check13 || exit 1 
          + export LD_LIBRARY_PATH=/opt/shibboleth/lib
           LANG=$HTTPD_LANG daemon $httpd $OPTIONS 
           RETVAL=$? 
           echo 
          ...
          
shibd init script

An example init script for starting and stopping the shibboleth daemon component can be found in the Appendix. see the section called “Sample shibd init script”.

More apache

Include configuration items relevant to shibboleth

ln -s /opt/shibboleth/etc/shibboleth/apache2.config \
/etc/httpd/conf.d/shibboleth.conf

If you find apache won’t start up and you get `permission denied’ errors, check the section called “Error Messages and Solutions”.

Keys

There should be a /etc/httpd/conf.d/ssl.conf file. This defines SSL settings including certificate and private key. Visiting https://yourserver/ should bring up the redhat test page, after you’ve clicked past some certificate warnings.

You are going to want to change these keys for something else, either real keys provided by a top-level Certificate Authority, keys provided by a federation you are operating within (e.g. SDSS Test Federation) or a self-signed or internally-issued set.

Once you’ve obtained your replacement key and certificate, change the ssl.conf file to reference them and restart apache. Re-visit the https url and look at the cert in the browser. If necessary, once you’ve confirmed it's the right one, add it to your browser’s list of trusted certificates permanently. This will reduce the number of pop-up windows that occur during testing.

Shibboleth
  • WAYF URL

    As suggested by the shibboleth.xml file, the default wayfURL is the In Queue federation’s service. Change to https://your-handle-server/shibboleth/HS for internal testing against your own origin.

    --> 
                     <Sessions lifetime="7200" timeout="3600"
                    checkAddress="true" 
    
                    - wayfURL="https://wayf.internet2.edu/InQueue/WAYF"
                    + wayfURL="https://lock.ncl.ac.uk/shibboleth/HS"
    
                     shireURL="/Shibboleth.shire"
                    shireSSL="false"/> 
                    <!--
    
  • choice of providerId

    The main application element’s providerId attribute must be changed to a URI chosen by the deployer to uniquely identify the service.

    i.e. in our example, providerId becomes providerId="https://webdev2.ncl.ac.uk/shibboleth/target"

    Note

    The providerId must match the the Name attribute in the Destinationsite tag in the federation’s sites.xml (or the sites.xml that the origin you are using has)

  • target certificates

    The target, by default, uses shibd.key and shibd.crt supplied in the shibboleth source. We need to get hold of a new keypair which is more secure and trusted by the origin. You may get one from a federation provider, or a CA which is trusted by your federation, or you could use Self Signed Certificates. From http://shibboleth.internet2.edu/guides/deploy-guide-target.html:

    • The only target component that must have a private key and certificate is the shibd.

    • it is mandatory for the shibd to authenticate when contacting an AA

    • certificate is signed by a CA accepted by the origin site

    • The shibd is assigned a key and a certificate using shibboleth.xml’s File Resolver element

    To make the shibd use your new keypair:

                     <Credentials
                    xmlns="urn:mace:shibboleth:credentials:1.0"> 
                     <FileResolver Id="defcreds"> 
                     <Key format="PEM"> 
                    - <Path>/opt/shibboleth-1.2.1/etc/shibboleth/shibd.key</Path>
                    + <Path>/opt/shibboleth/self-signed/ssl.key</Path>
                     </Key> 
                     <Certificate format="PEM"> 
                    - <Path>/opt/shibboleth-1.2.1/etc/shibboleth/shibd.crt</Path>
                    + <Path>/opt/shibboleth/self-signed/ssl.crt</Path>
                     </Certificate> 
                     </FileResolver>
                     
    

    We have omitted how to make the IdP trust these keys. In most cases it is not necessary as you will end up using the Federation (in this case SDSS-provided) keys. In this case also the SDSS CA was already trusted by our origin.

    Federation Provider and Trust Provider elements must be added or changed as needed to reflect the arrangements required. This information is often provided by federations to their members[4]

Getting the service to work with Shibboleth

Getting the service (Blackboard, Zope) to accept information from shibboleth and use it in some way: i.e. identify the user by their attributes, etc., is the final step in the set up. The amount of work involved in getting a particular service to work with Shibboleth is completely dependent on the service. This article goes on to decribe (in sections 3 and 4) how this process works for two VLEs, Blackboard and Zope.



[2] IAMSECT project documentation is available from http://iamsect.ncl.ac.uk/deliverables/

[3] http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.2/install-target-1.2.1-debian.html

[4] Quote from http://sdss.ac.uk/wiki/wiki.pl?SetupServiceProvider