Skip to main content

Use SimpleSAMLphp with Shibboleth SSO

Configure a single sign-on system for your Drupal or WordPress site with SimpleSAMLphp.


This section provides information on how to install and configure SimpleSAMLphp for Pantheon sites. Refer to the Other SSO Options section if you are searching for an SSO service provider solution with minimal configuration requirements.

Before You Begin

Info:
Note

The instructions below are only for advanced users working on integrating a Shibboleth single sign-on system with their Drupal site using the SimpleSAMLphp Authentication module from Drupal.org. For WordPress sites, use the WP SAML Auth plugin from WordPress.org with the bundled OneLogin SAML PHP library. WordPress Multisite users require additional configuration.

Install SimpleSAMLphp

PHP mcrypt is still used in SimpleSAMLphp 1.14.x, but was removed as a dependency in SimpleSAML 1.15.x. PHP mcrypt has been deprecated in PHP 7.1, and removed from core PHP 7.2. Consider using the appropriate lower versions if you encounter issues.

  1. Download SimpleSAMLphp and add it to your Git repository as private/simplesamlphp

    wget https://simplesamlphp.org/download?latest -O simplesamlphp-latest.tar.gz
    mkdir -p private/simplesamlphp
    tar -zxf simplesamlphp-latest.tar.gz -C private/simplesamlphp --strip-components 1
    git add private
    git commit -am "Adding SimpleSAML"
  2. Add a symlink to your repository from /simplesaml to /private/simplesamlphp/public:

    ln -s private/simplesamlphp/public simplesaml
    git add simplesaml
    git commit -am "Adding SimpleSAML symlink"
  3. Generate or install certs as needed, and add them to the repository in private/simplesamlphp/cert.

Configure SimpleSAMLphp

Set up your SimpleSAMLphp config.php as follows:

  1. Enable local sessions to ensure that SimpleSAMLphp can keep a session when used in standalone mode:

    config.php
    if (!ini_get('session.save_handler')) {
        ini_set('session.save_handler', 'file');
    }
  2. Load necessary environmental data.

    config.php
    $host = $_SERVER['HTTP_HOST'];
    $db = array(
        'host'      => $_ENV['DB_HOST'],
        'database'  => $_ENV['DB_NAME'],
        'username'  => $_ENV['DB_USER'],
        'password'  => $_ENV['DB_PASSWORD'],
        'port'      => $_ENV['DB_PORT'],
    );
  3. Set up the base config with the basic variables defined:

    config.php
    $config = [
         'baseurlpath' => 'https://'. $host .':443/simplesaml/', // SAML should always connect via 443
         'certdir' => 'cert/',
         'logging.handler' => 'errorlog',
         'datadir' => 'data/',
         'tempdir' => $_ENV['HOME'] . '/tmp/simplesaml',
    
         // Your $config array continues for a while...
         // until we get to the "store.type" value, where we put in DB config...
         'store.type' => 'sql',
         'store.sql.dsn' => 'mysql:host='. $db['host'] .';port='. $db['port'] .';dbname='. $db['database'],
         'store.sql.username' => $db['username'],
         'store.sql.password' => $db['password'],
    ]

    A custom SimpleSAML/Logger/LoggingHandlerInterface implementation is required for persistent and centralized logging.

    Info:
    Note

    Some SSO providers will fail to connect when the port number (443) is specified in baseurlpath. To solve this error, remove :443 from the line.

  4. Commit the changes to your SimpleSAMLphp files:

    git add private/simplesamlphp
    git commit -am "Adding SimpleSaml config files."
  5. Visit the subdirectory /simplesaml on your development site and complete your metadata configuration.

Drupal Configuration

If you are using the simpleSAMLphp Authentication module, follow the instructions listed in the README file. These instructions cover both Composer and non-Composer implementations for Drupal sites.

Composer settings.php File

Configuration of the setting.php file is not needed if you are using Composer.

Non-Composer settings.php File

Non-Composer implementations must add the following lines to the settings.php file to allow the Drupal module to locate SimpleSAMLphp:

Drupal 7 Example

settings.php
# Provide universal absolute path to the installation.
$conf['simplesamlphp_auth_installdir'] = $_ENV['HOME'] .'/code/private/simplesamlphp';

Drupal (Latest)

Drupal 10 includes Symfony 6. The SimpleSAMLphp library is not currently compatible with Symfony 6 unless you use the dev-master branch. There is a new simplesamlphp_auth branch (4.x) that you can use if you require a compatibility workaround. Note that this workaround requires you to use dev versions at your own risk.

You must require the Drupal module like this:

composer require drupal/simplesamlphp_auth:"^4"

WordPress Multisite Issues

WordPress Multisite users have reported a possible solution to enable SSO on their site. To use this solution, modify inc/class-wp-saml-auth.php to include:

class-wp-saml-auth.php
//$redirect_to = filter_input( INPUT_GET, 'redirect_to', FILTER_SANITIZE_URL );
//$redirect_to = $redirect_to ? : $_SERVER['REQUEST_URI'];
// added to resolve multisite SSO issues
$redirect_to = get_admin_url();
$this->provider->login( $redirect_to );

Troubleshooting

Varnish Not Working/Cookie Being Set for Anonymous Users

There is a known issue with the Drupal 7 version of the SimpleSAMLphp Authentication module. The module attempts to load a session on every page, as reported in https://drupal.org/node/2020009 in the official issue queue. Although there are two patches you can try in an effort to improve site performance; at this time, https://drupal.org/node/2020009#comment-7845537 is the recommended solution until the fix is accepted into an official project release.

SimpleSAMLphp Error: can't find metadata

Generate the required identity provider connections files through the modules, or follow the steps in SimpleSAMLphp for Adding IdPs to the SP.

The files must be added under the /private/simplesamlphp/metadata directory and symlinked into the vendor directory, if you are using Composer. This is similar to the config setup for Composer.

Other SSO Options

Other plugins and modules provide SSO provider services with less configuration.

Warning:
Warning

Pantheon does not officially endorse or provide support for any third-party plugins or modules.

SAML SP 2.0 Single Sign On (SSO) - SAML Service Provider

Drupal: The module SAML SP 2.0 Single Sign On (SSO) - SAML Service Provider provides a simple drop-in alternative way to configure SAML with a variety of IdPs.

The Support team has tested this module on Pantheon using Okta.

WordPress: The WordPress version of SAML SP Single Sign On – SSO login works in exactly the same way as the Drupal module, but has not been tested by Pantheon Support.

OAuth

OAuth is an open authorization standard that Pantheon customers have reported success using. Refer to SSO and Identity Federation on Pantheon for more information.

WP SAML Auth with Google Apps

WP SAML Auth lets your users sign into WordPress using their Google Account if your organization uses Google's G Suite. Refer to our Using WP SAML Auth with Google Apps guide for more information.

WordPress SSO Plugins

You can consult this list of WordPress SSO plugins for more options.

Drupal SSO Modules

You can consult this list of Drupal SSO modules for more options.

More Resources