Skip to main content Skip to navigation

IT Services

Getting started with new mode (non-Java)

Though we do not directly support the installation of other Shibboleth-compatible software, we know that others have been successful in installing it on their servers and using them to sign in to SSO. The following is a guide provided by Brian Foley on installing the Shibboleth software and then configuring it to speak to Warwick SSO. Though long, it's reasonably straightforward for a technical person to follow, but you will need to be able to install new software on the server in question.

This documentation is written for the 1.3 generation of Shibboleth, but the latest generation is 2. You can follow these instructions installing 1.3 as the newer versions are mostly backward compatible, but you should be aware that support from Shibboleth for their 1.3 software is expiring. It is recommended that you use 2 but you may have to adapt the instructions here, referring also to the instructions on the Shibboleth website.

Using Warwick's Web sign-on with Apache

Overview

Warwick's Single Sign-on system allows users both on and off campus to be identified and log in to a web site using only their IT Services usercode and password. The system is based on Internet2's Shibboleth project, and since Shibboleth provides an Apache authentication module, it is possible wrap Shibboleth authentication around portions of existing Apache web sites, and thus provide secure, authenticated access to web services at Warwick.

At a fairly high level, a Shibboleth authentication session looks like this:

  1. The user starts up their web browser and tries to access a page protected by Shibboleth.
  2. The Shibboleth Apache module talks to the Shibboleth daemon, sees that the user hasn't logged in yet (because it didn't send any Shibboleth session cookies) and automatically redirects the user to the 'Identity Provider' (IdP) web server. This happens in the browser via an automatically-posted form (the white screen you see briefly after signing in).
  3. The IdP (using the web sign-on page at Warwick) prompts the user to type in their usercode and password. If they are correct, the IdP posts information about the successful authentication back to a special URL on the original web server (usually something like https://example.com/Shibboleth.sso/SAML/POST).
  4. The Shibboleth Apache module handles requests to this URL and uses the information it gets from the IdP to set up a session, and stores the information it needs in its session cache. This cache is memory-based by default.
  5. Finally, the Shibboleth Apache module sets some session cookies and redirects the user to the resources they were originally trying to access.
  6. This time, the Shibboleth module gets the request, talks to the Shibboleth daemon, sees that the session cookies represent a logged in user, adds the appropriate Apache aliases and HTTP headers for use by scripts on the server side, and finally allows access to the original resource.
  7. Until the Shibboleth session expires (or the Shibboleth daemon restarts), every request from the user after this will have a proper session cookie, and will access the resource as in the previous step.

Since the communications between the IdP and the user involve passing around sensitive information (the usercode/password), the IdP sign-on page is only accessible using HTTPS.

Similarly, since the IdP sends sensitive authentication details back to the Shibboleth daemon (by the special URL on the service's web server), and the session cookies are also sent back and forth to the same server, a site that's secured with Shibboleth must use HTTPS also.

To configure Apache to work like this, you will need to do the following:

  1. Set up HTTPS and get an SSL certificate for your web server if you haven't already.
  2. Download, build and install Shibboleth and the libraries it requires.
  3. Configure the Shibboleth daemon to use IT Services's IdP.
  4. Load the shibboleth authentication module in your Apache configuration.
  5. Set up a test page that uses authentication.
  6. Get a provider ID from IT Services.

Set up HTTPS and get an SSL certificate

If your web server isn't configured to use HTTPS, you'll need to get this working before you can go any further. As described in the overview, to be able to authenticate securely, Shibboleth needs to use HTTPS communications. There are plenty of guides to setting up HTTPS with Apache on the Internet. Apache's documentation might be a good place to start. Alternatively, Googling for 'Apache HTTPS HowTo' also turns up useful results.

Download, build and install Shibboleth

If you are lucky, your computer may have a package management system that can install this and all the dependencies for you in a single command. It's recommended that you use such a managed package if available, because building stuff is a pain. Ubuntu and Debian have a package called libapache2-mod-shib2.

The Shibboleth daemon is a multi-threaded C++ application that depends on a number of libraries. It is important the that libraries be compiled with pthread support, otherwise shibd will crash randomly. For the purposes of these instructions, I'm going to assume that you want to install all these libraries and binaries in your home directory. If you don't, you'll need to modify commands appropriately. The build procedure below was used successfully on a 32-bit Intel RedHat Enterprise Linux 4 box with Apache 2.

  1. Shibboleth uses log4cpp, a log4J clone. Download the latest log4cpp (1.0currently).

    From the log4cpp directory, run the following commands to configure and install log4cpp:

    ./configure --disable-static --disable-doxygen --prefix=$HOME
make
make install
  2. Shibboleth uses xerces-c to parse the XML received from the IdP. Download the latest version of xerces-c.

    Xerces-C++ has a slightly nonstandard build system, so the instructions are a little unusual. Note that the '-r pthread' option is crucial, otherwise shibd will crash randomly. Also the configuration options assume you're using a 32 bit Linux platform. If you're not, you'll need to modify the options accordingly. Unpack the source code, and run the following commands:

    export XERCESCROOT=full path of the directory called xerces-c-src_2_7_0
cd src/xercesc
./runConfigure -p linux -c gcc -x g++ -r pthread -b 32 -P $HOME
make
make install
  3. Shibboleth uses xml-security-c to handle signed and encrypted XML responses from the IdP. Download the latest version of xml-security-c.

    From the xml-security-c-1.2.1 directory run the following commands:

    cd src
./configure --without-xalan --prefix=$HOME
make
make install
  4. Shibboleth is based on the SAML protocol, and uses the OpenSAML package. Download the latest version of the C++ source of OpenSAML.

    Unpack opensaml-1.1a, and from the opensaml-1.1a directory run the following commands:

    ./configure --with-log4cpp=$HOME --with-xerces=$HOME --with-xmlsec=$HOME --prefix=$HOME
make
make install
  5. Finally, we can build Shibboleth itself. Download the source for the latest service provider or the 1.3 service provider(this documentation only covers 1.3 versions - 2.0 is recommended if you are prepared to take the initiative of referring to the official Shibboleth documentation). Unpack shibboleth-1.3f, and from the shibboleth-1.3f directory run the following commands. Note that the configuration assumes you're using Apache 2.0 and that Apache's apxs tool is in /usr/sbin. If this isn't true, modify the options accordingly.
    ./configure --with-log4cpp=$HOME --with-xerces=$HOME --with-xmlsec=$HOME --with-saml=$HOME \
            --with-apxs2=/usr/sbin/apxs --enable-apache-20 --prefix=$HOME
make
make install

If you succeeded with all of this, congratulations! Now go and have a coffee break :)

Configure the Shibboleth daemon to use IT Services's IdP

This step will involve editing two configuration files. One will tell Shibboleth where to go on your web site when doing authentication, and how it should set up sessions. The other describes the IdP itself. Assuming you installed Shibboleth as described in the build instructions, all the configuration files are stored in $HOME/etc/shibboleth/.

To describe what portions of the the XML files need to be edited, we will use some simple XPath notation. In XPath '/HTML/HEAD/TITLE' means all the XML elements called TITLE found under any HEAD element inside any HTML element in our XML document. Similarly '/HTML/BODY/A/@HREF means the HREF attribute under any A element in any BODY element inside any HTML element in our document.

By way of example, our service will be a Wiki running on "https://wiki.dcs.warwick.ac.uk/cs118wiki/"

Make a copy of "shibboleth.xml.dist" called "shibboleth.xml". Edit shibboleth.xml and make the following changes:

  1. /SPConfig/Local/RequestMapProvider/RequestMap/Host/@name is currently set to "sp.example.org", change it to the hostname of your web server eg "wiki.dcs.warwick.ac.uk". /SPConfig/Local/RequestMapProvider/RequestMap/Host/Path/@name is currently set to "secure", change it to the path to your service, eg "cs118wiki". These changes tell Shibboleth where to find the web service.
  2. Remove the entire /SPConfig/Local/Implementation/ element; we're not using Microsoft IIS, so it doesn't concern us.
  3. The main changes occur under /SPConfig/Applications/. Later, we'll have to get a proper provider ID from IT services, and change /SPConfig/Applications/@providerId from "https://sp.example.org/shibboleth" to this. The ID is used so the IdP can decide whether you are running a service that it is allowed to give authentication information to. Warwick use a URN that looks something like "urn:wiki.dcs.warwick.ac.uk:wiki:service". For the moment, don't worry about it. Change /SPConfig/Applications/@homeURL from "https://sp.example.org/index.html" to the base URL of your service, eg "https://wiki.dcs.warwick.ac.uk/cs118wiki/".
  4. Change /SPConfig/Applications/Sessions/@handlerSSL from "false" to "true". This instructs Shibboleth to use secure communications with the IdP.
  5. There are two /SPConfig/Applications/Sessions/SessionInitiator elements. Delete the second one, the change the Location attribute in the first from "/WAYF/idp.example.org" to "/Shibboleth.sso/WAYF/websignon.warwick.ac.uk" and change wayfURL from "https://idp.example.org/shibboleth-idp/SSO" to "https://websignon.warwick.ac.uk/origin/hs". This tells Shibboleth to redirect users to the web sign-on page to be authenticated.
  6. Change /SPConfig/Applications/Errors/@supportContact from "root@localhost" to an email address where the administrator for the service can be contacted. The address is displayed in error pages in the client's web browser if Shibboleth fails for some reason.
  7. There are two /SPConfig/Applications/MetadataProvider/ elements. Delete the second. In the first change the uri attribute from "example-metadata.xml" to "warwick-idp-metadata.xml". This is the filename of the configuration file we'll set up next that holds information about Warwick's IdP.
  8. Under /SPConfig/CredentialsProvider/FileResolver/, change the two paths to point at the files that hold the Certificate and Certificate Key files used for SSL on your webserver. These will be the same files that are used with the 'SSLCertificateFile' and 'SSLCertificateKeyFile' directives in your Apache configuration.
  9. Finally, delete the /SPConfig/AttributeFactory element. We don't use it.

OK. Now the Shibboleth module should know how to handle redirects to the IdP and back to your web service. Next, we'll tell it about the IdP itself.

Make a copy of "example-metadata.xml" called "warwick-idp-metadata.xml". Edit it and make these changes:

  1. Change /EntitiesDescriptor/EntityDescriptor/@entityID from "https://idp.example.org/shibboleth" to "urn:mace:eduserv.org.uk:athens:provider:warwick.ac.uk".
  2. There are two /EntitiesDescriptor/EntityDescriptor/IDPSSODescriptor/Extensions/shibmd:Scope/ elements. Delete one, and change the text inside the other from example.org to warwick.ac.uk.
  3. We need to get the server certificate used by the IdP. On UNIX this can be done from the command line, using the command openssl s_client -connect websignon.warwick.ac.uk:443. The certificate itself is the text between the "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" lines. There are two /EntitiesDescriptor/EntityDescriptor/IDPSSODescriptor/KeyDescriptor/ elements. Delete one, and put the certificate text inside the ds:X509Certificate element of the other. To check that we've copied all the text correctly, the certificate should begin with the characters "MII" and end with an "=".
  4. Delete both /EntitiesDescriptor/EntityDescriptor/ArtifactResolutionService/ elements. We don't use them.
  5. There are two /EntitiesDescriptor/EntityDescriptor/SingleSignOnService/ elements. Delete one, and change the Location attribute in the other to "https://websignon.warwick.ac.uk/origin/hs"
  6. Under /EntitiesDescriptor/EntityDescriptor/AttributeAuthorityDescriptor/ we need to make similar changes to the ones we made to /EntitiesDescriptor/EntityDescriptor/IDPSSODescriptor/. Remove one of the /EntitiesDescriptor/EntityDescriptor/AttributeAuthorityDescriptor/Extensions/shibmd:Scope/ elements, and change the text inside the other from example.org to warwick.ac.uk. Also, remove one of the /EntitiesDescriptor/EntityDescriptor/AttributeAuthorityDescriptor/KeyDescriptor/ elements, and change the certificate in the other as we did earlier.
  7. There are two /EntitiesDescriptor/EntityDescriptor/AttributeAuthorityDescriptor/AttributeService/ elements. Delete one, and change the Location attribute in the other to "https://websignon.warwick.ac.uk/origin/aa". This tells the Shibboleth daemon where to ask for Attributes about an authenticated user. (Attributes are just metadata about the user. At Warwick this includes things like their full name, what department they're in etc. IT Services maintain a list of Attributes).
  8. Lastly change the user friendly text under /EntitiesDescriptor/EntityDescriptor/Organization/ to something appropriate like "Warwick Identity Provider", "Warwick Web Sign-on" and "http://www.warwick.ac.uk/".

Load the Shibboleth authentication module in Apache

This can be done by adding the contents of $HOME/etc/shiboleth/apache2.config to the end of your Apache configuration, and then restarting Apache. Remove the '<Location /secure>' from you configuration and add the following:

	<Location /Shibboleth.sso>
		SetHandler shib-handler
	</Location>

Set up a test page in Apache

Assuming you're using PHP, the easiest way to test Shibboleth authentication is to create a temporary directory on your webserver, and put a file in it called test.php. In that file put this text:

	<?php
		phpinfo();
	?>

Add something like the following to your Apache configuration[...]

Get a provider ID from IT Services

Register your application

Configure the AAP settings in Shibboleth

When the IdP authenticates a user, it passes back to the Shibboleth daemon a list of attributes describing the user. Shibboleth can be configured to make those attributes available for use as Apache security directives, or as HTML headers which can be processed by CGI scripts. Create a copy AAP.xml.dist called AAP.xml, and replace everything inside the AttributeAcceptancePolicy element with:

    <AttributeRule Namespace="urn:warwick:websignon" Name="cn"
        Header="Shib-userid" Alias="userid">
        <AnySite> <AnyValue/> </AnySite>
    </AttributeRule>

    <AttributeRule Namespace="urn:warwick:websignon" Name="givenName"
        Header="Shib-givenname" Alias="givenname">
        <AnySite> <AnyValue/> </AnySite>
    </AttributeRule>

    <AttributeRule Namespace="urn:warwick:websignon" Name="sn"
        Header="Shib-surname" Alias="surname">
        <AnySite> <AnyValue/> </AnySite>
    </AttributeRule>

    <AttributeRule Namespace="urn:warwick:websignon" Name="mail"
        Header="Shib-email" Alias="email">
        <AnySite> <AnyValue/> </AnySite>
    </AttributeRule>

    <AttributeRule Namespace="urn:warwick:websignon" Name="warwickdeptcode"
        Header="Shib-warwickdeptcode" Alias="warwickdeptcode">
        <AnySite> <AnyValue/> </AnySite>
    </AttributeRule>

The Header XML attribute in each AttributeRule element defines the name of the HTTP header set on the server if that attribute is found. The alias XML attribute says what name the attribute should map to in Apache. So, for example, with the configuration about the user's department code should be accessible in a PHP script by reading $_SERVER['HTTP_SHIB_WARWICKDEPTCODE'], and in Apache you can add directives like Require warwickdeptcode CS or Require mail ~ @warwick.ac.uk$