Pantheon Simplesamlphp Drupal Configuration

Pantheon Documentation

You can review the Pantheon documentation at https://pantheon.io/docs/shibboleth-sso. There's a few issues where the documentation seems to be incorrect, so it is as best used a fallback to this document.

Install simplesamlphp

You will need to do this step in a repository which exists in WSL (Windows Linux Shell) and not located on /mnt/.

  1. Download the simplesamlphp library. Note that the Pantheon instructions don't seem to work to do this.
    wget https://github.com/simplesamlphp/simplesamlphp/releases/download/v1.19.5/simplesamlphp-1.19.5.tar.gz -O simplesamlphp-latest.tar.gz
  2. Create directory to put simplesamlphp.
    mkdir -p private/simplesamlphp
  3. Extract the simplesamlp archive.
    tar -zxf simplesamlphp-latest.tar.gz -C private/simplesamlphp --strip-components 1
  4. Remove the tarball
    rm simplesamlphp-latest.tar.gz
  5. Add the new files to git.
    git add private
  6. Commit the simplesamlphp files to the git repo
    git commit -am "Adding SimpleSAML"
  7. Add a symlink to your repository from /simplesaml to /private/simplesamlphp/www
    ln -s private/simplesamlphp/www simplesaml
  8. Add the symlink to git.
    git add simplesaml
  9. Commit the simplesamlphp files to the git repo
    git commit -am "Adding SimpleSAML symlink"

Install certificates

  1. Copy the default-sp.crt, default-sp.key, and sso-signing.pem files from an existing repository to private/simplesamlphp/cert.

Editing configuration files

  1. config.php: This file exists in /private/simplesamlphp/config. Follow the Pantheon tutorial or copy a version from a working simplesamlp configuration. Ensure you edit the 'secretsalt' and 'auth.adminpassword'.
  2. authsources.php: This file exists in /private/simplesamlphp/config. Replace the default-sp array with the following:
        'default-sp' => [
            'saml:SP',
     
            'privatekey' => 'default-sp.key',
            'certificate' => 'default-sp.crt',
     
            // The entity ID of this SP.
            // Can be NULL/unset, in which case an entity ID is generated based on the metadata URL.
            'entityID' => 'https://sp.sog.unc.edu/simplesaml/module.php/saml/sp/metadata.php/default-sp',
     
            // The entity ID of the IdP this SP should contact.
            // Can be NULL/unset, in which case the user will be shown a list of available IdPs.
            'idp' => 'https://sso.unc.edu/idp',
     
            // The URL to the discovery service.
            // Can be NULL/unset, in which case a builtin discovery service will be used.
            'discoURL' => 'NULL',
     
            /*
             * The attributes parameter must contain an array of desired attributes by the SP.
             * The attributes can be expressed as an array of names or as an associative array
             * in the form of 'friendlyName' => 'name'. This feature requires 'name' to be set.
             * The metadata will then be created as follows:
             * <md:RequestedAttribute FriendlyName="friendlyName" Name="name" />
             */
            /*
            'name' => [
                'en' => 'A service',
                'no' => 'En tjeneste',
            ],
     
            'attributes' => [
                'attrname' => 'urn:oid:x.x.x.x',
            ],
            'attributes.required' => [
                'urn:oid:x.x.x.x',
            ],
            */
        ],
  3. saml20-idp-remote.php: This file exists in /private/simplesamlphp/metadata. Follow the Pantheon tutorial or copy a version from a working simplesamlp configuration.
    $metadata['https://sso.unc.edu/idp'] = array(
        'name' => array(
            'en' => 'UNC SSO',
        ),
        'description'          => '',
        'SingleSignOnService'  => 'https://sso.unc.edu/idp/profile/SAML2/Redirect/SSO',
        'certificate' => 'sso-signing.pem',
        'sign.authnrequest' => true,
        'SingleLogoutService' => 'https://sso.unc.edu/idp/logout.jsp'
    );
     
  4. Update git with the file changes.
    git add simplesaml
  5. Commit the configuration files to the report.
    git commit -am "Adding SimpleSAML confirgation files"

Enable Shibboleth/SAML

  1. Ensure your simplesaml is in the right place by going to /simplesaml. For example, https://clerks.sog.unc.edu/simplesaml. You should see the "SimpleSAMLphp installation page".
  2. Email Jan Tax (tax@unc.edu) that you need a new domain added to the sp.sog.unc.edu idp. He will need the domains you want to add.
  3. Once Jan has informed the UNC SSO service about the new URLs, go to /simplesaml/module.php/core/authenticate.php
  4. Click on 'default-sp'. You should be redirected to the UNC SSO login page. If you get an error similar to "UNC-Chapel Hill Single Sign-On - Unable to Respond", it likely means something got entered wrong on Jan's end.
  5. You should be able to log in as normal through the UNC SSO page.
  6. You will land on the "SAML 2.0 SP Demo Example" page, which should have a breakdown of various information about your UNC account under the "Your Attributes" box.

Enable Simplesamlphp for Drupal

  1. Download the simplesamlphp_auth and externalauth modules for your version of Drupal. Add it to your repository and push your code to the server as you would with any module.
  2. Edit your site's settings file (generally on Pantheon sites/default/settings.php) and add the following:
    /**
     * Tell Drupal where to find simplesamlphp
     */
    $settings['simplesamlphp_dir'] = $_ENV['HOME'] .'/code/private/simplesamlphp';
  3. Push the new settings file up to your codebase. Note: When you add this change to your git repository, you probably will need to force adding the file.
    git add -f sites/default/settings.php
  4. Enable simplesamlphp_auth (which should enable externalauth automatically).
  5. Navigate to the simplesamlphp_auth configuration page at /admin/config/people/simplesamlphp_auth
  6. Click on the "Local authentication" menu (admin/config/people/simplesamlphp_auth/local).
  7. Enable "Allow authentication with local Drupal accounts" and if desired, restrict to appropriate roles (ie administrators). Do not skip this step or you might white-screen your site!.
  8. Save the configuration and return to the main page.
  9. Check the box to activate authentication via SimpleSAMLphp
  10. Ensure that "default-sp" is set as the "Authentication source for this SP"
  11. Click the save configuration button.
  12. Click on "User info and syncing"
  13. You have choices as to what you put for the unique identifier for the user, their username, and their email. Generally I set them all to the same value, their email address. On the campus SSO system that is identified by urn:oid:0.9.2342.19200300.100.1.3.