fidzu : web

• Higher ed Drupal teams planning for Drupal 11
• Platform owners managing SSO across multiple environments
• Engineers who want to reduce upgrade risk caused by third-party dependencies

The SAML Authentication module is a really straightforward resource to set up SSO into your site. From my point of view, it's way easier to configure and maintain than SimpleSAMLphp, so, even if you're not worried about upgrades (though should you be, read our post about upgrading to Drupal 11), this module will make the maintenance of your site less complicated. However, it's not perfect. It has its caveats, which I will cover!

Most of the configuration required for SAML Auth is already handled in your site's SimpleSAMLphp settings. However, there's already a tool that automates this task!

If you read the Drupal 11 compatible issue thread for SimpleSAMLphp, you will stumble upon Jay Beaton's comment: He created a helper module to automate the migration of SAML Auth from SimpleSAMLphp. This module will make the switch pretty fast! However, depending on your site's setup, you must be careful on what settings you're migrating, especially if the configuration varies by environment.

Before migrating, there are a few decisions worth making. Let's dive into them!

1. Install SAML Authentication

Naturally, because we want to migrate into SAML Authentication, we need to install it on our site.

1. Run composer require drupal/samlauth

2. Install the helper module

The SimpleSAMLphp to SAML Auth Migration module is currently in development, so the module itself is a sandbox project in Drupal.org. In order to install it, you need to:

1. Add the sandbox as a custom repository into your composer.json:

   "samlauth_helper": {
               "type":"package",
               "package": {
                   "name": "drupal/samlauth_simplesamlphp_auth_migration",
                   "version":"1.0.0",
                   "type": "drupal-module",
                   "source": {
                       "url": "https://git.drupalcode.org/sandbox/jrb-3531935.git",
                       "type": "git",
                       "reference":"1.0.x"
                   }
               }
           }

2. This is the composer command: composer config repositories.samlauth_helper '{"type": "package", "package": {"name": "drupal/samlauth_simplesamlphp_auth_migration", "version": "1.0.0", "type": "drupal-module", "source": {"url": "https://git.drupalcode.org/sandbox/jrb-3531935.git", "type": "git", "reference": "1.0.x"}}}'
3. Require the module: composer require drupal/samlauth_simplesamlphp_auth_migration
4. Enable it: drush en samlauth_simplesamlphp_auth_migration -y

3. Migrate the configuration

There are two ways for you to migrate the configuration: either through drush commands or through the UI. For the purpose of this article, we will migrate the configuration through the command line, however, you can do it through the UI in this path: admin/config/people/saml/simplesamlphp-auth-migration.

That path also provides a nice visualization of the configuration mapping and migration that will be performed. You can also view it running drush samlauth-simplesamlphp-show-changes command.

3.1. Before migrating

Usually, sites have different setups for different environments, such as testing, development, or production. Each environment may have its own configuration, and if you're running a migration locally, SimpleSAMLphp might not even be enabled.

Knowing this, depending on where you're running the migration, you will need to manually set some of the settings yourself. For example, the staging environment uses a different certificate than production. Locally, the staging environment SimpleSAMLphp settings are enabled by default. When you run the migration command, the settings for the active environment will be migrated over, not the other for production.

Another example is that the Entity ID of the SP is dynamic, depending on the environment. If so, you will need to override the SAML Authentication settings, rather than the SimpleSAMLphp.

For the ones that need to be migrated manually, you can either set up a config split for each environment, or you can do some configuration overrides through settings.php. Just beware that, if you need to override arrays, it may not be possible to override them through settings.php. Read more about the issue.

I've done both approaches. The approach you take will depend on your site. I've set different configuration splits, and have overridden values through settings.php. In my case, I just create a settings.saml.php file and include it in settings.php.

3.2. Known caveats

Although SAML Authentication is way simpler to set up, it's missing a feature SimpleSAMLphp provides: you can link a remote IdP certificate. In SAML Authentication, the files must be physical in your server. You can only link their path.

