Table of Contents
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:
This is the standard LDAP backend authentication module, it uses LDAP configuration from the config.php file.
This authentication module lets you connect to multiple LDAPS depending on what organization the user selects in the login form.
This authentication module will authenticate users against an RADIUS server instead of LDAP.
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.
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.
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.
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.
simpleSAMLphp will only work with RSA and not DSA certificates.
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
.
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:
The entity ID of the IdP. In this example this value is set
to: idp.example.org
.
The hostname of the server running this IdP.
Pointing to the private key in PEM format, in the certs directory.
Pointing to the certificate file in PEM format, in the certs directory.
Do you want to encode all attributes in base64? If so, remember to turn on the same option on the SP.
Which authentication module to use? Default is:
auth/login.php
which is the LDAP
authentication module.
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:;
The entity ID of the given SP. Here it is:
saml2sp.example.org
.
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.
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.
The SP NameQualifier for this SP. If unsure, set it to the same as the entityID.
This basicly means you turn off SSO for this SP.
Set it to the default: transient.
Set to true to include attribtues, if not no attribute statements will be sent.
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.
To test the IdP, it is best to configure two hosts with simpleSAMLphp, and use the SP demo example to test the IdP.
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.
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!
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.
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.
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.