Using simpleSAMLphp as a Service Provider

Andreas Åkre Solberg

Mon Oct 15 16:55:49 2007


Table of Contents

Introduction
Configuring metadata for SAML 2.0 SP
Configuring SAML 2.0 SP Hosted metadata
Configuring SAML 2.0 IdP Remote metadata
Setting the default SAML 2.0 IdP
Using the SAML 2.0 IdP Discovery Service
Configuring metadata for Shibboleth 1.3 SP
Configuring Shibboleth 1.3 SP Hosted metadata
Configuring Shibboleth 1.3 IdP Remote metadata
Exchange metadata with the IdP
Automatically generation of SP metadata for SAML 2.0
Test the SAML 2.0 SP examples
Integrating authentication with your own application

Introduction

simpleSAMLphp can run as both a SAML 2.0 Service Provider and as a Shibboleth 1.3 Service Provider. The configuration and metadata would be somewhat different, therefore there are separate chapter for the two, although the configuration is similar.

Configuring metadata for SAML 2.0 SP

When you are setting up a SAML 2.0 SP, you would need to configure two metadata files. saml20-sp-hosted.php and saml20-idp-remote.php. saml20-sp-hosted.php represent the SAML entity of the service provider itself, while the saml20-idp-remote.php configuration lists all the trusted SAML 2.0 IdP and how to connect to them.

Configuring SAML 2.0 SP Hosted metadata

You need to know at least two variables to be able to setup this metadata. You need to know the hostname of the server you are using, and you need to set an entity ID for this server. Talk to the people running the IdP of what entity ID you should use.

Note

Feide has special rules for setting entity IDs, so if you want to connect to Feide, contact them and ask what entity ID you should use.

Here is an example of the metadata file:

$metadata = array( 

	/*
	 * Example of a hosted SP 
	 */
	'entityid' => array(
		'host'							=>	'hostname',
		'spNameQualifier' 				=>	'entityid',
		'NameIDFormat'					=>	'urn:oasis:names:tc:SAML:2.0:nameid-format:transient',
		'ForceAuthn'					=>	'false'
	)

);

Here are the description of the possible fields:

index (the index of the array)

The entity ID of the hosted SP entity.

spNameQualifier

The name qualifier of the SP. If this is not important to you, you can set it to be identical with the entity ID above.

host

The hostname of the server running this SAML 2.0 SP. This option allows simpleSAMLphp to automatically discover which SP metadata to use, when it runs multiple virtual hosts.

NameIDFormat

The NameIDFormat in the request. If you don't know what this is, or don't need it to be anything specific, leave it with the default configuration.

ForceAuthn

Force authentication is a parameter that allows you to force re-authenticatino of users even if the user contains a SSO session at the IdP.

Configuring SAML 2.0 IdP Remote metadata

This metadata file lists all the IdPs that you trust.

	/*
	 * Example simpleSAMLphp SAML 2.0 IdP
	 */
	'idp.example.org' =>  array(
		'name'					=>	'Test',
		'description'			=> 'Description of this example entry',
		'SingleSignOnService'	=>	'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
		'SingleLogoutService'	=>	'https://idp.example.org/simplesaml/saml2/idp/LogoutService.php',
		'certFingerprint'		=>	'3fa158e8abfd4b5203315b08c0b791b6ee4715f6',
		'base64attributes'		=>	true
	),
index (the index of the array)

The entity ID of this SAML 2.0 IdP entity.

name

Set the name of this identity provider. Will just be used in the UI of the discovery service, so set it to whatever you want.

description

Set the description of this identity provider. Will just be used in the UI of the discovery service, so set it to whatever you want.

SingleSignOnService

Contact the IdP to get the endpoint URL of this service. This is the URL which the user is redirected with the AuthnRequest using HTTP-REDIRECT.

SingleLogoutService

Contact the IdP to get the endpoint URL of this service. This is the URL which the user is redirected with the LogoutRequest using HTTP-REDIRECT.

certFingerprint

The md5sum of the certificate used by the IdP. If you don't know how to compute this, you can leave it as it is, and then you'll get an error message the first time you try to login. In this error message you are told what is the fingerprint of the IdP certiciate, so you can copy and use that.

base64encode

Is the IdP base64 encoding all the attributes? Base64encoding should be avoided but makes it much easier to send data in different formats and characterencodings, so you can leave it on when you test. If you are using simpleSAMLphp at the IdP, remember to set the parameter in the metadata at the IdP to be the same.

Setting the default SAML 2.0 IdP

In the global configuration (config.php) there is a parameter to set the default IdP to use. Alternatively you can specify which IdP to use in a parameter to the initSSO.php script when you initiate logon in your application.

Here is an example from config.php:

	'default-saml20-idp'	=>	'sam.feide.no',

The configuration above will use the IdP configured in IdP Remote metadata with entity ID equal to sam.feide.no.

Using the SAML 2.0 IdP Discovery Service

If you want end users to be able to select one of all the specified entries in IdP remote metadata, you can set the default IdP to be null, then simpleSAMLphp will initiate the builtin IdP discovery service to let the user select IdP. Here is the neccessary configuration from config.php:

	'default-saml20-idp'	=>	null,

Configuring metadata for Shibboleth 1.3 SP

When you are setting up a Shibboleth 1.3 SP, you need to configure two metadata files. shib13-sp-hosted.php and shib13-idp-remote.php. shib13-sp-hosted.php represents the SAML entity of the service provider itself, while the shib13-idp-remote.php metadata lists all the trusted SAML 2.0 IdPs and contains information on how to connect to them.

