simpleSAMLphp Installation and Configuration

Andreas Åkre Solberg

Mon Oct 15 16:54:59 2007


Table of Contents

The history of simpleSAMLphp
Contributors
Changelog
Version 0.5
Version 0.4
News about simpleSAMLphp
Download and install simpleSAMLphp
Getting a working copy of simpleSAMLphp from subversion
Making configuration and metadata files
Configuring apache
The simpleSAMLphp installation webpage
Next steps
A. Installing simpleSAMLphp in alternative locations

The history of simpleSAMLphp

simpleSAMLphp is an iteration of what was earlier referred to as lightbulb (Sun OpenSSO Extensions), written by Pat Patterson, Sun. There are not much code left from lightbulb, but credits go to Pat for introducing a new way of thinking when it comes to implementing federation protocols in a simple and elegant way.

The simpleSAMLphp project is currently led by Andreas Åkre Solberg, UNINETT.

The product is used to bridge AAI protocols in the GÉANT project, http://geant2.net.

We have received a bunch of external contributions.

Contributors

Thank you very much for your contributions to simpleSAMLphp:

  • Lukas Hammerle, SWITCH, Switzerland

  • Stefan Winter, Restena, Luxemborg

Changelog

Here is changes between simpleSAML versions. Look here if you are upgrading, to see if there are any changes to the config format.

Version 0.5

Released . Revision X.

Warning

Both config.php and metadata format is changed. Look at the templates to understand the new format.

  • Documentation is updated!

  • Metadata files have been more tidy. Removed unused entries. Look at the new templates on how to change your existing metadata.

  • Support for sending metadata on mail to Feide. Automatically detecting if you have configured Feide as the default IdP.

  • Improved SAML 2.0 Metadata generation

  • Added support for Shibboleth 1.3 IdP functionality.

  • Added RADIUS authentication backend

  • Added support for HTTP-Redirect debugging when enable debug=true

  • SAML 2.0 SP example now contains a logout page.

  • Added new authentication backend with support for multiple LDAP based on which organization the user selects.

  • Added SAML 2.0 Discovery Service

  • Initial proof of concept implementation of "User consent on attribute release"

  • Fixed some minor bugs.

Version 0.4

Released 2007-09-14. Revision X.

  • Improved documentation

  • Authentication plugin API. Only LDAP authenticaiton plugin is included, but it is now easier to implement your own plugin.

  • Added support for SAML 2.0 IdP to work with Google Apps for Education. Tested.

  • Initial implementation of SAML 2.0 Single Log-Out functionality both for SP and IdP. Seems to work, but not yet well-tested.

  • Added support for bridging SAML 2.0 to SAML 2.0.

  • Added some time skew offset to the NotBefore timestamp on the assertion, to allow some time skew between the SP and IdP.

  • Fixed Browser/POST page to automaticly submit, and have fall back functionality for user agents with no javascript support.

  • Fixed some bug with warning traversing Shibboleth 1.3 Assertions.

  • Fixed tabindex on the login page of the LDAP authentication module to allow you to tab from username, to password and then to submit.

  • Fixed bug on autodiscovering hostname in multihost environments.

  • Cleaned out some debug messages, and added a debug option in the configuration file. This debug option let's you turn on the possibility of showing all SAML messages to users in the web browser, and manually submit them.

  • Several minor bugfixes.

News about simpleSAMLphp

To get the latest news about simpleSAMLphp you can follow this url: http://rnd.feide.no/category/simplesamlphp/.

Currently simpleSAMLphp has a project page at Google Code:

http://code.google.com/p/simplesamlphp/

Download and install simpleSAMLphp

You can go to code.google.com/p/simplesamlphp/ to find the most recent release of simpleSAMLphp. Download the zipped file, and unzip it on your webserver. However I hightly reccomend running from a subversion checkout instead.

Getting a working copy of simpleSAMLphp from subversion

Go to the directory where you want to install simpleSAMLphp:

cd /var

Then do a subversion checkout:

svn checkout http://simplesamlphp.googlecode.com/svn/trunk/ simplesamlphp

If you know subversion you know how to view logs and review changes to the files. To update the version you have checked out, enter:

cd /var/simplesamlphp
svn up

Making configuration and metadata files

Configuration and metadata files are stored in a template format, you need to copy them to have your local copies. The reason why it is done this way, is that when you upgrade you can do svn up in subversion or just copy the whole directory over your installation, without replacing your existing configuration. When you are updating, you should investigate whether the config format is changed, this should be documented in the changelog.

Here are the steps you need to do to create local configuration files:

cd /var/simplesamlphp
cp config/config-template.php config/config.php
cp -r metadata-templates/*.php metadata/

Configuring apache

In this example simpleSAMLphp is located in /var/simplesamlphp, that is the default location. If you want to modify this location, you can do so freely, but then you need to update the path in a few files. I wrote a separate chapter about that, read on.

Of the folders inside simplesamlphp, only the www folder needs to be accessible from the web. There are several ways of putting the simpleSAMLphp depending on the way web sites are structured on your apache web server. Here is what I believe is the best configuration.

Find the apache configuration file for the virtual hosts that you want to run simpleSAML on. The configuration may look like this:

<VirtualHost  *>
        ServerName service.example.com
        DocumentRoot /var/www/service.example.com

        Alias /simplesaml /var/simplesamlphp/www
</VirtualHost>

What is special is the Alias directive. That directive will give control to simpleSAMLphp for all urls that matches http(s)://service.example.com/simplesaml/*. simpleSAMLphp will need to have several SAML interfaces available on the web, and all these interfaces are included in the www subdirectory of your simpleSAMLphp installation. You can set the alias to whatever you want, but this alias must be set in the config.php file of simpleSAML as described in ???. Here is an example of how this configuration may look like in config.php:

$config = array (
[...]
	'baseurlpath'			=> 'simplesaml/',

The simpleSAMLphp installation webpage

When you have installed simpleSAMLphp, you can access the homepage of your installation, which contains some information and a few links to the test services. The url of an installation can be in example:

https://service.example.com/simplesaml/

The exact link depends on how you set it up with apache and off course your hostname.

Warning

Don't click on any of the links yet, because they require you to eigther have setup simpleSAMLphp as an Service Provider or as an Identity Provider.

Here is an example screenshot of what the simpleSAMLphp page looks like:

Figure 1. Screenshot of the simpleSAMLphp installation page.

Screenshot of the simpleSAMLphp installation page.

Next steps

You have now successfully installed simpleSAMLphp, and the next steps depends on whether you want to setup a service provider, to protect a website with authentication or if you want to setup an identity provider and connect it to a user storage. We will also provide documentation on bridging federation protocols in a separate document.

A. Installing simpleSAMLphp in alternative locations

If you want to install simpleSAMLphp in an alternative directory, feel free to do so. You need to set the path of the installation directory in the config.php file:

$config = array (
[...]
	'basedir' 				=> '/usr/local/simplesaml/simplesamlphp',

And you also need to modify the Alias directive in the apache configuration:

        Alias /simplesaml /usr/local/simplesaml/simplesamlphp/www