Available in 1.11 1.10 1.9 1.8 1.7 1.6 1.5

Connecting SimpleSAMLphp SP to UK Access Federation and InCommon

Table of Contents

This guide will describe how to configure simpleSAMLphp as a service provider (SP) supporting SAML 1.1 (shib1.3) and SAML 2.0 connecting it to a federation such as UK Access Federation or InCommon.

You should previously have installed simpleSAMLphp as described in the simpleSAMLphp installation instructions.

1 Configuring the SP

The SP is configured by an entry in config/authsources.php. If you copy the authsources.php configuration from config-templates, it contains a decent default setup.

Further details on configuring an SP:

1.1 Enabling a certificate for your Service Provider

UK Access Federation and InCommon probably requires that you enable a certificate for your SP. Other federations do not always require that you do.

If you enable a certificate for your Service Provider, it may be able to sign requests and response sent to the Identity Provider, as well as receiving encrypted responses.

Create a self-signed certificate in the cert/ directory.

cd cert
openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem

Then edit your authsources.php entry, and add references to your certificate:

'default-sp' => array(
    'privatekey' => 'saml.pem',
    'certificate' => 'saml.crt',

2 Consuming Federation Metadata

In order to enable the functionality to automatically download and parse metadata from a remote URL, enable the metarefresh and cron modules:

touch modules/metarefresh/enable
cp modules/metarefresh/config-templates/*.php config/
touch modules/cron/enable
cp modules/cron/config-templates/*.php config/

Create a directory to cache the downloaded federation metadata:

mkdir metadata/metarefresh-ukaccess
chmod go+rw metadata/metarefresh-ukaccess

The module metarefresh is responsible for getting metadata from a preconfigured URL, and then parse and validate it and cache it for use with the SAML SP module.

Edit the config/config-metarefresh.php:

$config = array(
    'sets' => array(
        'uk' => array(
            'cron'      => array('hourly'),
            'sources'   => array(
                    'src' => 'http://metadata.ukfederation.org.uk/ukfederation-metadata.xml',
                    'validateFingerprint' => 'D0:E8:40:25:F0:B1:2A:CC:74:22:ED:C3:87:04:BC:29:BB:7B:9A:40',
            'expireAfter'       => 60*60*24*4, // Maximum 4 days cache time.
            'outputDir'     => 'metadata/metarefresh-ukaccess/',
            'outputFormat' => 'serialize',

The example above is from UK Access Federation. If you instead would like to get metadata from InCommon, use the following URL and fingerprint:

'src' => 'http://wayf.incommonfederation.org/InCommon/InCommon-metadata.xml',
'validateFingerprint' => '74278f967cf1bfcaaa1b41afb6336448a2150eb4',    

Notice that the configuration points the outputDir to the directory we created earlier. Now, we configure the SAML SP to use the cached outputDir as one of its metadata sources. Edit config.php:

'metadata.sources' => array(
    array('type' => 'flatfile'),
    array('type' => 'serialize', 'directory' => 'metadata/metarefresh-ukaccess'),

Now, go to the frontpage of your simpleSAMLphp installation, and:

  1. ConfigurationCron module information page.
  2. You then would need to enter that admin password that you did set in config.php during installation.
  3. Run cron [hourly]

Then the page should load for a while and show no errors, only a white page. (These URLs are meant to run from cron, hence no output). If this operation seems to run fine, navigate to the SimpleSAMLphp Front pageFederation. Here you should see a list of all trusted Identity Providers. The Identity Providers that are downloaded are listed with information about the valid cache duration, such as (expires in 96.0 hours).

For more details on how to configure automated metadata:

For information on how to configure remote metadata manually (possibly in combination with automated metadata as described here):

3 Exchange metadata with the Federation

In order to connect your Service Provider to the IdPs of the federations, the IdPs will need to trust your Service Provider. The prodecure for managing trust in federations differ, but the common part is that you would need to prepare SAML 2.0 metadata for your SP, and register that with the federation administration.

SimpleSAMLphp will automatically suggest metadata for your SP. Go to the SimpleSAMLphp Front pageFederation. Here you will see an entry with SAML 2.0 SP Metadata. If you follow the link [ Show metadata ], you will see a page listing metadata for your entity. You may copy and paste the SAML 2.0 metadata document, or send a link to this page to the federation administration.

4 Test the SP

After the metadata is is configured on the IdP, you should be able to test your SP.

Go to the SimpleSAMLphp Front PageAuthenticationTest configured authentication sources. You will then see a list of authentication sources that you may test. Select the authentication source ID for your SAML 2.0 SP. If you have not modified the authsources.php template, the ID is default-sp. When you click that link you should see a discovery service list of all Identity Providers.

For a better looking more advanced Discovery Service with tabs and live search, you should use the discopower module in simpleSAMLphp that is part of the official simpleSAMLphp release.

5 Integrating authentication with your own application

6 Caveat

In federations like UK Access Federations different aspects of the SAML protocol is in use, and here follows some information about what should work with SimpleSAMLphp and what will not work.

SimpleSAMLphp SP supports SAML 1.1, compatible with Shibboleth 1.3:

SimpleSAMLphp SP supports SAML 2.0, compatible with Shibboleth 2.X:

Important about certificates: SimpleSAMLphp as an SP requires that Identity Providers have embedded certificates in metadata. Most federations use emebedded certificates, and others are migrating to use embedded certificates. Some federations though are using PKI, relying on a list of trusted CAs and no embedded certificates in metadata - this setup is not supported by simpleSAMLphp.

7 Support

If you need help to make this work, or want to discuss simpleSAMLphp with other users of the software, you are fortunate: Around simpleSAMLphp there is a great Open source community, and you are welcome to join! The forums are open for you to ask questions, contribute answers other further questions, request improvements or contribute with code or plugins of your own.

More information about the federations:

If your questions are not related to simpleSAMLphp, but instead procedures on how to deal with a specific federation, visit the support channels specific for that federation.