Information for: DEVELOPERS   PARTNERS

Using SimpleSAMLphp with your Acquia Cloud site

Using SimpleSAMLphp with PHP 7.2 displays errors in log files. For more information, see this known issue.

SimpleSAMLphp is a basic implementation of the SAML authentication protocol. SimpleSAMLphp supports several popular authentication identity provider (IdP) systems, including Shibboleth, Microsoft ADFS, CA SiteMinder, Oracle Identity Manager, and Novell SecureLogin. The only service provider implementation supported at Acquia is SimpleSAMLphp.

If you are an existing Acquia subscriber, and you would like help implementing SimpleSAML, contact your Account Manager for information about how Acquia can assist you. For new SimpleSAML installations on Acquia Cloud, a special engagement is available. Without a SimpleSAML engagement, Acquia Support can provide limited help. If you are not a current Acquia subscriber, contact an Acquia sales team representative for help.

Note for Acquia Cloud Site Factory users

Acquia Cloud Site Factory subscribers must work with Acquia to enable SimpleSAML on their websites.

Installing SAML

Installing SAML includes the following steps:

  1. Installing the PHP code
  2. Installing the simplesamlphp_auth Drupal module
  3. Configuring SimpleSAMLphp to communicate with your Identity Provider (IdP)

Installing the PHP code

To begin installing SimpleSAMLphp, download the library . Acquia recommends version 1.13.2.

#. Extract the SimpleSAML library to the root directory of your repository alongside docroot, acquia-utils and library. #. In your docroot directory, create a symbolic link (named simplesaml, for example) pointing to the www directory in the SimpleSAMLphp library. As an example:

cd docroot; ln -s ../simplesamlphp/www simplesaml

The preceding bash command ensures the web interface is publicly accessible, while keeping the configuration outside of the document root.

Installing the simplesamlphp_auth Drupal module

Install and enable the Drupal simpleSAMLphp Authentication module. Do not activate the SimpleSAMLphp sign-in until you have configured the SimpleSAMLphp library. Drupal will give you a green box on several pages indicating SimpleSAML is not active.

Important

If you activate the sign-in before you configure the SimpleSAMLphp library, you will have problems accessing your website.

If you lock yourself out of your website by activating the sign-in before configuring the library, you can use Drush from the command line to disable the module. For help, see Disabling modules that block sites on Acquia Cloud.

Note

The following issues in the simplesamlphp_auth module’s issue queue may cause problems due to session cookies invalidating Varnish® caching. Acquia recommends determining the status of the module issues before proceeding:

Setting the installation location of the Simple SAML library

Despite the location field prompt to use an absolute path, use the following install location through the module user interface:

../simplesaml

Drupal 8 websites must add the following code to your website’s .htaccess file, otherwise the following Access Denied messages may display: (documented here)

# Copy and adapt this rule to directly execute PHP files in contributed or
# custom modules or to run another PHP application in the same directory.
RewriteCond %{REQUEST_URI} !/core/modules/statistics/statistics.php$
+ # Allow access to simplesaml paths
+ RewriteCond %{REQUEST_URI} !^/simplesaml
# Deny access to any other PHP files that do not match the rules above.
RewriteRule "^.+/.*\.php$" - [F]

Configuring SimpleSAMLphp to communicate with your Identity Provider (IdP)

Modify the SimpleSAMLphp configurations in the config.php file in SimpleSAMLphp as necessary. Changes may depend on your environment.

You can configure SimpleSAMLphp to store SAML session information in different ways. By default, SimpleSAMLphp attempts storing session information as files on disk. Since a large number of web servers are available for highly-available production environments, those files are not shared across servers. Acquia does not recommend saving sessions to a file due to how file permissions are secured on Acquia Cloud and the volatile nature of tmp.

Instead, Acquia recommends storing session information in a SQL database as described in the following section.

Storing session information using the Acquia Cloud SQL database

The SQL database does not require the same database as your Drupal installation. Using the same database is acceptable. To create a separate database for SAML session information, see Adding a new database.

To connect to the High Availability (HA) database on Acquia Cloud, add the SimpleSAMLphp Acquia Configuration code snippet to the bottom of the config.php file, where [ah_database_name] is the workflow database name for your environment. You can find your database connection information on your Acquia Cloud > Databases page. Click the arrow to the right of Backup for the database, and then click Connection Details.

Download the SimpleSAMLphp Acquia Configuration file here.

Note

Before June 2018, the configuration file version is incompatible with environments named other than dev, stage, or prod. Acquia recommends you update to the current version of the script. For help with troubleshooting older versions of the script, see Older SimpleSAMLphp configurations do not account for on-demand environments.

An example modification:

To support multisite installs, use the following example code after line 44 (the custom area) of the SimpleSAMLphp Acquia Configuration code snippet:

$config['baseurlpath'] = "https://{$_SERVER['SERVER_NAME']}/simplesaml/";

The following steps allow you to leverage the SimpleSAMLphp GUI. The SimpleSAMLphp documentation highlights the details on configuring the SimpleSAMLphp library as a Service Provider (SP).

Navigate back to admin/config/people/simplesamlphp_auth, select the Activate authentication via SimpleSAMLphp checkbox, and then configure the details for your IdP. You should check, and test the changes as the IdP-specific configuration falls outside the scope of Acquia Support.

External tool for testing

Internet2 offers a free, external service as part of their support for Shibboleth providing a test Identity Provider and Service Provider. For initial testing, Acquia recommends the Test SP found at testshib.org.

SimpleSAML for Acquia Cloud Site Factory

If you are an Acquia Cloud Site Factory subscriber, you cannot configure the server side of SimpleSAMLphp on your own — contact Acquia Support about a Professional Services engagement to enable SimpleSAML, allowing you to:

  • Secure and install Service Provider (SP) metadata at the IdP.
  • Collaborate with Acquia technical resources for the testing of the SimpleSAMLphp configuration.
  • Ensure the availability of technical resources with access to and knowledge of the IdP.
  • Own all custom code and testing of custom workflows (beyond the provided code and workflows by the SimpleSAMLphp Authentication module, and the SimpleSAMLphp library).
  • Correct the config.php file to use the following path, instead of the default creds.json path:
  • Own testing and validation of all Drupal configurations and workflows integrating with SimpleSAMLphp Authentication module features.

Acquia will provide you with SP data, which you can then provide to the IdP. After the process completion, you will be responsible for the module configuration, and activation in the user interface.