Four Kitchens: Don’t let SimpleSAMLphp block your Drupal upgrade

• 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

1. Install SAML Authentication

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.

1. Run composer require drupal/samlauth

2. Install the helper module

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. 1. 1. 1. 1. Add the sandbox as a custom repository into your composer.json:
               You will have to go and search in your code for any SimpleSAMLphp usage and change it!
               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:

               3.1. Before migrating

               Although this library and module is a great resource for SAML integrations, it conflicts with Drupal upgrade paths, hindering the efforts to keep Drupal sites up to date. This is the case for sites that want to upgrade to Drupal 11. If your site has this dependency, you may be stuck until there’s a compatible version of the library.
               Having the whole context of what we need to be careful about, let’s migrate the config! It’s very simple:
               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.
               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.
               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!

               3.2. Known caveats

               The good news is that there’s another PHP library for SAML integrations that has a Drupal contributed module, and it has no conflicting dependencies with Drupal Core! The module is called SAML Authentication, and it uses OneLogin SAML toolkit for PHP. This guide will provide you with the steps for an easy and seamless migration from the SimpleSAMLphp module to SAML Authentication!
               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 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”.

               3.3. Migrate the configuration

               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.

               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

               “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’s a supported, Drupal-friendly alternative, the SAML Authentication module, that avoids these conflicts entirely. Even better, the community has built tooling to make migration significantly easier than you might expect.

1. 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:
      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.
      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.
      /**
      * 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 Drupalsamlauth_simplesamlphp_auth_migrationMigrate $saml_auth_utility */
      $saml_auth_utility = Drupal::service(‘samlauth_simplesamlphp_auth_migration.migrate’);
      $saml_auth_utility->updateAuthmapTable();
      }

PHP applications integrating with SAML have relied on the SimpleSAMLphp library. Following this standard, the Drupal community created the SimpleSAMLphp Authentication module, which is used by more than 14,000 sites (as of this publication), to provide SSO authentication integration for Drupal sites.

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)

/**
* 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

January 22, 2026
By migrating now, you’ll ensure your Drupal site is ready for Drupal 11 without downtime or dependency conflicts, and you can take advantage of the latest features immediately.

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

4.1.1. Pantheon special routing rule

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.
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:
Before migrating, there are a few decisions worth making. Let’s dive into them!
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.
Naturally, because we want to migrate into SAML Authentication, we need to install it on our site.
Robert always aims to engineer software that is maintainable, scalable, and reusable while always trying to improve himself and learn from others.

4.1.2. Testing workaround

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.

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.

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.

5. You’re almost there

Before speaking about these issues, these are the remote host providers the masquerading will work:
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.

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.

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.

6. Hurray!

This guide walks through a practical, field-tested approach to migrating from SimpleSAMLphp to SAML Authentication — so you can unblock your Drupal 11 upgrade path without downtime or guesswork.