Using SimpleSAMLphp with your Acquia Cloud site

SimpleSAMLphp is a basic implementation of the SAML authentication protocol. It 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 that’s supported at Acquia, however, is SimpleSAMLphp.

If you’re an existing Acquia subscriber and you’d 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 very limited help. If you’re not a current Acquia subscriber, contact an Acquia sales team representative for assistance.

Note for Acquia Cloud Site Factory users

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

Installing SAML

There are three steps to installing SAML:

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

Install the PHP code

To begin installing SimpleSAMLphp, download the library . Acquia has validated the use of version 1.13.2, which we recommend as the minimum version.

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 something like simplesaml) that points to the to the www directory in the SimpleSAMLphp library. As an example:

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

These commands ensure that the web interface is publicly accessible, while keeping the configuration outside of the document root.

Install 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 message on several pages saying that SimpleSAML is not active.

Important

If you activate the sign-in before you configure the SimpleSAMLphp library, you will be unable to get back into your website easily.

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 additional assistance, see Disabling modules that block sites on Acquia Cloud.

Note

There are two issues in the module’s issue queue that may cause problems due to session cookies invalidating Varnish® caching. Please determine the status of these issues before proceeding:

Set the installation location of the Simple SAML library

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

../simplesaml

Drupal 8 websites must add the following code to your website’s .htaccess file, otherwise you the following Access Denied messages may be displayed (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]

Configure SimpleSAMLphp to communicate with your Identity Provider (IdP)

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

You can configure SimpleSAMLphp to store SAML session information in different ways. By default, it attempts to store session information as files on disk; however, with the availability of multiple web servers for highly-available production environments, those files aren’t shared across servers. Due to how file permissions are secured on Acquia Cloud and the volatile nature of tmp, Acquia does not recommend saving sessions to a file.

Instead, we recommend that you store the session information in a SQL database. The rest of this document describes using a SQL database to store session information.

Storing session information using the Acquia Cloud SQL database

The database does not need to be the same database as your Drupal installation, but there’s no harm in doing so. For the procedure 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

The version of this configuration file available prior to June 2018 was incompatible with environments named other than dev, stage, or prod. Acquia recommends that you update to the current version of this script. For assistance with troubleshooting older versions of this 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/";

These steps will 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 check box, and then configure the details for your IdP. You will need to verify and test these changes as the IdP-specific configuration is outside the scope of Acquia support.

External tool for testing

There is an excellent free external service provided by Internet2 as part of the support for Shibboleth that provides a test Identity Provider and Service Provider. For this article you may find it useful to initially test using the Test SP found at testshib.org.

SimpleSAML for Acquia Cloud Site Factory

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

  • Obtain 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 what is provided 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 that integrate with SimpleSAMLphp Authentication module functionality.

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

More Information

Thanks to Steve Moitozo, Nate Klingenstein, and Richard Bennion for their valuable technical contributions to this documentation page.

Contact supportStill need assistance? Contact Acquia Support

Acquia: Think Ahead

53 State Street, 10th Floor
Boston, MA 02109
United States
Phone: 888-922-7842

Map: Google Maps
View other locations