Set up SSO for two Drupal sites using SAML and one Drupal site as the IdP

Submitted by roo on Mon, 11/27/2017 - 16:33

There's quite a bit of set up to get this working, mostly outside of Drupal.

In my case I was using Drupal 7 as the IdP and Drupal 8 as the SP, but the process would be the same if the SP were a Drupal 7 site. (At the time of writing, the Drupal module to enable the Drupal database to act as the IdP has not been ported to D8, so using a D8 users database as the IdP is not possible without custom code).

Firstly some terminology. These are not formal definitions, more a summary of my own (limited) understanding.

  • SAML - Security Assertion Markup Language - is a " standard for exchanging authentication and authorization data between security domains".
    by definition then it is not limited to Drupal sites.
  • IdP - Identity Provider - the system that manages the identity information and provides a service to allow user authentication.
    Any system (not just Drupal) can be configured to authenticate via the IdP (with appropriate certificates etc.)
  • SP - Service Provider - communicates with the IdP to authenticate a user on a system which is seperated from the IdP.
    Can authenticate against any type of IdP, not limited to a Drupal database.

In my case, I have an existing Drupal 7 system, with an existing userbase which I want to act as the IdP, and a new Drupal 8 system which requires SSO and access to the UID (amongst other datafields)

I considered Bakery but the User ID is (intentionally) not available utilising Bakery.

There are a few aspects to setting up Drupal/SAML.

  1. The core functionality is provided by simpleSAMLphp.
  2. drupalauth is a plugin for simpleSAMLphp which provides a means to define a Drupal database as the IdP
  3. drupalauthssp is the Drupal 7 plugin to allow Drupal to inderact with the simpleSAML IdP enabled by drupalauth.
  4. simpleSAMLphp Authentication is the Drupal module to allow Drupal to interact with the simpleSAML SP

 

Set up the IdP

simpleSAMLphp installation

The IdP will be a Drupal7 site, so installation simply consists of downloading the tarball from simplesamlphp.org and extracting it to the desired location.

simpleSAMLphp needs to be installed on both webservers. My layout for a virtual host looks like:

/var/www/vhosts/saml-idp.example.co.nz
                          |
                          +-- drupal
                          +-- htdocs -> drupal
                          +-- simplesamlphp

Within the simplesamlphp directory, run 'composer install' to complete the installation and install all dependancies.

Install the drupalauth plugin for simpleSAMLphp:

Follow the installation instructions at drupalauth, but essentially you extract the plugin into the modules subdirectory of the simpleSAMLphp installation.

simpleSAMLphp configuration

  • simpleSAMLphp is outside the webspace, but the www sub-directory needs to be web accessible, so an alias is created for it
    • Apache:
      Alias /simplesaml /var/www/vhosts/saml-idp.example.co.nz/simplesamlphp/www
    • nginx is a little trickier:

      location  /simplesaml {
          alias /var/www/vhosts/saml-idp.example.co.nz/simplesamlphp/www;

          location ~ ^(?<prefix>/simplesaml)(?<phpfile>.+?\.php)(?<pathinfo>/.*)?$ {
            include fastcgi_params;
            fastcgi_split_path_info ^(.+?\.php)(/.+)$;
            fastcgi_pass phpcgi;
            fastcgi_param SCRIPT_FILENAME $document_root$phpfile;
            fastcgi_param PATH_INFO $fastcgi_path_info;
          }
       }

       NOTE: the Alias defined here must match what's in the config.php (see next step)

  • simpleSAMLphp config.php
    Work through the  config options. The config file provided is well documented
    • base URL path
      the default should be fine
    • cert directory
      (may want to alter this)
    • tech contact email
    • security config:
      generate a secretsalt - instructions in the config
      admin password
    • simpleSAML functionality
       - enable saml20-idp
    • store.type
      memcache seems sensible, but there seems to be issues with memcached/php7/simplesamlphp, so I used sql
      'store.type'          => 'sql',
      'store.sql.dsn'       => 'mysql:host=localhost;dbname=drupal7database',
      'store.sql.username'  => 'drupal7user',
      'store.sql.password'  => 'drupal7password',
      'store.sql.prefix'    => 'drupal_site_prefix',

simpleSAMLphp Drupal Module  (only required on the IdP)

This is a module for simpleSAMLphp which allows simpleSAMLphp to use Drupal as the IdP.

  • Download and extract into the module into the modules directory of simpleSAMLphp on the IdP
  • Enable the module by creating a file named 'enable' in the directory (touch <path-to>/simplesamlphp/modules/drupalauth/enable)
  • Edit simplesamlphp/config/authsources.php and add the following:

        // Use Drupal 7 as authentication source
        'drupal-userpass' => array('drupalauth:External',
        
         // The filesystem path of the Drupal directory.
         'drupalroot' => '/var/www/vhosts/saml-idp.example.co.nz/htdocs',
        
         // Whether to turn on debug
         'debug' => true,
        
         // the URL of the Drupal logout page
         'drupal_logout_url' => 'https://saml-idp.example.co.nz/user/logout',
        
         // the URL of the Drupal login page
         'drupal_login_url' => 'https://saml-idp.example.co.nz/user',
        
         // Which attributes should be retrieved from the Drupal site.
         'attributes' => array(
           array('drupaluservar'   => 'uid',  'callit' => 'uid'),
           array('drupaluservar' => 'name', 'callit' => 'cn'),
           array('drupaluservar' => 'mail', 'callit' => 'mail'),
           array('drupaluservar' => 'field_first_name',  'callit' => 'givenName'),
           array('drupaluservar' => 'field_last_name',   'callit' => 'sn'),
           array('drupaluservar' => 'field_organization','callit' => 'ou'),
           array('drupaluservar'   => 'uuid',  'callit' => 'uuid'),
           array('drupaluservar' => 'roles','callit' => 'roles'),
          ),
        ),

    (taken from simplesamlphp/modules/drupalauth/lib/Auth/Source/External.php)

