Single Sign On Development Notes - NCIOCPL/cgov-digital-platform GitHub Wiki
Implementation Steps
- Run
blt recipes:simplesamlphp:init
. - 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/";
- 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.'; } }
- Edit
blt.yml
and addsimplesamlphp_auth
to the enable list undermodules:
> [tier]- Set for dev, test, and prod.
- Potentialy add an "ode" group which will not enable simplesamlphp_auth.
- 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
- ???
- 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
Acquia Support Docs for SimpleSaml
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:
composer require simplesamlphp/simplesamlphp
. (For me, this requires increasing the PHP memory limit.)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