This means if your site has remote IdP certificates, you will have to copy its contents and create the files into your site folder. This may make your maintenance process a bit more nuanced, as if the IdP certificates change, you will have to update the physical files from your site.

For the purposes of this migration, if you are linking to remote IdP certificates, you will have to create the files. I've faced two situations: remote and local files. For the remote certificates, I decided to put them into web/private/saml-certificates.

3.3. Migrate the configuration

Having the whole context of what we need to be careful about, let's migrate the config! It's very simple:

1. Run drush samlauth-simplesamlphp-migrate
   1. You can provide the --cert-path for your certificate path; or
   2. You can go to /admin/config/people/saml/saml and add it into the X.509 certificate(s) field
2. Confirm it was migrated correctly
   1. You can compare against your SimpleSAMLphp configuration

3.4. The Auth Map table

Both SimpleSAMLphp and SAML Authentication use the External Authentication module, it allows a SAML authenticated user with an authname identical to the one in the authmap table to be logged in as that Drupal user. Among those values, it stores the provider, i.e., the module that allowed the authentication.

The SAML helper module automatically migrates the SimpleSAMLphp authmap values into SAML Authentication. However, this is a database migration, so, if you migrated locally and then pushed your changes into a remote environment, this migration won't be reflected there. To make sure it also happens, you can:

1. If you keep the helper module in your remote environments, you can create an update hook that calls the service that makes the changes:

   /**
    * Enable SAML auth migration module and update authmap table.
    */
   function hook_update_N(): void {
     if (!\Drupal::moduleHandler()->moduleExists('samlauth_simplesamlphp_auth_migration')) {
       \Drupal::service('module_installer')->install(['samlauth_simplesamlphp_auth_migration']);
     }
     /** @var \Drupal\samlauth_simplesamlphp_auth_migration\Migrate $saml_auth_utility */
     $saml_auth_utility = \Drupal::service('samlauth_simplesamlphp_auth_migration.migrate');
     $saml_auth_utility->updateAuthmapTable();
   }
   

Or, you can just do it yourself:

/**
 * Enable SAML auth module and update authmap table.
 */
function hook_update_N(): void {
  if (!\Drupal::moduleHandler()->moduleExists('samlauth')) {
    \Drupal::service('module_installer')->install(['samlauth']);
  }

  \Drupal::database()
    ->update('authmap')
    ->fields(['provider' => 'samlauth'])
    ->condition('provider', 'simplesamlphp_auth')
    ->execute();
}

4. Testing the new SAML Authentication

Once you've migrated over everything, the last step is to test if the configuration migration actually works. In order for you to test it, you will need to make changes to your IdP with the new values of the new SAML implementation: the metadata URL, the Assertion Consumer Service, and the Single Logout Service.

If you don't want to override the existing values from your current SAML IdP, you can modify the Entity ID for SAML Authentication to create a new one, that way you could have two entries in you IdP for SimpleSAMLphp and SAML Authentication.

Regardless, it may be the case that making such a change could take some time if it's handled by another team. If that's the case, you would have to wait until those changes are implemented to test the new SAML implementation. Fortunately, the SAML Auth helper module provides a way to masquerade SimpleSAMLphp endpoints with SAML Auth implementations, that way you can test right away without having to make any changes to the IdP. You would eventually need to do it, but for testing purposes, you can use the helper module. To do so, you have to:

1. Remove the simplesaml folder from your web/docroot folder
2. Disable the simplesamlphp_auth module
3. Remove any composer script/automated script that symlinks any SimpleSAMLphp related behavior
4. Enable the Use SimpleSAMLphp Authentication Routes option offered by the SAML Auth helper module (find it on admin/config/people/saml/saml)

Once that's done, you can try and log in using SSO into the site you're trying to migrate. If it works, fantastic! You only need to (i) request the IdP changes for you to completely move away from SimpleSAMLphp, and (ii) you can remove the helper module.

4.1. Remote host provider issues

