Most enterprise Drupal sites eventually need to stop managing passwords locally and let the company's Identity Provider handle authentication. The SAML Authentication module, usually called samlauth, lets Drupal act as a SAML Service Provider so users can sign in through Okta, Microsoft Entra ID, ADFS, PingFederate, OneLogin, Google Workspace, or another corporate IdP.

This guide walks through the practical setup: what to ask from the identity team, what to configure in Drupal, how to map users, how to test safely, and the problems that usually appear during first rollout.

What You Are Building

In a SAML login flow there are two systems:

• Identity Provider (IdP): the company's login system. This is where the user enters credentials and completes MFA.
• Service Provider (SP): your Drupal website. Drupal trusts the IdP and creates or updates the Drupal session after validating the SAML response.

The samlauth module is useful when one Drupal site connects to one primary IdP. If your Drupal site must support several IdPs at the same time, evaluate the multi-IdP extension or a broader SSO architecture before committing to the rollout.

Prerequisites

Before touching configuration, gather these items:

• Drupal 10.3+ or Drupal 11.
• Composer and Drush access to the project.
• Administrator access in Drupal.
• An IdP application created by your company identity team.
• The IdP metadata XML or the individual Entity ID, SSO URL, and X.509 signing certificate.
• A test user account in the IdP with the same attributes production users will receive.
• A recovery Drupal admin account that can still log in locally if SSO breaks.

Step 1: Install The Module

Install the module with Composer, then enable it with Drush:

composer require 'drupal/samlauth:^3.14'
drush en samlauth -y
drush cr

Commit the Composer changes and exported configuration after the setup is tested. In a deployment pipeline, the module should arrive through code, not by installing directly on production.

Step 2: Collect The Drupal SP Metadata

After enabling samlauth, go to the SAML Authentication configuration screen in Drupal. The exact route can vary by module version, but it is under Administration > Configuration > People > SAML Authentication.

Drupal exposes Service Provider metadata that the IdP needs. Give the identity team these values:

• SP Entity ID: the unique identifier for your Drupal site as a SAML application.
• Assertion Consumer Service URL: the endpoint where the IdP posts the SAML response.
• Single Logout URL: only required if you plan to support SAML logout.
• SP certificate: required if you sign authentication requests or decrypt encrypted assertions.

Use the final public production URL in metadata. Do not send localhost, DDEV, staging, or an internal container URL for a production IdP app.

Step 3: Configure The Company IdP

In the IdP, create a SAML application for Drupal. The identity team usually asks for the ACS URL, Entity ID, NameID format, and requested attributes.

Use these common settings unless your identity team requires something else:

• SAML response binding: HTTP-POST.
• NameID format: persistent or email address, depending on company policy.
• Assertion signing: enabled.
• Response signing: enabled if the IdP supports it.
• Assertion encryption: optional, but useful for sensitive environments.
• RelayState: allow Drupal to preserve the destination URL after login.

The IdP should release at least these attributes:

Step 4: Add IdP Metadata In Drupal

Back in Drupal, configure the IdP side of the trust relationship. If the IdP gives you metadata XML, use it as the source of truth. If you receive separate values, enter them manually.

At minimum Drupal needs:

• IdP Entity ID.
• Single Sign-On Service URL.
• X.509 signing certificate.
• Expected NameID format, if your IdP enforces one.

Keep the certificate formatting intact, including the BEGIN and END lines. A surprising number of SAML failures are caused by certificates pasted without line breaks or copied from the wrong environment.

Step 5: Configure User Matching And Account Creation

This is the most important design decision. Decide how a SAML identity maps to a Drupal user account.

Recommended approach:

• Use an immutable identifier such as employee ID, object ID, or persistent NameID as the primary key.
• Map email into Drupal's email field, but avoid using email as the only permanent identifier if your company changes email addresses.
• Enable automatic account creation only after the IdP app assignment rules are correct.
• Keep role assignment conservative at first. Start with authenticated user access, then add group-to-role mapping later if required.

If existing Drupal users already exist, test account linking with a small pilot group before enabling everyone. Duplicate accounts are painful to unwind after launch.

