Using simpleSAMLphp as an identity provider

Andreas Åkre Solberg

Sun Oct 21 13:49:41 2007


Table of Contents

Authentication modules
Configuring the LDAP authentication module
Configuring the multi-LDAP authenticaiton module
Setting up a SSL signing certificate
Configuring metadata for an SAML 2.0 IdP
Configuring SAML 2.0 IdP Hosted metadata
Configuring SAML 2.0 SP Remote metadata
Configuring metadata for a Shibboleth 1.3 IdP
Test IdP
Support
A. Writing your own authentication module
Authentication API

Authentication modules

In the www/auth directory, you see multiple files, each representing an authentication module. In the IdP hosted metadata configuration you specify which authentication module that should be used for that specific IdP. You can implement your own authentication module, see ???.

These authentication modules are included:

auth/login.php

This is the standard LDAP backend authentication module, it uses LDAP configuration from the config.php file.

auth/login-ldapmulti.php

This authentication module lets you connect to multiple LDAPS depending on what organization the user selects in the login form.

auth/login-radius.php

This authentication module will authenticate users against an RADIUS server instead of LDAP.

auth/login-auto.php

This module will automatically login the user with some test details. You can use this to test the IdP functionality if you do not have

This module is not completed yet. Work in progress.

Configuring the LDAP authentication module

The LDAP module is auth/login.php.

If you want to perform local authentication on this server, and you want to use the LDAP authenticaiton plugin, then you need to configure the following parameters in config.php:

  • auth.ldap.dnpattern: What DN should you bind to? Replacing %username% with the username the user types in.

  • auth.ldap.hostname: The hostname of the LDAP server

  • auth.ldap.attributes: Search parameter to LDAP. What attributes should be extracted? objectclass=* gives you all.

Configuring the multi-LDAP authenticaiton module

The module is auth/login-ldapmulti.php.

Note

Documentation will be added later. For now, contact the author.

Setting up a SSL signing certificate

For test purposes, you can skip this section, and use the included certificate.

For a production system, uou must generate a new certificate for your IdP.

Warning

There is a certificate that follows this package that you can use for test purposes, but off course NEVER use this in production as the private key is also included in the package and can be downloaded by anyone.

Here is an examples of openssl commands to generate a new key and a selfsigned certificate to use for signing SAML messages:

openssl genrsa -des3 -out server2.key 1024 
openssl rsa -in server2.key -out server2.pem
openssl req -new -key server.key -out server2.csr
openssl x509 -req -days 60 -in server2.csr -signkey server2.key -out server2.crt

The certificate above will be valid for 60 days.

Note

simpleSAMLphp will only work with RSA and not DSA certificates.

Configuring metadata for an SAML 2.0 IdP

If you want to setup a SAML 2.0 IdP you need to configure two metadata files: saml20-idp-hosted.php and saml20-sp-remote.php.

Configuring SAML 2.0 IdP Hosted metadata

This is the configuration of the IdP itself. Here is some example config:

	// The SAML entity ID is the index of this config.
	'idp.example.org' => array(
	
		// The hostname of the server (VHOST) that this SAML entity will use.
		'host'				=>	'sp.example.org',
		
		// X.509 key and certificate. Relative to the cert directory.
		'privatekey'		=>	'server.pem',
		'certificate'		=>	'server.crt',
		
		/* If base64attributes is set to true, then all attributes will be base64 encoded. Make sure
		 * that you set the SP to have the same value for this.
		 */
		'base64attributes'	=>	false,
		
		// Authentication plugin to use. login.php is the default one that uses LDAP.
		'auth'				=>	'auth/login.php'
	)

Here are some details of each of the parameters:

index (index of array)

The entity ID of the IdP. In this example this value is set to: idp.example.org.

host

The hostname of the server running this IdP.

privatekey

Pointing to the private key in PEM format, in the certs directory.

certificate

Pointing to the certificate file in PEM format, in the certs directory.

base64attributes

Do you want to encode all attributes in base64? If so, remember to turn on the same option on the SP.

auth

Which authentication module to use? Default is: auth/login.php which is the LDAP authentication module.

Configuring SAML 2.0 SP Remote metadata

Here (saml20-sp-remote.php) you configure all SPs that you trust. Here is an example:

	/*
	 * Example simpleSAMLphp SAML 2.0 SP
	 */
	'saml2sp.example.org' => array(
 		'AssertionConsumerService'		=>	'https://saml2sp.example.org/simplesaml/saml2/sp/AssertionConsumerService.php', 
 		'SingleLogoutService'			=>	'https://saml2sp.example.org/simplesaml/saml2/sp/SingleLogoutService.php',
		'spNameQualifier' 				=>	'dev.andreas.feide.no',
		'ForceAuthn'					=>	'false',
		'NameIDFormat'					=>	'urn:oasis:names:tc:SAML:2.0:nameid-format:transient',
		'simplesaml.attributes'			=>	true
	),

Here are some details about each of the parameters:;

index (index of array)

The entity ID of the given SP. Here it is: saml2sp.example.org.

AssertionConsumerService

The URL of this SAML 2.0 endpoint. Ask the SP if you are unsure. If the SP sent you SAML 2.0 metadata, you can find the parameter in there.

SingleLogoutService

The URL of this SAML 2.0 endpoint. Ask the SP if you are unsure. If the SP sent you SAML 2.0 metadata, you can find the parameter in there.

spNameQualifier

The SP NameQualifier for this SP. If unsure, set it to the same as the entityID.

ForceAuthn

This basicly means you turn off SSO for this SP.

NameIDFormat

Set it to the default: transient.

simplesaml.attributes

Set to true to include attribtues, if not no attribute statements will be sent.

Configuring metadata for a Shibboleth 1.3 IdP

You need to configure the shib13-idp-hosted.php metadata, as well as the list of trusted SPs in the shib13-sp-remote-php metadata. This configuration is very similar to the SAML 2.0 metadata mentioned in the previous section, so go look there for now.

Test IdP

To test the IdP, it is best to configure two hosts with simpleSAMLphp, and use the SP demo example to test the IdP.

Tip

To make the initial test up and running with minimal hassle, use the login-auto if you do not want to setup a user storage, and use the included cert so you do not need to create a new certificate.

Support

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

A. Writing your own authentication module

You can write your own authentication module. Just copy one of the files in the www/auth directory and play with it, then configure an IdP to use that module with the auth parameter in the metadata. The file must support incoming URL parameters, massage the session object with login state information and return to the RelayState, and that is all you need to do!

Tip

Instead of changing the code of the builtin authentication module, copy it into a new file and edit that. That way, your module will not be replaced or in conflict when you upgrade simpleSAMLphp to a newer version.

Authentication API

The authentication plugin should be placed in the auth directory.

The following parameters must be accepted in the incomming URL:

  • RelayState: This is the URL that the user should be sent back to after authentication within the plugin.

  • RequestID: This is the ID of an incomming request.

The initSSO.php takes in addition the following parameters:

  • idpentityid: This is the entityid of the IdP to authenticate with. This parameter is optional, if not set the default for this host will be used.

  • spentityid: This is which SP config to use. This parameter is optional, if not set the default for this host will be used.

In hosted IdP metadata there is a config parameter auth that will tell simpleSAML which authentication plugin that can be used.

Tip

The authentication API is pretty basic. The easiest way to understand how it works is to look at one of the existing plugins that is located in the auth directory of your installation.