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 customer 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 customer, contact an Acquia sales team representative for assistance.

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 currently has validated that customers have successfully used version 1.13.2. This is recommended as a 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 theSimpleSAMLphp library. As an example:

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

This ensures that the web interface is publicly accessible, but keeps the configurations 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.

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. See Disabling modules that block sites on Acquia Cloud for help.

Set the Installation location of the Simple SAML library

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

 ../simplesaml

 

Note for Drupal 8 sites: you need to add the following to your .htaccess file, otherwise you may see Access Denied messages  (documented in http://cgit.drupalcode.org/simplesamlphp_auth/tree/README.md?h=8.x-3.x#n116 ) 

 

  # 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, we don't 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 Managing your databases.

To connect to the High Availability (HA) database on Acquia Cloud Enterprise, add the gist code snippet to the bottom of the config.php file, where [ah_database_name] is the workflow database name for your environment.

Download the gist file here.

An example modification:

To support multisite installs use the following example code after line 18 (the custom area) of the gist code snippet:

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

These steps will allow you to leverage the SimpleSAMLphp GUI. The SimpleSAMLphp documentation is located at http://simplesamlphp.org/docs/stable/, which 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.

Cookie and caching issues

One feature generally expected from a Single Sign On solution is that if a visitor has already authenticated on a different website that they are automatically authenticated when visiting the Drupal website. This is a very user friendly feature that ensures a seamless transition between websites. However, it can come at the cost of decreased caching by the Varnish layer.

When the NO_CACHE cookie is set, it automatically bypasses Varnish caching. This can be highly detrimental to performance if you have mostly anonymous users or a website that doesn't need everyone to be authenticated.

If you remove the setcookie() function call from the gist code snippet, a visitor who is not signed in will not be automatically signed in on the new website and will receive a cached version of most pages. These users can still visit the normal SAML login page (/saml_login) and sign in using the SAML IdP. All non-authenticated users will receive cached pages. This can be very helpful for high traffic websites that only have a limited number of authenticated users, like editors need to actually sign in to make changes.

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 http://www.testshib.org/.

SimpleSAML for Acquia Cloud Site Factory

If you're an Acquia Cloud Site Factory customer, you cannot configure the server side of SimpleSAMLphp on your own — you must engage with Acquia 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:
          /mnt/gfs/mydocroot.env/files-private/sites.json

    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.

Add new comment

Plain text

  • No HTML tags allowed.
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.
By submitting this form, you accept the Mollom privacy policy.

Contact supportStill need assistance? Contact Acquia Support