Using SimpleSAMLphp with Drupal 10

September 21, 2024
8 minute read

Co-authored by Brandon Goodwin and Sidhartha Sharma

Installing Simplesamlphp_auth

To install the SimpleSAMLphp authentication module, run the following command:
```
composer require drupal/simplesamlphp_auth
```
Enable the SimpleSAMLphp Authentication module and add the External Authentication module as a dependency.

Creating the Symlink

Create a symbolic link in the docroot to access SimpleSAMLphp from the web:

ln -s ../vendor/simplesamlphp/simplesamlphp/public docroot/simplesaml

Setting up Configuration Directories

In your project root, create a directory simplesamlphp_files.

mkdir -p simplesamlphp_files/config simplesamlphp_files/metadata

Copy the configuration template files from the vendor/simplesamlphp/simplesamlphp directory:

In Config:

cp config.php.dist ../../../../simplesamlphp_files/config/config.php
cp authsources.php.dist ../../../../simplesamlphp_files/config/authsources.php

In Metadata:

cp saml20-idp-remote.php.dist ../../../../simplesamlphp_files/metadata/saml20-idp-remote.php

Configuring Environment Variables

Alternatively, you can use an environment variable to dictate where your configuration lives for simplesaml. For Cloud IDE, follow these steps: https://docs.acquia.com/acquia-cloud-platform/add-ons/ide/faq#section-how-can-i-set-a-custom-environment-variable-to-use-with-my-application

SIMPLESAMLPHP_CONFIG_DIR: /var/www/html/simplesamlphp_files/config

Acquia Cloud Next Env:

acli api:environments:variable-create <app>.<env> "SIMPLESAMLPHP_CONFIG_DIR" "/var/www/html/simplesamlphp_files/config"

Acquia Cloud Classic Env:

acli api:environments:variable-create <app>.<env> "SIMPLESAMLPHP_CONFIG_DIR" "/var/www/html/<app>.<env>/simplesamlphp_files/config"

Acquia Cloud IDE:

echo 'SetEnv SIMPLESAMLPHP_CONFIG_DIR "/home/ide/project/simplesamlphp_files/config"' > ~/configs/apache2/envvars.conf && acli ide:service-restart apache

(Optional) Adding Post-Install Commands to composer.json

Add the following to your composer.json within your “post-install-cmd” section, located within scripts:

"post-install-cmd": [
            "ln -f -s ../vendor/simplesamlphp/simplesamlphp/public ./docroot/simplesaml",
            "ln -f -s ../../../../simplesamlphp_files/config/authsources.php ./vendor/simplesamlphp/simplesamlphp/config/authsources.php",
            "ln -f -s ../../../../simplesamlphp_files/config/config.php ./vendor/simplesamlphp/simplesamlphp/config/config.php",
            "ln -f -s ../../../../simplesamlphp_files/metadata/saml20-idp-remote.php ./vendor/simplesamlphp/simplesamlphp/metadata/saml20-idp-remote.php"
        ]

This creates symlinks for your config and metadata files within the vendor simplesamlphp directory.

Modifying Config.php

Include acquia config php in your config.php.

To append it to your config manually:

cat << EOF >> simplesamlphp_files/config/config.php

#Include Acquia specific functions and settings
include_once("acquia_config.php");

EOF

To add this snippet to the bottom of your config.php:

if (file_exists('/var/www/site-php')) {
   require_once("/var/www/html/" . $_ENV['AH_SITE_NAME'] . "/simplesamlphp_files/config/acquia_config.php");
}

In acquia_config.php, unsure of the ide section, modify the path for the cert to search the correct path. It appears that it is missing the html part in the path).

  $config['certdir'] = "/var/www/html/{$_ENV['AH_SITE_GROUP']}.{$_ENV['AH_SITE_ENVIRONMENT']}/simplesamlphp_files/cert/";
  $config['metadatadir'] = "/var/www/html/{$_ENV['AH_SITE_GROUP']}.{$_ENV['AH_SITE_ENVIRONMENT']}/simplesamlphp_files/metadata";

Updating .htaccess

In your .htaccess, add the following snippet to prevent a permission denied error on the simplesaml path:

# Allow access to simplesaml paths
RewriteCond %{REQUEST_URI} !^/simplesaml

Ensure that you add it after the following line:

RewriteCond %{REQUEST_URI} !/core/modules/statistics/statistics.php$

Ensure that you add it before the following line:

RewriteRule "^(.+/.*|autoload)\.php($|/)" - [F]

Configuring acquia_config.php

If you are using the acquia_config.php, edit that file separately or within the relevant sections if appended to your config.php

Technical Contact Name & Email

$config['technicalcontact_name'] = "Test Name";
$config['technicalcontact_email'] = "[email protected]";

Secret Salt and auth admin password

$config['secretsalt'] = 'AddYourSaltStringHere';
$config['auth.adminpassword'] = 'ChangeThisPlease';

Generate salt

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

