simplesamlphp-sp-migration.md

Migrating to the saml module

This document describes how you can migrate your code to use the saml module for authentication against SAML 2.0 and SAML 1.1 IdPs. It assumes that you have previously set up a SP by using redirects to saml2/sp/initSSO.php.

The steps we are going to follow are:

1. Create a new authentication source.
2. Add the metadata for this authentication source to the IdP.
3. Test the new authentication source.
4. Convert the application to use the new API.
5. Test the application.
6. Remove the old metadata from the IdP.
7. Disable the old SAML 2 SP.

Create a new authentication source

In this step we are going to create an authentication source which uses the saml module for authentication. To do this, we open config/authsources.php. Create the file if it does not exist. If you create the file, it should looke like this:

<?php
$config = array(
    /* Here we can add entries for authentication sources we want to use. */
);

We are going to add an entry to this file. The entry should look something like this:

'default-sp' => array(
    'saml:SP',

    /*
     * The entity ID of this SP.
     * Can be NULL/unset, in which case an entity ID is generated based on the metadata URL.
     */
    'entityID' => NULL,

    /*
     * The entity ID of the IdP this should SP should contact.
     * Can be NULL/unset, in which case the user will be shown a list of available IdPs.
     */
    'idp' => NULL,

    /* Here you can add other options to the SP. */
),

default-sp is the name of the authentication source. It is used to refer to this authentication source when we use it. saml:SP tells SimpleSAMLphp that authentication with this authentication source is handled by the saml module.

The idp option should be set to the same value that is set in default-saml20-idp in config.php.

To ease migration, you probably want the entity ID on the new SP to be different than on the old SP. This makes it possible to have both the old and the new SP active on the IdP at the same time.

You can also add other options this authentication source. See the saml:SP documentation for more information.

Add the metadata for this authentication source to the IdP

After adding the authentication source on the SP, you need to register the metadata on the IdP. To retrieve the metadata, open the frontpage of your SimpleSAMLphp installation, and go to the federation tab. You should have a list of metadata entries, and one will be marked with the name of the new authentication source. In our case, that was default-sp.

Click the Show metadata link, and you will arrive on a web page with the metadata for that service provider. How you proceed from here depends on which IdP you are connecting to.

If you use a SimpleSAMLphp IdP, you can use the metadata in the flat file format at the bottom of the page. That metadata should be added to saml20-sp-remote.php on the IdP. For other IdPs you probably want to use the XML metadata.

Test the new authentication source

You should now be able to log in using the new authentication source. Go to the frontpage of your SimpleSAMLphp installation and open the authentication tab. There you will find a link to test authentication sources. Click that link, and select the name of your authentication source (default-sp in our case).

You should be able to log in using that authentication source, and receive the attributes from the IdP.