Table of Contents
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.
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.
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.
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:
The entity ID of the hosted SP entity.
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.
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.
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.
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.
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 ),
The entity ID of this SAML 2.0 IdP entity.
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.
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.
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.
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.
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.
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.
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
.
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,
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.
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' )
The entity ID of the hosted SP entity.
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.
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' ),
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
.
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.
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.
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.
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.
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.
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);
If you have problems to get this work, or want to discuss simpleSAMLphp with other users of the software you are lucky! Around simpleSAMLphp there is a great Open source community, and you are welcome to join! Both for asking question, answer other questions, request improvements or contribute with code or plugins of your own.
Visit the project page of simpleSAMLphp at: http://code.google.com/p/simplesamlphp/
And please join the mailinglist: https://postlister.uninett.no/sympa/subscribe/simplesaml