Configuring Shibboleth 1.3 SP Hosted metadata

In the hosted metadata (shib13-sp-hosted.php) you will need to configure two parameters, the entity ID and the hostname of the server running this SP.

	/*
	 * Example of hosted Shibboleth 1.3 SP.
	 */
	'sp1entityid'	=> array(
		'host'						=>	'sp.example.org'
	)
index (the index of the array)

The entity ID of the hosted SP entity.

host

The hostname of the server running this Shibboleth 1.3 SP. This option allows simpleSAMLphp to automatically discover which SP metadata to use, when it runs multiple virtual hosts.

Configuring Shibboleth 1.3 IdP Remote metadata

Here (shib13-idp-remote.php) you configure which IdPs that you trust.

	'urn:mace:switch.ch:aaitest:dukono.switch.ch'	=> array(
		'SingleSignOnUrl'		=>	'https://dukono.switch.ch/shibboleth-idp/SSO',
		'certFingerprint'		=>	'c7279a9f28f11380509e075441e3dc55fb9ab864' 
	),
index (the index of the array)

The entity ID of this Shibboleth 1.3 IdP entity. In this example the entity ID is set to urn:mace:switch.ch:aaitest:dukono.switch.ch.

SingleSignOnUrl

Contact the IdP to get the endpoint URL of this service. This is the URL which the user is redirected with the request for authentication.

certFingerprint

The md5sum of the certificate used by the IdP. If you don't know how to compute this, you can leave it as it is, and then you'll get an error message the first time you try to login. In this error message you are told what is the fingerprint of the IdP certiciate, so you can copy and use that.

Exchange metadata with the IdP

Before you can run the test examples, you need the people running the IdP to load the metadata for your SP. If you run Shibboleth 1.3 SP, you will need to manually create metadata for your SP and send to the IdP, if you use SAML 2.0, metadata can be generated automatically.

Automatically generation of SP metadata for SAML 2.0

On the installation page there is a link named "Look at your SAML 2.0 SP metadata". Click there to look at the metadata for your SP. Send this metadata document to the IdP and ask them to load it.

If you are connected to Feide, and put one of Feides entity IDs as default IdP, you will see an additional section on this page:

Enter your email address and click the button to send the metadata to Feide. Remeber to get in contact with Feide to discuss your new service, and how you can be connected to Feides test environment.

Test the SAML 2.0 SP examples

When you have installed simpleSAMLphp, configured apache, and setup metadata and exchanged metadata with the IdP you are ready to test the example service that is included in the simpleSAMLphp installation.

On the installation page of simpleSAMLphp as you remember from the installation guide, there is a link to a Shibboleth 1.3 and SAML 2.0 example. When you click on that example, you should be automatically redirected to the IdP. Then login as usual, and you should get back to a status page with .

You should be redirected to the IdP. Login, and you should be sent back and shown all the attributes sent form the IdP.

Figure 1. Screenshot of the status page after an user have succesfully authenticated

Screenshot of the status page after an user have succesfully authenticated

Integrating authentication with your own application

You will need to hook some code into your application executed for every protected HTTP request. The flow in that code goes like:

  • Check whether the user is authenticated or not.

  • If the user is not authenticated, and it should be, then redirect the user to the initSSO.php script with the appropriate parameters. In particular the RelayState that tells the URL to return to after login.

  • If the user is authenticated then your done, map to your own user database if neccessary, and access the attributes from the session object as you like.

Here are some example code from the included example that you can reuse:

We start off with including a common file _include.php. All this file is doing is adding simpleSAMLphp to the classpath. If you want you can do this in php.ini instead. Or you can include all the content of _include.php in the application it self.

require_once('../_include.php');

Including class specifications. This is for SAML 2.0, for shibboleth look at the shibboleth example in www/example-simple/shib13-example.php.

require_once('SimpleSAML/Utilities.php');
require_once('SimpleSAML/Session.php');
require_once('SimpleSAML/XML/MetaDataStore.php');
require_once('SimpleSAML/XML/SAML20/AuthnRequest.php');
require_once('SimpleSAML/XML/SAML20/AuthnResponse.php');
require_once('SimpleSAML/Bindings/SAML20/HTTPRedirect.php');
require_once('SimpleSAML/Bindings/SAML20/HTTPPost.php');
require_once('SimpleSAML/XHTML/Template.php');

Then enable using PHP Sessions, and load configuration and metadata with simpleSAMLphp. You can copy this lines into your application without changes:

session_start();

/* Load simpleSAMLphp, configuration and metadata */
$config = SimpleSAML_Configuration::getInstance();
$metadata = new SimpleSAML_XML_MetaDataStore($config);
$session = SimpleSAML_Session::getInstance();

Then at last, you check whether the session is valid. If it is not, redirect to the initSSO.php script adding the current URL as a RelayState parameter. If you are authenticated, then retrieve all the attributes from the session object. You may want to look closer at the attributes array, so why don't you print_r it out right away to get the structure...

/* Check if valid local session exists.. */
if (!isset($session) || !$session->isValid() ) {
	header('Location: /' . $config->getValue('baseurlpath') . 'saml2/sp/initSSO.php?RelayState=' . urlencode(SimpleSAML_Utilities::selfURL()));
	exit(0);
}

$attributes = $session->getAttributes();
print_r($attributes);