Create a certificate

  • Go to the defined cert directory and run:
    openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out saml-idp.example.co.nz.crt -keyout saml-idp.example.co.nz.pem
    (See simpleSAMLphp documentation)

Install drupal module drupalauth4ssp

  • Install and enable this in the usual way (drush on D7)
  • Configure module
    • Enter the full path to simplesamlphp
    • Enter drupal-userpass for the Authentication source
    • In the "Allowed list of URLs for ReturnTo Parameter" enter an asterix (*) as wildcard.

Configure simpleSAMLphp Metadata

There are template metadata files in simplesamlphp/metadata-templates. Copy the required ones into simplesamlphp/metadata

  • The IdP will require:
    • saml20-idp-hosted.php
    • saml20-sp-remote.php

Edit the files in simplesamlphp/metadata

  • saml20-idp-hosted.php
    • Configure the certificate/private-key
    • Authentication source. Use:
      'auth' => 'drupal-userpass',
  • saml20-sp-remote.php will require data from the SP, so we'll come back to this once the SP is configured.

Set up the SP

Install Drupal (drupal 8 in my case) and simpleSAMLphp.

As this is a Drupal 8 site, Drupal was installed with composer.

My configuration installs D8 in this structure:

/var/www/vhosts/saml-sp.example.co.nz
                          |
                          +-- drupal-8.x
                          +-- htdocs -> drupal-8.x/web
                         

The Drupal module simplesamlphp_auth is required, so this was installed with :

composer require drupal/simplsamlphp_auth

simplesamlphp_auth has a dependancy of simplesamlphp, so composer installed simplsamlphp in

/var/www/vhosts/saml-sp.example.co.nz/vendor/simplsaml

(Note - there are alternative modules available to provide the SP functuionality in Drupal:

  • samlauth doesn't require simplesamlphp on the SP webserver. I haven't configured this module and the example metadata only deals with openidp. As I have an existing D7 userbase, OpenIDP isn't an option for me.
  • saml_sp also is independant of simplesamlphp, but seems at the time of writing to be missing some useful features.
  • There are a couple of commercial modules, plus modules that are specific to third party IdP's)

Create the alias for the web interface:

Alias /simplesaml /var/www/vhosts/saml-sp.example.co.nz/drupal-8.x/vendor/simplesamlphp/simplesamlphp/www
(Apache example shown)

Edit the simpleSAMLphp config.php as for the IdP excepting do not enable saml20-idp and alter the SQL connection details appropriately:

  • simpleSAMLphp config.php
    Work through the  config options. The config file provided is well documented
    • base URL path
      the default should be fine
    • cert directory
      (may want to alter this)
    • tech contact email
    • security config:
      generate a secretsalt - instructions in the config
      admin password
    • simpleSAML functionality
      - leave all disabled
    • store.type:
      'store.type'          => 'sql',
      'store.sql.dsn'       => 'mysql:host=localhost;dbname=drupal8database',
      'store.sql.username'  => 'drupal8user',
      'store.sql.password'  => 'drupal8password',
      'store.sql.prefix'    => 'drupal8_site_prefix',

Configure the Authsource

  • edit authsources.php and add a new source. Enter the following within the $config - array( block:

        // Use Drupal 7 as authentication source
        'drupal7site' => array(
            'saml:SP',
            'entityID' => 'http://saml-idp.example.co.nz',
            'idp' => 'http://saml-idp.example.co.nz/simplesaml/saml2/idp/metadata.php',
            'privatekey' => 'idp.key',
            'certificate' => 'idp.crt',
        ),

    This creates a new authentication source. If you prefer you can edit the default-sp authentication source. I created a new one as I like to know that I'm using the one I've configured.

Configure the Metadata

  • Copy vendor/simplsamlphp/simplesamlphp/metadata-templates/saml-20-idp-remote.php to vendor/simplsamlphp/simplesamlphp/metadata/saml-20-idp-remote.php
  • Edit the metadata/saml-20-idp-remote.php
  • On the IdP visit the 'Federation' tab of the simpleSAMLphp admin pages
  • Copy the 'Flat file format' of the IdP metadata (click on the clipboard icon)
  • Paste the metadata into saml-20-idp-remote.php and save the file

Copy the public key

From the IdP Metadata page used above, scroll to the bottom and download the certificate into the location configured in the config.php on the SP. Ensure the name of the file is the same as configured in the Authsource.

Drupal module simplesamlphp_auth

  • Enable the module (either with drush or via the web interface).
  • Configure the module
    • set the installation directory
    • set the Authentication source as drupal7site (or whatever you configured above)
    • map the basic fields (I used uid as the uniqueID, cn as the username and mail as the email address)
    • Configure other settings. Make sure that the admin user can log in locally.

Configure the Metadata for the IdP

The IdP needs the metadata from the SP that will connect.:

  • On the IdP, edit the file metadata/saml-20-sp-remote.php
  • On the SP , visit the Fedaration tab of the simpleSAMLphp admin pages
  • Copy the 'Flat file format' metadata for the Authsource you created ("drupal7site" in this example)
  • Paste into saml-20-sp-remote.php and save the file

 

That's pretty much it. You should now be able to visit your SP site, visit /saml_login (there's a link created on /user/login), and login to your SP by authenticating on the IdP.