Available in stable development 1.14 1.13 1.12 1.11 1.10 1.9 1.8 1.7 1.6 1.5

SimpleSAMLphp Advanced Features

Table of Contents

1 SimpleSAMLphp documentation

This document is part of the SimpleSAMLphp documentation suite.

This document assumes that you already have a installation of SimpleSAMLphp running, configured and working. This is the next step :)

2 Bridging between protocols

A bridge between two protocols is built using both an IdP and an SP, connected together. To let a SAML 2.0 SP talk to a SAML 1.1 IdP, you build a SimpleSAMLphp bridge from a SAML 2.0 IdP and a SAML 1.1 SP. The SAML 2.0 SP talks to the SAML 2.0 IdP, which hands the request over to the SAML 1.1 SP, which forwards it to the SAML 1.1 IdP.

If you have followed the instructions for setting up an SP, and have configured an authentication source, all you need to do is to add that authentication source to the IdP.

Example of bridge configuration

In metadata/saml20-idp-hosted.php:

'auth' => 'default-sp',

In config/authsources.php:

'default-sp' => array(

3 Attribute control

Filtering, mapping, etc can be performed by using existing or create new Authentication Processing Filters. For more information, read:

4 Automatic update of SAML 2.0 Metadata XML from HTTPS

The metarefresh module is the preferred method for doing this. Please see the metarefresh documentation.

5 Auth MemCookie

It is possible to integrate SimpleSAMLphp with Auth MemCookie. This allows you to integrate SimpleSAMLphp with web applications written in another language than PHP.

Auth MemCookie works by reading authentication data from a memcache server and setting environment variables based on attributes in this data. It also allows you to use the default Apache access control features to restrict access to your site.

The SimpleSAMLphp Auth MemCookie module can be found in www/authmemcookie.php and the configuration should be stored in config/authmemcookie.php. You may have to copy this file from config-template/authmemcookie.php.

To use Auth MemCookie, you need to do the following steps:

  1. Install and configure SimpleSAMLphp for running as an SP.
  2. Install and configure a memcache server.
  3. Install and configure Auth MemCookie. Go to the Auth MemCookie homepage for downloads and installation instructions. The following example (from extra/auth_memcookie.conf) may be useful when configuring Auth MemCookie:

    <Location />
            # This is a list of memcache servers which Auth MemCookie
            # should use. It is a ','-separated list of
            # host:port-pairs.
            # Note that this list must list the same servers as the
            # 'authmemcookie.servers'-option in config.php in the
            # configuration for SimpleSAMLphp.
            Auth_memCookie_Memcached_AddrPort ""
            # This must be set to 'on' to enable Auth MemCookie for
            # this directory.
            Auth_memCookie_Authoritative on
            # This adjusts the maximum number of data elements in the
            # session data. The default is 10, which can be to low.
            Auth_memCookie_SessionTableSize "40"
            # These two commands are required to enable access control
            # in Apache.
            AuthType Cookie
            AuthName "My Login"
            # This command causes apache to redirect to the given
            # URL when we receive a '401 Authorization Required'
            # error. We redirect to "/simplesaml/authmemcookie.php",
            # which initializes a login to the IdP.
            ErrorDocument 401 "/simplesaml/authmemcookie.php"
    <Location /secret>
            # This allows all authenticated users to access the
            # directory. To learn more about the 'Require' command,
            # please look at:
            # http://httpd.apache.org/docs/2.0/mod/core.html#require
            Require valid-user
  4. Configure the SimpleSAMLphp Auth MemCookie module by editing config/authmemcookie.php. You must set the username option to a valid attribute name. All other can most likely be left at their default values.

  5. Enable the SimpleSAMLphp Auth MemCookie module by setting enable.authmemcookie to true in config/config.php.

  6. To test the installation, you can add the following script as your /secret/index.php directory:

    foreach($_SERVER as $key=>$value) {
      echo('<tr><td>' . htmlspecialchars($key) . '</td><td>' . htmlspecialchars($value) . '</td></tr>');

    You should now be able to go to http://yourserver/secret/ to test the configuration. You should be redirected to your IdP, and after entering your username and password you should be taken back to http://yourserver/secret/. The resulting page should list all environment variables set by Apache, including the ones set by Auth MemCookie.

6 Metadata signing

SimpleSAMLphp supports signing of the metadata it generates. Metadata signing is configured by four options:

These options can be configured globally in the config/config.php-file, or per SP/IdP by adding them to the hosted metadata for the SP/IdP. The configuration in the metadata for the SP/IdP takes precedence over the global configuration.

There is also an additional fallback for the private key and the certificate. If metadata.sign.privatekey and metadata.sign.certificate isn't configured, SimpleSAMLphp will use the privatekey, privatekey_pass and certificate options in the metadata for the SP/IdP.

7 Session checking function

Optional session checking function, called on session init and loading, defined with 'session.check_function' in config.php.

Example code for the function with GeoIP country check:

public static function checkSession($session, $init = FALSE) {
    $data_type = 'example:check_session';
    $data_key = 'remote_addr';

    $remote_addr = NULL;
    if (!empty($_SERVER['REMOTE_ADDR'])) {
        $remote_addr = (string)$_SERVER['REMOTE_ADDR'];

    if ($init) {
        $session->setData($data_type, $data_key, $remote_addr, SimpleSAML_Session::DATA_TIMEOUT_SESSION_END);

    if (!function_exists('geoip_country_code_by_name')) {
        SimpleSAML_Logger::warning('geoip php module required.');
        return TRUE;

    $stored_remote_addr = $session->getData($data_type, $data_key);
    if ($stored_remote_addr === NULL) {
        SimpleSAML_Logger::warning('Stored data not found.');
        return FALSE;

    $country_a = geoip_country_code_by_name($remote_addr);
    $country_b = geoip_country_code_by_name($stored_remote_addr);

    if ($country_a === $country_b) {
        if ($stored_remote_addr !== $remote_addr) {
            $session->setData($data_type, $data_key, $remote_addr, SimpleSAML_Session::DATA_TIMEOUT_SESSION_END);

        return TRUE;

    return FALSE;

8 Support

If you need help to make this work, or want to discuss SimpleSAMLphp with other users of the software, you are fortunate: Around SimpleSAMLphp there is a great Open source community, and you are welcome to join! The forums are open for you to ask questions, contribute answers other further questions, request improvements or contribute with code or plugins of your own.