Apache SPEP Installation Guide

Authors
Shaun Mangelsdorf

Applicable versions
0.7

Preparing your server

To successfully operate the Apache SPEP your server must be accessible on port 443 from the ESOE system. You can ask your ESOE system administrator for the IP addresses ESOE will connect from if you're running a restrictive firewall policy and update it appropriately. In some circumstances your administrator may allow you to configure port 80 unsecured SPEP instances. This is a per installation decision, on which your ESOE system administrator can advise you.

Minor change required to ESOE
There is a small change required to the ESOE environment to support Apache SPEPs, due to a bug in the Java libraries related to XML signature validation. This change requires that the commons-logging and xmlsec jar files are moved from $TOMCAT/shared/lib to $TOMCAT/common/endorsed.

Upgrading from pre-Beta 1 versions of the Apache SPEP
There has been considerable change to the configuration process, along with the ability to now use Java keystores rather than having to extract the keys into files manually. We recommend that anyone upgrading from a pre-0.4 version rewrite their configuration file from the default provided.

Build Prerequisites:

The source distribution of SPEP consists of 4 gziped tared files:

  1. Extract saml2-{version}.tar.gz spep-{version}.tar.gz spepd-{version}.tar.gz and modspep-{version}.tar.gz to a directory suitable for building. You will need approximately 200mb free space on the filesystem for the build process.
  2. The 4 source trees extracted all have a GNU standard configure script and Makefile. Note that if you have any of the required libraries installed in non-standard locations you will need to provide --with parameters to configure. See ./configure --help for more information.
  3. Build the source by running the configure script in a manner suitable for your system, then running make install to build and install the files.
  4. For the purposes of the rest of this document, we will refer to the prefix of your installation as $prefix. This defaults to /usr/local and is changed by the --prefix parameter to the configure script.

Registering the SPEP with ESOE Manager

Ask your ESOE administrator, or see this page for information if you manage your ESOE instance.

Service configuration

Retrieve your service configuration and keystore from ESOE Manager, or from your ESOE administrator.

This page shows you the configuration values that need to be set up in the spep.conf file, which can be found at $prefix/etc/spep/

You may also need to change the path information in the spep.conf file, if you installed the SPEP to a non-standard location.

For each of the configuration options shown by the ESOE Manager service node configuration page, enter the corresponding value for the current node in its spep.conf file.

It is very important that each node's configuration be correct. There will be some differences between them.

The keystore will be the same for all nodes. We recommend that you save the keystore to the same location as spep.conf and set it to be owned by the user that will run spepd. This keystore does not need to be read by the Apache module, so 0600 permissions are highly recommended.

Running the SPEP Daemon

The command line options for the SPEP daemon are:

spepd options:
  --help                   display this help message
  -f [ --config-file ] arg the spepd configuration file to use
  -l [ --log-file ] arg    file to send log output to
  --debug                  run in debug mode (don't fork to become daemon)
  -v [ --verbose ]         run in verbose mode (display some messages on
                           startup to describe what is happening)

Protecting your web content

After copying modspep.so into your apache modules directory, add the following statement to enable it:

LoadModule spep_module modules/modspep.so

Note the path to the module may differ slightly if your apache installation differs from the default.

Add the following options to the root of your httpd.conf (Outside any Directory/Location sections)
SPEPDaemonPort 7142

The daemon port here should correspond to the value configured in spep.conf earlier. The log file specified here should be a different file to the one that spepd logs to.

As an example, here is the configuration required to protect all web content under /secure
<Location /secure>
    SPEPEnabled On
</Location>

Run the environment

Your environment is now able to be started, we recommend you watch logging closely for the first little while to make sure all configuration is in order. To invoke spep simply browse to the protected web application.

Feedback

We aim to continually improve this documentation set to make it as easy as possible for new users and seasoned users alike to setup an SPEP. We welcome any comments or additions you may have on the ESOE users mailing list at any time.

Also available in: HTML TXT