z50bvp9ipfy3vhtxsvzqy44jgc09zqqo

Generate password

vendor/simplesamlphp/simplesamlphp/bin/pwgen.php

Notes: Depending on where you are setting this up (Acquia Cloud or Local), you may need to change the tempdir or loggingdir to an existing path.

Configuring authsources.php

Next, provide information about your service provider (SP) and identity provider (IdP) to SimpleSAMLphp in an authsources.php file, which configures the service provider.
The values in the authsources.php file control the following settings:
- Entity ID of your SP, which is a unique identifier for your SP. This value defaults to the URL of the service provider’s metadata. You may want to override this value with a more human-readable name.
- Entity ID of your IdP, which is a unique identifier for your IdP. This value must match the entity ID value in the metadata provided to you by your IdP.
- The NameIDFormat, which your IdP includes in its metadata.
- The location of a self-signed SSL certificate, if your IdP requires your service provider to have a self-signed SSL certificate.
Previously in this tutorial, we created a copy of the authsources template, but we also provide an example file here: https://docs.acquia.com/downloadable-resources?cid=3e60e#section-authsourcesphp
Replace the entityID to a unique identifier (Your domain name is fine in this case)
Replace the idp with the metadata url provided by your idp

<?php

// This file is available at
// https://docs.acquia.com/resource/simplesaml/sources/

$config = array(
  // This is a authentication source which handles admin authentication.
  'admin' => array(
    // The default is to use core:AdminPassword, but it can be replaced with
    // any authentication source.

    'core:AdminPassword',
  ),
  'default-sp' => array(
    'saml:SP',
    // The entityID is the entityID of the SP that the IdP is expecting.
    // This value must be exactly what the IdP is expecting. If the
    // entityID is not set, it defaults to the URL of the SP's metadata.
    // Don't declare an entityID for Site Factory.
    'entityID' => 'https://' . $_SERVER['HTTP_HOST'] . '/simplesaml' . '/',

    // If the IdP requires the SP to hold a certificate, the location
    // of the self-signed certificate.
    // If you need to generate a SHA256 cert, see
    // https://gist.github.com/guitarte/5745b94c6883eaddabfea68887ba6ee6
    'certificate' => "../cert/saml.crt",
    'privatekey' => "../cert/saml.pem",
    'redirect.sign' => TRUE,
    'redirect.validate' => TRUE,

    // The entityID of the IdP.
    // This is included in the metadata from the IdP.
    'idp' => 'idp entityID goes here',

    // NameIDFormat is included in the metadata from the IdP
    'NameIDFormat' => 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient',

    // If the IdP does not pass any attributes, but provides a NameID in
    // the authentication response, we can filter and add the value as an
    // attribute.
    // See https://simplesamlphp.org/docs/stable/saml:nameidattribute
    'authproc' => array(
      20 => array(
        'class' => 'saml:NameIDAttribute',
        'format' => '%V',
      ),
    ),
    // The RelayState parameter needs to be set if SSL is terminated
    // upstream. If you see the SAML response come back with
    // https://example.com:80/saml_login, you likely need to set this.
    // See https://github.com/simplesamlphp/simplesamlphp/issues/420
    'RelayState' => 'https://' . $_SERVER['HTTP_HOST'] . '/saml_login',

    // If working with ADFS, Microsoft may soon only allow SHA256 certs.
    // You must specify signature.algorithm as SHA256.
    // Defaults to SHA1 (http://www.w3.org/2000/09/xmldsig#rsa-sha1)
    // See https://docs.microsoft.com/en-us/security/trusted-root/program-requirements

    // 'signature.algorithm'  => 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
  ),
);

Setting up SSL Certificates (If Required)

If your IdP requires an SSL cert for authentication, create a cert directory under the simplesamlphp_files directory and place both the cert and private key in that location:

Create the cert directory:
```
mkdir simplesamlphp_files/cert
```

Create Cert and Private Key:

openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem

Configuring saml20-idp-remote.php

Given the metadata XML file provided by your IDP, navigate to /simplesaml/module.php/admin/federation/metadata-converter.
Press parse. It outputs the proper input for saml20-idp-remote file.

Verifying Installation

Access SimpleSAMLphp Admin Interface: Visit https://your-domain.com/simplesaml/admin to access the SimpleSAMLphp admin interface. You must see the SimpleSAMLphp dashboard if everything is configured correctly.
Run SimpleSAMLphp Diagnostics: Use the diagnostic tools within the admin interface to check the configuration, especially the connection between your Service Provider (SP) and Identity Provider (IdP).

Common Issues and Troubleshooting

Symlink Issues: Ensure the symlinks are correctly created and point to the correct directories. If SimpleSAMLphp is not accessible, check the symlink paths.
Permission Errors: If you encounter permission denied errors, verify the file and directory permissions for simplesamlphp_files and its contents. All files should be readable by the web server.
Configuration Errors: Double-check the config.php and authsources.php for syntax errors or incorrect paths.