What SSO means for a Drupal site
Drupal single sign-on means the site stops keeping its own passwords as the main way people sign in and instead trusts an external identity provider. In practice Drupal takes one of two roles. It can act as a SAML service provider, using the contributed SAML Authentication module (samlauth), or as an OpenID Connect relying party, using the contributed OpenID Connect module. LDAP is a different pattern: Drupal queries a directory to check credentials or look up attributes, but the user still arrives at a Drupal login form. Decide which pattern fits your identity provider before anything else, because it sets the configuration, the test plan and the support burden.
The sign-in is the easy part. The account lifecycle is where most of the work sits. Decide what happens on first sign-in (whether an account is created automatically, and with which username and email), how roles are assigned from identity provider attributes or groups, and how an account is disabled or removed when someone leaves. Each of these needs a written rule and a test. Without them, accounts pile up, and former staff keep editorial rights that nobody reviews.
Teams usually need this for one of three reasons: staff-only editorial access behind the corporate identity provider, customer or citizen logins to a portal, or consolidating accounts that already exist in another system. Each reason leads to different decisions about account linking, self-registration and who can grant roles. Linking an existing local account to a federated identity, for example, is a common source of duplicate or hijacked accounts if the matching key is an email address that is not verified.
Plan for roles that drift and for admin access that survives an outage. Roles in Drupal and roles in the identity provider will diverge over time unless one side is the source of truth and the other is checked on a schedule. Keep at least one local administrator account that works when the identity provider is down, store its credentials under your own control, and test that path. Confirm the current compatibility of the samlauth and OpenID Connect modules with your target Drupal core version on their Drupal.org project pages before you commit to a design.
Components and extension points involved
A Drupal SSO build touches a small set of contributed modules, core account and role handling, and environment configuration. Each piece has a specific configuration task and a specific check that should pass before users depend on it.
SAML Authentication module
The contributed samlauth module lets Drupal act as a SAML service provider. The team configures the identity provider metadata, entity IDs, certificates and attribute mappings, then verifies signed assertions, audience restriction and the login and logout flows against the identity provider's test users. Confirm the release supports your Drupal version before you commit to it.
OpenID Connect module
The contributed OpenID Connect module authenticates users from an external OpenID Connect provider and creates accounts on first sign-in. It ships with built-in clients for generic OAuth 2.0, GitHub, Google, LinkedIn, Facebook and Okta. The team chooses the client, sets redirect URIs and scopes, and verifies that the account created on first sign-in carries the expected email and username.
LDAP contributed modules
Contributed LDAP modules handle directory binding, authentication and attribute lookup against Active Directory or another LDAP directory. The team configures a service bind account with read-only rights, base distinguished names, search filters and the attributes to map. Confirm the current module set and its Drupal compatibility on the project pages before planning around it.
Users, roles and permissions
Drupal's core user, role and permission system is where identity attributes finally take effect. Mapped groups or claims should land on specific roles, and those roles determine what each person can edit or administer. The team reviews the permission matrix for every mapped role and verifies that a user removed from the identity provider loses access on the next sign-in.
Settings and environment configuration
Client secrets, certificate paths, directory bind passwords and endpoint URLs belong in settings.php or environment configuration, not in exported configuration that is committed to version control. The team confirms that these values differ per environment, that file permissions on settings.php are restricted, and that a configuration export contains no secrets.
Local administrator fallback
Local accounts, including at least one administrator, must remain able to sign in when the identity provider, directory or certificate is unavailable. The team decides which accounts stay local, stores their credentials under controlled custody, and tests that the fallback works in a non-production environment before cutover.
Decisions and trade-offs
This table compares the main SSO and identity choices for Drupal, showing when each fits and what it costs to run and reverse.
| Decision | When it fits | Operational cost and offboarding |
|---|---|---|
| SAML through samlauth | Your identity provider speaks SAML 2.0 and your team already manages SAML metadata. Samlauth 8.x-3.14 supports Drupal 10.3 and later and Drupal 11. | Service provider certificate and metadata rotation on a planned calendar. Offboarding depends on disabling the user at the IdP, then checking active Drupal sessions. |
| OpenID Connect through the OpenID Connect module | Your provider offers OIDC, such as Keycloak, authentik, Zitadel or Okta, or you need built-in clients for common providers. | Client secret rotation, redirect URI maintenance and claim mapping. The module creates accounts on first sign-in, so confirm how a disabled IdP user is blocked in Drupal. |
| LDAP direct bind or lookup | A directory is the only identity source and no front-end provider is planned. Drupal checks credentials against the directory itself. | A bind service account with least privilege, enforced TLS and a password rotation process. Offboarding relies on directory disablement and a scheduled sync to block Drupal accounts. |
| Federation through an identity provider | Several applications share one login, MFA policy and session controls must sit in one place, and upstream directories stay authoritative. | Operating the provider itself, including patching, backups and connector health. Offboarding has one control point, so review its session lifetimes. |
| Just-in-time account creation versus pre-provisioned accounts | Just-in-time suits simple roles that follow IdP membership. Pre-provisioning suits sites where an approver must release access before first login. | Just-in-time needs a least-privilege default role and a rule for stale accounts. Pre-provisioning needs an import job that matches directory changes, including removals. |
| Role mapping inside Drupal versus at the identity provider | Drupal mapping suits a few Drupal-specific roles. IdP group claims suit organizations that already govern access centrally across applications. | Drupal mapping lives in site configuration and needs review on each release. IdP claims must stay consistent, and a removed group only takes effect at the next token issue. |
| Existing identity provider in front of Drupal | An identity provider such as Keycloak, authentik or Zitadel already serves other applications, so Drupal joins its existing login. | A second system to patch, back up and monitor, plus its certificates. Offboarding becomes a single disable point, but an outage there blocks every linked application. |
| Local accounts alongside SSO | Keep one break-glass administrator with MFA and a sealed credential for provider outages. Disable other local logins once SSO is verified. | Test the break-glass path on a schedule and log each use. Remaining local accounts become a second offboarding list that must be reviewed with the directory. |
Build sequence
This sequence takes the Drupal site from confirmed versions and an agreed identity contract to a tested, logged and reproducible SSO configuration in production.
Confirm Drupal, PHP and module versions
Confirm the Drupal core version, PHP version and identity module release together before any configuration starts. The Drupal.org PHP requirements page lists PHP 8.1 or later for Drupal 10 and PHP 8.3 or later for Drupal 11. The SAML Authentication module's latest stable release, 8.x-3.14, supports Drupal 10.3 and later and Drupal 11. Done when a signed compatibility sheet exists and a test build resolves cleanly with Composer.
Inventory the identity provider and fix the attribute contract
The identity team lists which protocols the provider supports (SAML, OpenID Connect or LDAP), the attributes it releases, and how group claims are named and scoped. Drupal and the identity team then agree on one protocol and one attribute contract covering the user identifier, email, display name and group values. Done when both teams sign the contract and a sample assertion or token from the provider matches it.
Register Drupal as a service provider or client
Create the Drupal application in the identity provider and set the entity ID or client ID, the assertion consumer or redirect URIs for each environment, and the logout endpoints. Exchange SAML metadata or client credentials through an approved secure channel. Done when the provider shows the registration for each environment and the metadata or discovery document loads without errors.
Configure the module with a test identity provider
Install the SAML Authentication module or the OpenID Connect module in a non-production environment and point it at a test identity provider tenant. Enter the provider settings and enable sign-in only for that tenant, storing the settings in configuration. Done when a known test account signs in, reaches the expected page, and its Drupal user record carries the identifier defined in the contract.
Map attributes to fields and roles
Map each contract attribute to a Drupal user field, then map each identity group to a Drupal role that carries only the permissions it needs. Sign in with one test account per group to check the result. Done when a role assertion review shows each test account holds exactly the roles its group should, and no federated account receives administrator by default.
Set account rules and lock down the login path
Decide whether first sign-in creates an account or only pre-provisioned users can enter, and how existing local accounts link to an identity. Keep one named local administrator as a fallback, restrict password login to that account, and review every remaining login route. Done when a failed federated sign-in produces a logged denial and the fallback account still signs in.
Promote the configuration through configuration management
Export the identity settings, role mappings and login-path changes into version-controlled configuration, then review the export diff before deploying. Import the same reviewed configuration into staging and then production, keeping client secrets and environment-specific metadata outside the repository. Done when staging passes the earlier login tests and production configuration matches the reviewed export.
Security, access control and secrets
These checks cover the SSO layer itself, from identity provider validation to the accounts and secrets it creates. General Drupal controls are covered in the Drupal security hardening topic.
Validate SAML assertions and OIDC tokens
In the SAML Authentication module, require signed responses and assertions from your identity provider's certificate, and track that certificate for expiry and rotation. In the OpenID Connect module, set the issuer to the exact value your provider publishes, confirm the client ID is the expected audience, and verify signatures against the provider's published keys. Test a tampered or expired assertion and a wrong-audience token on staging, and confirm that both are rejected.
Keep secrets and keys out of code
OIDC client secrets, the SAML service provider private key and any LDAP bind password should load from environment variables or a secrets store, never from settings files committed to Git. Restrict read access on the web hosts, and rotate these values after staff changes. Check that configuration export does not write secret values into exported files. Confirm which secrets store your team already operates.
Restrict group-to-role mapping
Map identity provider groups to Drupal roles through an explicit allowlist, and require named groups that your identity team controls before any administrator or editor role is granted. Missing or empty group claims should grant no elevated role. Because the OpenID Connect module creates accounts on first sign-in, review the default role for new accounts, and repeat the mapping review after each directory reorganization.
Limit and monitor break-glass accounts
Keep a small number of local administrator accounts for use only when the identity provider is unavailable. Give each one a unique, long password stored in a sealed vault, disable interactive login for them during normal operation, and alert on every sign-in through the site's logging. Test the recovery procedure on a schedule so these accounts work when they are needed.
Enforce HTTPS and exact redirect URIs
Serve the site and every SSO endpoint over HTTPS only, and set HSTS at the web server so SAML responses and tokens never travel in clear text. Register exact redirect URIs with each identity provider and avoid wildcards, because loose matching can send authorization codes to an unintended location. Confirm that the registered URIs match the public hostname used in production.
Keep SSO modules patched
Track Drupal Security Team advisories for the contributed SAML and OpenID Connect modules as well as Drupal core. Core security releases land on the third Wednesday of the month, and the Security Team uses Wednesday windows for advisories, so schedule a review in those windows. Test each update in staging with a saved SAML and OIDC sign-in before production, and confirm how your Composer lock file pins these modules.
Verification and failure behavior
Treat SSO as finished only when every login path has a test that proves the expected Drupal result, and every failure path has been forced on purpose and shown to fail closed. Start with six functional cases: a first-time SAML or OpenID Connect sign-in creates the expected Drupal account with the expected email and username; a returning user keeps the roles mapped to their identity provider groups; removing a user from a group changes their Drupal access on the next sign-in, as your role mapping design specifies; an expired or mismatched assertion (wrong audience, wrong issuer, bad signature or stale timestamp) is rejected; a Drupal account blocked in the admin interface cannot sign in through SSO; and the break-glass administrator can still sign in with its local password when the identity provider is unreachable.
Next, rehearse the failure modes that cause most production incidents. Test an identity provider outage and confirm the login page still offers the break-glass path. Rehearse certificate rollover by publishing the new signing certificate, then switching the identity provider, and confirm the SAML module accepts assertions from both during the overlap window. Introduce clock skew between the Drupal web servers and the identity provider to see whether assertions are rejected at the expected tolerance. Rename a mapped attribute in a test identity provider and confirm the mapping fails visibly instead of silently assigning no roles. Create two identities that share an email address across the LDAP directory and the identity provider, and decide in advance which source wins. Finally, lock the LDAP service account and confirm sign-ins fail with a clear message and an alert.
For each test, confirm the evidence, not just the outcome. Check the Drupal watchdog or your central log pipeline for an entry naming the failure type, the identity provider and the time, and make sure no password or assertion content is written to the log. Then confirm the user experience: a failed SSO attempt should show a plain error message with a next step, such as contacting the help desk, and should never fall through to an anonymous session or an open form. Keep the test results, the configuration version and the names of the testers in your change record. Ask your implementation partner to show these results as part of acceptance, and confirm which logging sink, alert channel and retention period your organization requires before testing begins.
Effort drivers and how to keep them down
This table lists the factors that most change the effort of a Drupal SSO build and the practical steps that keep each one contained, so you can see where a scope will grow before it is signed.
| Driver | Why it changes effort | How to keep it down |
|---|---|---|
| Identity providers and protocols | Each provider adds its own metadata, certificate or client registration, claim format and test cases. SAML and OpenID Connect use different configuration paths in the SAML Authentication and OpenID Connect modules. | Use one identity provider for all Drupal sites. Confirm which protocol each site needs before the build starts and avoid enabling both unless a real requirement exists. |
| Quality of directory and attribute data | Missing, duplicated or inconsistently formatted attributes such as email, username or department force custom mapping and extra exception handling in Drupal. | Agree an attribute contract before build: names, formats, which attribute is the unique key and what happens when a value is absent. Ask the identity team to confirm it in writing. |
| Roles and group rules to map | Every identity group that must map to a Drupal role adds rules, edge cases and permission reviews. Many small groups multiply the test matrix. | Limit Drupal roles to a short list that matches the permissions editors and administrators truly need. Map groups to roles in one reviewed table rather than one rule per team. |
| Account linking and existing local accounts | Existing Drupal users must be matched to identity provider accounts without duplicates. Matching on email alone can link the wrong person, and migrating passwords is usually not possible. | Decide early whether local accounts are linked, disabled or kept for break-glass use. Run a matching report on a copy of production data before go-live. |
| Number of Drupal environments | Each environment needs its own redirect URIs, certificates or client secrets, and settings. Configuration drift between development, staging and production causes most late defects. | Keep identity settings in version-controlled configuration with environment-specific values stored as secrets. Use the same provider tenant for every environment where possible. |
| Changes to the identity team's own configuration | If the identity team must register clients, add claims, change group sync or approve certificates, the work depends on their queue and change process, which can add waiting time. | Ask for the required changes to be listed in the scope and scheduled with the identity team at kickoff. Prepare the exact client settings and claim lists so their review is quick. |
| Compliance evidence needs | Assessors may ask for proof of MFA enforcement, access reviews, logging of sign-ins and documented role assignments. Collecting this after the build adds work. | Define the evidence list at scoping and set up logging and role documentation during the build. DeployOpen prepares evidence for assessments, but independent auditors decide whether controls are sufficient. |
| Test plan written late | Without agreed test cases for first sign-in, role changes, deprovisioning and failure of the provider, defects surface during acceptance and reopen design decisions. | Fix the test plan early, covering sign-in, attribute edge cases, role mapping, account linking, logout and a recovery path if the provider is unavailable. Agree the acceptance criteria in writing. |
Frequently asked questions
Should we use SAML or OpenID Connect for Drupal single sign-on?
The answer depends on what your identity provider supports and what your team already runs. Drupal can act as a SAML service provider through the contributed SAML Authentication module (samlauth), and it can accept external OpenID Connect sign-in through the contributed OpenID Connect module. If your identity provider is already configured for one protocol, that protocol is usually the lower-effort path. Confirm the protocol support of your identity provider and the module versions against your Drupal version before you decide.
What drives the cost and timeline of a Drupal SSO project?
The main drivers are the number of identity sources, the quality of the attributes your identity provider sends, and how many roles must map to Drupal permissions. Each identity provider configuration, certificate or client registration, and test environment adds work. Role mapping rules that depend on group nesting or business logic take longer to design and verify than a simple one-to-one mapping. Ask any partner for a quote that lists these items separately, and state which environments and identity providers are in scope.
What do we need from the identity team and the Drupal team?
The identity team supplies the identity provider configuration, the metadata or client details, the attribute and group names, and test accounts across user types. The Drupal team supplies the site environments, decisions on account creation and role rules, and sign-off on login, logout and session behavior. Both teams should agree early on which attribute is the stable user identifier, because changing it later can disconnect existing accounts. Agree on who owns certificate and secret rotation before go-live.
Can our internal team build Drupal SSO without a partner?
Yes, if your team has Drupal module configuration experience and someone who can operate the identity provider. Both modules are contributed projects, so your team must track their releases, Drupal version compatibility and security advisories. The harder parts are usually the identity provider side, role mapping edge cases and failure testing, such as an expired certificate or a missing attribute. A partner can be useful for a fixed-scope build and handover, and an internal team can take over the operations afterward.
How do we keep Drupal role mapping accurate over time?
Role mapping stays accurate when the rules are documented, version-controlled and reviewed whenever groups or roles change in the identity provider. Map from stable group identifiers instead of display names, and keep a test account for each mapped role. Schedule a periodic review of who holds each Drupal role, and remove mappings that no longer correspond to a current group. Decide whether roles are removed when a user leaves a group at next sign-in, since that behavior depends on the module settings and your policy.
What happens to existing local Drupal accounts after SSO is enabled?
Existing local accounts keep working unless you disable them, and the answer for each one depends on how it matches an identity provider user. Accounts that match by a stable identifier can be linked to the federated login, while unmatched accounts remain local. Local administrator accounts are usually kept as an emergency path, protected with strong authentication and tested before any cutover. Confirm how your chosen module links existing accounts, and plan the list of accounts to keep, disable or convert before go-live.
Does Drupal licensing change the cost of SSO?
Drupal and its contributed files are licensed under GPL-2.0-or-later, and there is no paid edition of Drupal itself, so there is no license fee to add for SSO. The cost is the build and operations effort, including module configuration, identity provider work, testing, certificate management and keeping contributed modules compatible with each Drupal release. Check the license terms of any separate identity product you use, because those are independent of Drupal.
How DeployOpen scopes, builds and hands over SSO work
DeployOpen plans and builds Drupal SSO and identity integration inside your own infrastructure, against a written scope that fixes what is included before work starts. The work moves from agreed identity design to a tested build, then to documentation your team can run.
How we scope
- Inventory which identity providers, SAML or OpenID Connect endpoints and LDAP directories the Drupal sites must trust, and who owns each.
- Agree in writing which attributes map to Drupal roles, which accounts stay local, and how first sign-in creates or links users.
- Confirm the Drupal version and PHP runtime, then check the SAML Authentication and OpenID Connect module versions against that target before committing.
How we build
- Configure the SAML service provider or OpenID Connect client in a non-production Drupal environment, with signing certificates and redirect URIs kept out of code.
- Build role mapping from identity provider claims or attributes, and test each rule with users who hold the expected and unexpected group memberships.
- Test sign-in, sign-out, session expiry, account lockout and the local admin fallback path, then review the results with your identity team.
How we hand over
- Deliver configuration as exported Drupal configuration and custom code in your repository, so changes move between environments through your pipeline.
- Document the identity provider settings, claim mappings, emergency local admin procedure and certificate renewal steps in a runbook your team owns.
- Walk your administrators and engineers through the runbook and the test cases, so the handover is verified rather than assumed.
How we support
- Offer ongoing support, module upgrades and security monitoring for the SSO modules as a retainer, if your team wants continued help after handover.
- Plan contributed module updates and Drupal core release windows around identity changes, so SSO is retested after each relevant update.
- Ask any support provider to confirm response terms, scope and certificate rotation responsibilities in writing before you sign.
