Authors
Shaun Mangelsdorf
Applicable versions
Beta 1 (0.4)
Beta 2 (0.5, 0.5.2)
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:
- Extract saml2-0.5.2.tar.gz spep-0.5.2.tar.gz spepd-0.5.2.tar.gz and modspep-0.5.2.tar.gz to a directory suitable for building. You will need approximately 200mb free space on the filesystem for the build process.
- 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.
- 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.
- 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.
SPEP Registration
Navigate to the "Register Service" page of the ESOE Manager.
Enter values for the following fields:
| Field |
Description |
| Service name |
Human readable name for the service |
| Service URL |
Base URL or "home" of the service - the main entry point for a user agent |
| Service Identifier |
Identifier of the service must be a URI, generally this is the same as the value entered above |
| Service description |
A description of what the service does |
| Service Authz Failure |
A message to be displayed by the central authorization failure page when access to one of your resources has been denied. This may contain HTML markup. |
Click Next.
Add Service Contacts
Select the contact type from the list, and enter the other details for the contact.
When this is filled in, click "Save contact".
You may edit and delete contacts after they have been saved. After you have finished entering contacts, click Next.
Add Service Nodes
The "SPEPNode URL" is used as the base URL for the SPEP endpoints. The different service locations here are paths to the service endpoints, using the SPEPNode URL as a base.
Select the server technology you are using. The default values for the endpoint paths will work for a default SPEP deployment.
Click Save Node. You may add more nodes and edit or delete nodes that have already been added.
After you have finished entering nodes, click Next.
Finalize registration process
From this page you may check the information you have entered, and also navigate back to previous pages to make any alterations by clicking the Previous button.
Once you are happy with the configuration, click Complete.
Service configuration
Navigate to your service in the ESOE Manager application. Click on the "get service configuration" link. In the service description, click on the "service node configuration" link.
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.
Save the keystore file by clicking the "download keystore" link. 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
SPEPLogFile /desired/path/to/logs/modspep.log
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>
Logging
Currently the logging system used by C++ SPEP is somewhat simplistic. We anticipate having a more feature packed logging solution before we move to a stable 1.0 release.
Log output is generated in the files configured by the SPEPLogFile directive in httpd.conf, and on the command line of spepd.
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 point your browser at http[s]://<<server [:port]>/_your_app/
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.