Step 6: Protect The Login Experience

Decide how users enter SSO:

• Add a “Login with Company SSO” link to the login page.
• Redirect selected protected paths to SAML login.
• Keep local login available for administrators, or restrict it to a private admin path protected by network rules.

Do not remove local admin access until SSO has been tested in production with a break-glass account. If the IdP has an outage or the certificate expires, you still need a way to repair Drupal.

Step 7: Test With A Pilot User

Use an incognito browser window and a test user assigned to the Drupal app in the IdP.

1. Visit a protected Drupal page or click the SSO login link.
2. Confirm Drupal redirects to the company IdP.
3. Complete login and MFA at the IdP.
4. Confirm the browser posts back to Drupal's ACS URL.
5. Confirm Drupal creates or matches the correct user account.
6. Confirm the user lands on the original destination URL.
7. Log out and confirm the expected logout behavior.

Review Drupal logs immediately after each test. If the login fails, the first useful clue is usually in recent log messages.

Common Challenges And Fixes

1. ACS URL Mismatch

Symptom: the IdP accepts login but fails when sending the user back to Drupal.

Fix: compare the ACS URL in the IdP with the URL shown in Drupal metadata. The scheme, host, path, and trailing slash must match. Also check reverse proxy settings so Drupal generates public HTTPS URLs instead of internal HTTP container URLs.

2. Certificate Mismatch Or Expiry

Symptom: Drupal rejects the SAML response with signature validation errors.

Fix: update Drupal with the current IdP signing certificate. Track certificate expiration dates before production launch and create an operational reminder before renewal.

3. Clock Drift

Symptom: errors mentioning NotBefore, NotOnOrAfter, or an assertion that is not yet valid.

Fix: sync server time with NTP on Drupal infrastructure and confirm the IdP time is also correct. SAML assertions are intentionally time-limited.

4. Missing Email Or NameID

Symptom: Drupal receives a valid SAML response but cannot create or match a user.

Fix: ask the identity team to confirm the exact attribute names being released. Attribute names are case-sensitive and may differ between IdPs.

5. Duplicate Drupal Accounts

Symptom: the same employee gets a second Drupal account after SSO.

Fix: review the matching identifier. If existing users were created by email and SAML uses employee ID, plan a one-time account-linking migration before broad rollout.

6. Redirect Loop After Login

Symptom: login succeeds but the user is immediately sent back to the IdP.

Fix: check Drupal session cookie settings, HTTPS termination, trusted host settings, reverse proxy headers, and whether the user account is blocked or missing required access.

7. Group Claims Are Too Large

Symptom: SAML response size becomes huge or login fails for users in many company groups.

Fix: ask the IdP team to release only application-specific groups, not every group the employee belongs to. Map only the groups Drupal truly needs.

Security Checklist Before Production

• Require signed assertions, and validate signatures in Drupal.
• Use HTTPS everywhere, including behind reverse proxies.
• Keep a break-glass local admin account.
• Document IdP certificate rotation dates.
• Restrict auto-provisioning to users assigned to the Drupal IdP app.
• Do not grant Drupal administrator roles directly from broad IdP groups.
• Export configuration and deploy it through the normal release process.

Deployment Notes

After the setup works locally or in staging, export Drupal configuration:

drush config:export -y
git status
git add composer.json composer.lock config/sync
git commit -m "Configure SAML authentication"

On production, deploy code first, then run database updates, import configuration, and rebuild cache:

drush updatedb -y
drush config:import -y
drush cache:rebuild

If the IdP configuration contains secrets or private keys, do not commit those values directly. Use environment-specific configuration overrides or a secrets manager, depending on your hosting model.

Final Thoughts

A successful SAML rollout is less about clicking the right checkbox and more about agreeing on trust boundaries: exact metadata, stable identifiers, certificate rotation, and account lifecycle. Start with a pilot group, keep local admin recovery available, and treat the IdP metadata as production infrastructure.

Once the basic login is stable, you can improve the experience with destination redirects, group-based role mapping, profile synchronization, and a cleaner branded login button.