In some cases, SSO is enabled in certain specific environments. That means you may want to test on those environments; you only need to deploy and let the environment be built with the new changes. However, it is not as straightforward as you may think. As a matter of fact, the helper module route masquerading may not even work.

Before speaking about these issues, these are the remote host providers the masquerading will work:

1. Acquia
2. Platform.sh (though you will have to edit the .platform.app.yml file)

4.1.1. Pantheon special routing rule

If your site is hosted on Pantheon, the helper module masquerading won't work. This is due to a specific routing rule Pantheon seems to have.

If you try and test the new SAML implementation with the helper module, you will get a HTTP 404 error, specifically stating that the file was not found - a text 404, completely different from your Drupal 404. In order to test this with the helper module, the steps (from the module itself) specify that "Make sure that SimpleSAMLphp is not available on the server at https://site/simplesaml/module.php".

Even after removing the library from your web/docroot, the helper module won't work on Pantheon. After some testing and investigation, and knowing that Pantheon uses Nginx for routing, I was able to confirm Pantheon has a special rule for paths that go to /simplesaml/*.php.

Any path following that pattern won't be routed through Drupal. Nginx makes sure to look up for a file inside your web/docroot simplesaml folder. Hence why I was getting a text 404, instead of Drupal's 404. I made a test to confirm this: I placed a hello.php file inside that folder that just returns a simple text message. When I went to /simplesaml/hello.php I was getting said message.

Due to this fact, the helper module route masquerading won't work because that's a path expected to be handled by Drupal; on Pantheon, that won't be the case. It won't work.

But, good news is, there's a workaround you can use in order to confirm your migration worked! Before diving into that, I want to give a shout out to Jay Beaton, the helper module maintainer! I reached out to him on Drupal Slack about the route overrides not working. He was kind enough to listen and help me; and, after talking to him, I was able to realize and discover this Pantheon issue; and the workaround I'm going to mention was recommended by him. Thanks so much for such a great tool, and help!

4.1.2. Testing workaround

Even if you cannot test remotely, you can do it locally. SAML validation and redirections happen on the browser level, meaning that, if you change your machine DNS to point a SSO-enabled domain to your local machine environment, you will be able to test it there. This is how you do it:

1. For DDEV, you need to edit the config.yaml file and:
   1. Add the domain you want to override in the additional_fqdns property
   2. Switch to false the use_dns_when_possible property, so DDEV always updates the /etc/hosts file with the project hostname instead of using DNS for name resolution
   3. Restart DDEV
   4. If for some reason the custom domain is not reaching your local environment, make sure the custom domain is in your /etc/hosts file.
2. For lando, you can add proxies with custom domains.
   1. You will need to edit your /etc/hosts file.

And that's it! You can now go to the custom domain while using your local environment!

5. You're almost there

With the configuration migrated over to SAML Authentication, you should be able to use SSO. However, if your site has custom code that uses SimpleSAMLphp services or is hooked into one of its hooks, you will need to adjust your code accordingly.

For example, from the sites I've migrated:

1. There was code that was using the simplesamlphp_auth.manager service, specifically to call the isAuthenticated() function.
   1. I changed it to use the SAML Authentication service, samlauth.saml, and calling the getAttributes() function, which does the same as SimpleSAMLphp isAuthenticated() (it gets the attributes if the current user was logged in using SSO, otherwise, it returns an empty array).
2. The hook_simplesamlphp_auth_user_attributes and hook_simplesamlphp_auth_existing_user hooks were being used.
   1. I had to create an Event Subscriber (as SAML Authentication doesn't use hooks for these) that hooks to SamlauthEvents::USER_LINK, equivalent to the existing user hook, and SamlauthEvents::USER_SYNC, equivalent to user attributes hook.

You will have to go and search in your code for any SimpleSAMLphp usage and change it!

6. Hurray!

That's it. With SimpleSAMLphp out of the way, your Drupal site is no longer blocked by upstream dependencies - and you're free to plan your Drupal 11 upgrade on your timeline. Happy coding!