Implementation Steps

1. Run blt recipes:simplesamlphp:init.
2. Edit acquia_config.php as follows:
   • Add this block to the top of the file.

   $secrets_file = sprintf('/mnt/files/%s.%s/secrets.settings.php', $_ENV['AH_SITE_GROUP'],$_ENV['AH_SITE_ENVIRONMENT']);
   if (file_exists($secrets_file)) {
     require $secrets_file;
   }
   

   • Change these settings to use values from the secrets file:
     • $config['technicalcontact_name'] = SamlSecrets::TECH_CONTACT_NAME;
     • $config['technicalcontact_email'] = SamlSecrets::TECH_CONTACT_EMAIL
     • $config['secretsalt'] = SamlSecrets::SECRET_SALT;
     • $config['auth.adminpassword'] = SamlSecrets::AUTH_ADMIN_PASSWORD;
   • In the path where AH_SITE_ENVIRONMENT does exist, change the setting for $config['certdir'] to

     $config['certdir'] = "/mnt/files/{$_ENV['AH_SITE_GROUP']}.{$_ENV['AH_SITE_ENVIRONMENT']}/saml-certificate/";
     

3. Define secrets.settings.php in the directory /mnt/files/$AH_SITE_GROUP.$AH_SITE_ENVIRONMENT. (Note the use of environment variables in the directory name).

   <?php
   
   if(!class_exists('SamlSecrets')) {
     class SamlSecrets {
   
       public const SECRET_SALT = 'some 32 alpha-numeric string';
   
       public const TECH_CONTACT_NAME = 'a name';
       public const TECH_CONTACT_EMAIL = 'an email address';
   
       public const AUTH_ADMIN_PASSWORD = 'a strong password.';
   
     }
   }
   

4. Edit blt.yml and add simplesamlphp_auth to the enable list under modules: > [tier]
   • Set for dev, test, and prod.
   • Potentialy add an "ode" group which will not enable simplesamlphp_auth.
5. Configure IDP metadata???
   • Bugger. The steps at https://blt.readthedocs.io/en/9.x/simplesamlphp-setup/ seem to be written for the Acquia professional services people....
   • Metadata for the login team can be retrieved from http://<<EnvironmentURL>>/simplesaml/module.php/saml/sp/metadata.php/default-sp?output=xhtml
6. ???
7. Profit

Approach

Setup

SAML authentication is installed by running the command blt recipes:simplesamlphp:init. The SimpleSAMLphp Authentication module must be enabled drush en simplesamlphp_auth before Drupal will start using SAML authentication.

NOTE: Installing SimpleSAML creates a set of configuration files in {project_root}/simplesamlphp/config. These files must be copied to {project_root}/vendor/simplesamlphp/simplesamlphp/config (e.g. by the deployment process) before accessing the site; otherwise, all web requests will fail.

Additionally, the acquia_config.php file requires some edits (technical contact name and email, salt, admin password).

Secrets

acquia_config.php retrieves database and other credentials from /var/www/site-php/$AH_SITE_GROUP.$AH_SITE_ENVIRONMENT/creds.json. These values vary between environments.

A proposed method of handling additional secrets (e.g. configuration values for acquia.config) is to store them in a secrets.settings.php file stored in /mnt/files/$AH_SITE_GROUP.$AH_SITE_ENVIRONMENT/. This file would then be referenced from our code.

To Be Resolved: The /mnt/files/$AH_SITE_GROUP.$AH_SITE_ENVIRONMENT/ file location is not shared between environments. As such, the file would need to be manually deployed every time a new on demand environment is created.

Local development vs. Cloud deployment

Installing SAML authentication adds the simplesamlphp composer package and the simplesamlphp_auth module, but doesn't enable the module. Leaving the module disabled in the codebase allows local development is able to take place and the module need only be enabled in the cloud environment.

Notes

• NIH Login Services
• Acquia SSO documentation

Acquia Support Docs for SimpleSaml

• Older SimpleSAMLphp configurations do not account for on-demand environments

Setup notes from Forrest Livengood

We have some general docs around setting up SimpleSAMLphp for SSO here: https://docs.acquia.com/resource/using-simplesamlphp-acquia-cloud-site/

One of the most important parts on that page is the snippet you can include or paste into the bottom of the /simplesamlphp/config/config.php file: https://raw.githubusercontent.com/acquia/blt/9.x/scripts/simplesamlphp/acquia_config.php

That snippet handles the connection to the database on Acquia Cloud. The database is used to store information about the user sessions.

A partner of ours has a very in-depth writeup of the process here: https://www.chapterthree.com/blog/how-to-configure-simplesamlphp-for-drupal-8-on-acquia

My own notes:

1. composer require simplesamlphp/simplesamlphp. (For me, this requires increasing the PHP memory limit.)
2. composer require drupal/simplesamlphp_auth

In the .htaccess file, there's a group of RewriteCond clauses for denying access to most PHP files. The block starts around line 141, but a good one to search for is RewriteCond %{REQUEST_URI} !/core/modules/statistics/statistics.php$.. An additional condition needs to be added to allow access to the /simplsaml directory.

RewriteCond %{REQUEST_URI} !^/simplesaml

Oh look, there's a Setting up SSO with SimpleSAMLphp page in the BLT docs! This looks like it includes some of the missing steps.

  To complete the setup you must manually modify several files:                                                                             
                                                                                                                                            
  * /var/www/simplesamlphp/config/acquia_config.php                                                                                         
  * /var/www/simplesamlphp/config/authsources.php                                                                                           
  * /var/www/simplesamlphp/metadata/saml20-idp-remote.php                                                                                   
                                                                                                                                            
  After editing these files execute the following command to copy the modified files to the correct location in the SimpleSAMLphp library:  
                                                                                                                                            
  'blt source:build:simplesamlphp-config'                                                                                                   
                                                                                                                                            
  See http://blt.readthedocs.io/en/latest/readme/simplesamlphp-setup/ for details on how to modify the files.  

Config file

Among other things, running blt recipes:simplesamlphp:init generates configuration files at {project_root}/simplesamlphp/config.

• acquia_config.php includes a "secretsalt" key. Presumably, this is used for encryption (session keys?), but there are no guidelines for what the value should be. Notes at https://github.com/SU-HSDO/mrc_blt#acquia-configs suggest that the output of

LC_CTYPE=C tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' </dev/urandom | dd bs=32 count=1 2>/dev/null;echo

(32 random alphanumeric characters) would be a suitable value.

In acquia_config.php, load SAML secrets with

$secrets_file = sprintf('/mnt/files/%s.%s/secrets.settings.php', $_ENV['AH_SITE_GROUP'],$_ENV['AH_SITE_ENVIRONMENT']);

if (file_exists($secrets_file)) {
  require_once($secrets_file);
}

The require_once for some reason doesn't prevent the file being loaded multiple times, so the secrets class needs to be written with a class_exists() to guard against redefinition.:

<?php

if(!class_exists('SamlSecrets')) {
  class SamlSecrets {

    public const SECRET_SALT = 'some 32 alpha-numeric string';

    public const TECH_CONTACT_NAME = 'a name';
    public const TECH_CONTACT_EMAIL = 'an email address';

    public const AUTH_ADMIN_PASSWORD = 'a strong password.';

  }
}

Crap for later

Secrets in Acquia cloud vs ACSF (important for acquia_config.php) From https://docs.acquia.com/resource/secrets/#secrets-settings-php-file

To make the secrets file available to your application, add the lines in the following example to the appropriate location based on your installed product:

Acquia Cloud – To your website’s settings.php file

Acquia Cloud Site Factory – To a post-settings-php hook named secrets.php