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.
    
2. Create directory to put simplesamlphp.
    
3. Extract the simplesamlp archive.
    
4. Remove the tarball
    
5. Add the new files to git.
    
6. Commit the simplesamlphp files to the git repo
    
7. Add a symlink to your repository from /simplesaml to /private/simplesamlphp/www
    
8. Add the symlink to git.
    
9. Commit the simplesamlphp files to the git repo
    

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:

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.

4. Update git with the file changes.
    
5. Commit the configuration files to the report.
    

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:
   

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.
    
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.