Drupal SSO with Microsoft Entra ID: which method to build on current Drupal
If your organization runs Drupal 10 or Drupal 11 and wants staff to sign in with their Microsoft Entra ID accounts, you have two supported methods to choose from: the contributed SAML Authentication module (*samlauth*), at version 8.x-3.14, which supports Drupal 10.3 or later and Drupal 11, or the contributed OpenID Connect module with its generic client. The Azure AD-specific client, the OpenID Connect Microsoft Azure Active Directory client, supports only Drupal 8 or 9, so it is not an option on current Drupal and should not appear in your plan. Confirm the module versions and compatibility on their Drupal.org project pages before you commit, because release support changes over time.
Both methods handle the same core job: they redirect the user to Entra ID, validate the response, and start a Drupal session. Each can create a Drupal account on first sign-in, so staff do not need a separate local password. Neither method is a full provisioning system. Deprovisioning when someone leaves, changes to existing accounts, and mapping Entra ID groups to Drupal roles are configuration and design work you must specify. Group-based role assignment in particular depends on which claims Entra ID sends, and on whether your tenant issues group identifiers or group names, so confirm that with your identity team before the build starts. The SAML Authentication module page is the natural next read for SAML-specific settings.
The choice usually comes down to your identity setup and how much of the flow your team already runs. SAML suits organizations that already manage enterprise applications in Entra ID with SAML metadata and attribute release. The OpenID Connect route fits teams that want OIDC-style client registration and claims handling. Either way, decide early which Entra ID attributes will populate the Drupal username, email and roles, and which fallback login stays available for administrators if the identity provider is unreachable. Those decisions shape the verification plan and the support runbook that follow.
What you need in place before configuring Entra ID login
Entra ID sign-in touches three teams: the Drupal platform owners, the identity team that controls the tenant, and whoever owns the public hostname. Settle the Drupal version, the hosting stack and the protocol choice first, because each later step depends on them.
Drupal version and PHP runtime
Drupal 10 requires PHP 8.1 or later and Drupal 11 requires PHP 8.3 or later. The SAML Authentication module's 8.x-3.14 release supports Drupal 10.3 and later and Drupal 11, so a site still on an older 10.x release may need a core update before the module can be installed. Confirm the current core and PHP versions in your environment before choosing a module.
Supported web server and database
Drupal runs on Apache, Nginx and other web servers, with MariaDB, MySQL, PostgreSQL or SQLite as the database. Check that the chosen combination is the one your platform team supports, since login redirects and session handling are configured on the web tier as well as in Drupal. Record the versions in the change request so the SSO configuration can be reproduced after a rebuild.
Entra ID tenant and app registration rights
Someone with sufficient rights in the Microsoft Entra admin center must register the application, set redirect URIs and create or assign client secrets or certificates. Confirm tenant ownership first: a partner-managed, subsidiary or guest tenant can change who may register applications. Also confirm who approves the app registration, because that approval often gates the work more than the configuration does.
HTTPS hostname and certificate
Entra ID returns users to a fixed redirect URI, so the production hostname must be decided before registration and must resolve to the Drupal site over HTTPS with a valid certificate. Changing the hostname later means updating the registration, the Drupal SSO settings and any saved metadata. Plan separate registrations for staging and production rather than reusing one redirect URI across environments.
Metadata or certificate exchange
SAML needs the Entra ID federation metadata or certificate, the Drupal service provider metadata and agreed attribute names. The OpenID Connect path needs the tenant's issuer URL, the client ID and a client secret stored outside the codebase. Decide which protocol you will use before exchanging anything, because the two paths require different registration settings and different secrets handling.
Questions for the identity team
Confirm three things before build: whether the tenant is owned by your organization, whether group claims are available in the tokens you will receive (group size limits and overage handling can change how roles are mapped), and who approves the app registration and its owner. Write the answers into the project record, since they determine whether group-to-role mapping is feasible as designed.
SAML or OpenID Connect: how to choose between the two methods
SAML through the SAML Authentication module (samlauth) fits organizations that already run SAML federation across several applications and have an established process for exchanging metadata, certificates and attribute definitions with their identity provider. In that setting, Drupal becomes one more service provider in a federation the security team already governs, so the work is mostly about matching the existing agreements rather than designing new ones.
- Federation alignment: The site needs the Entra ID enterprise application metadata and the signing certificate arranged in advance, and the Drupal side must expose its service provider metadata for upload.
- Attribute release: Attributes such as the user identifier, email and group membership are defined in the SAML assertion, so the Entra ID claims configuration determines what Drupal can read.
- Certificate lifecycle: Signing and encryption certificates expire, and rotation must be scheduled on both sides, which becomes a recurring operational task.
- Version fit: The 8.x-3.14 release supports Drupal 10.3 and later and Drupal 11, so confirm the Drupal version before committing to this path.
Before choosing SAML, confirm with the identity team that the federation metadata process and certificate ownership are already defined for this application.
The generic OpenID Connect client in the OpenID Connect module suits teams that want Drupal to receive OIDC tokens and claims directly from Entra ID, particularly when the same app registration is used by other OAuth 2.0 or OIDC clients. The module creates accounts on first sign-in and maps the returned claims to Drupal user fields, which makes the claim design the central part of the project.
- App registration: The Entra ID side requires an app registration with a client secret or certificate, redirect URIs for the Drupal site and the scopes the module requests.
- Claim handling: Group membership is returned as a claim only when the token configuration includes it, and large group sets may need a different approach, so confirm the behavior in your tenant.
- Client maintenance: The client secret has an expiry date that must be tracked, which is a recurring task similar to certificate rotation.
- Flexibility: Teams that also plan to use Keycloak, Okta or another provider can reuse the same OIDC pattern, with the built-in clients listed for the module as a starting point.
Check the module's current documentation and the Entra ID token configuration together, since claim names and group behavior are where most sign-in problems appear.
Configuration effort differs less in the Drupal module than in the coordination required with the Entra ID administrators. Each protocol asks for different objects to be created, and the number of people who must approve those objects shapes the schedule more than the module settings do. The table of responsibilities below is a useful starting point for scoping.
- SAML: Expect work on the enterprise application, the SAML single sign-on configuration, the attribute and claim mappings and the exchange of metadata files.
- OIDC: Expect work on the app registration, redirect URIs, client credentials, API permissions and optional token configuration for groups.
- Drupal side: Both paths need the module installed, the identity provider configured, field mapping for name and email, and a tested first-sign-in account creation flow.
- Testing: Plan test accounts in several groups, a failed-login path and a sign-out check for each protocol.
Ask your Entra ID administrators which of these objects they already manage and who approves changes to them before choosing the protocol.
Mapping groups to Drupal roles is where the two protocols differ most in practice. Both can carry group information, but the form it takes, how it is delivered and how it changes over time determine how stable the role mapping will be. The design should define the group source, the claim format and the fallback when group data is missing before any role is assigned.
- Claim format: SAML attributes and OIDC claims can carry group object identifiers or display names, and the identifier form is generally more stable when groups are renamed.
- Role assignment timing: Decide whether roles are set only on first sign-in or refreshed on each login, because a removed group membership should remove the Drupal role.
- Administrative roles: Keep administrator roles mapped to a small, named group with its own approval process.
- Missing claims: Define what happens when the group claim is absent, which should default to the lowest-privilege role rather than granting access.
Review the group claim output for a test user in your tenant before finalizing the mapping, since the returned values determine every later role decision.
Neither protocol is the right answer on its own, and the choice should follow from the organization's existing federation, the Entra ID administration model and the Drupal version in use. The checks below help confirm the decision with the people who will own each side of the integration, and they should be settled before the build starts.
- Drupal version: Confirm the site runs a version that the samlauth release supports, and confirm the OpenID Connect module version that will be installed.
- Federation standard: Ask whether the organization already standardizes on SAML for other applications, and who owns the metadata and certificates.
- Entra ID ownership: Identify who can create enterprise applications or app registrations and who approves token configuration changes.
- Group model: Agree which groups map to which Drupal roles, and whether group identifiers or names will be used.
- Secrets and certificates: Record the expiry dates and rotation owners for every certificate or client secret.
Bring these answers to the design review, since they determine which protocol section of the build plan applies.
How to configure Entra ID sign-in on Drupal, step by step
This sequence takes a Drupal site from a module choice to Entra ID sign-in for all intended users, with a test account proving each stage before wider rollout.
Choose the module and confirm compatibility
The team confirms the Drupal version in use, then selects the SAML Authentication module (samlauth) or the generic OpenID Connect client, based on the protocol the security team wants to govern. Confirm that the chosen release supports your Drupal version: samlauth 8.x-3.14 supports Drupal 10.3 and later and Drupal 11, and the Azure AD-specific client is not an option on current Drupal. Done means a written decision record names the module, release and Drupal version, and a non-production copy of the site is ready for testing.
Install and enable the module in staging
A Drupal developer adds the chosen module with Composer, enables it in a staging environment, and checks that the module's configuration pages load without errors. The site's dependency file and lock file should record the exact release so the same version deploys to every environment. Done means the module appears as enabled in the site's extension list, the staging site loads normally, and the change is committed to version control for review.
Register Drupal as an application in Entra ID
An Entra ID administrator creates an enterprise application or app registration for the Drupal site in the tenant that holds the workforce accounts. For SAML, the administrator sets the identifier (entity ID) and the assertion consumer service URL that the module reports; for OpenID Connect, they set the redirect URI and create a client secret or certificate. Confirm with your Entra ID administrators which tenant, sign-in audience and assignment settings apply to your organization. Done means the application exists in the tenant and its identifiers match what the Drupal side will expect.
Set redirect and assertion consumer URLs exactly
The team copies the callback or assertion consumer URL from the Drupal module settings page into Entra ID, character for character, including scheme, host and path. A mismatch is the most common cause of failed sign-ins at this stage, so the check is a side-by-side comparison of both values in the staging environment. Done means the URL in Entra ID matches the URL the module generates, and the team has recorded the entity ID or client ID it will use in the next step.
Configure Drupal with tenant endpoints and certificates
A Drupal administrator enters the tenant's metadata or endpoints into the module: the identity provider metadata document for SAML, or the authorization, token and key endpoints with client ID and secret or certificate for OpenID Connect. Signing certificates and secrets should be stored in your secrets management service, not in exported configuration files. Done means the module saves without validation errors and the settings page shows the expected issuer and endpoints.
Test sign-in with one controlled account
A tester signs in with a single pilot account that is assigned to the Entra ID application, and the team checks that the user is created or matched in Drupal with the expected username and email. For SAML, a security engineer inspects the SAML response in a controlled browser session to confirm the issuer, audience, signature and attribute values; for OpenID Connect, they decode the ID token and check its issuer, audience and expiry. Done means the pilot account lands on the intended Drupal page with the correct identity, and the token or response contents match the attributes you expected.
Map groups to roles and test privilege boundaries
The team maps the Entra ID group claims or attributes to Drupal roles and confirms that a user in a lower-privilege group cannot gain administrative permissions. Test at least one account from each group that matters, and include a user outside all assigned groups to confirm access is denied. Done means each test account receives exactly the roles its group grants, and the mapping is documented for the access review. Confirm the claim names and group handling your tenant supports before you rely on them.
Enable for all users with a rollback plan
After the pilot results are signed off, the team assigns the intended user groups to the Entra ID application, enables sign-in for those users on production, and keeps a documented route back to local login for administrators. Monitor sign-in logs and Drupal logs for the first sessions, and record who approved the rollout. Done means production users can sign in through Entra ID, local administrator access is confirmed to still work, and the configuration and test evidence are stored with the change record.
Mapping Entra ID attributes and groups to Drupal accounts and roles
This table compares each Entra ID attribute or claim with the Drupal field or role it feeds, and notes where mapping usually breaks. Read it as a checklist for the design review: confirm each row against your tenant and your chosen module before the build. The main takeaway is that the account match key and group translation decide whether sign-in and role changes behave predictably.
| Entra ID source | Drupal target | Design decision | What to test |
|---|---|---|---|
| User principal name (UPN) | Drupal username | Often a sign-in name, not a stable identifier. Use it for display or username only if your naming policy guarantees uniqueness. | Rename a user in Entra ID and confirm the existing Drupal account still matches. |
| Email claim | Drupal email field | Confirm the claim is populated for all users. Decide whether email is used as a match key or only for profile sync. | Users with no mail attribute, guest accounts and shared mailboxes. |
| Object ID (oid or subject) | Account match key (authmap) | Use the stable object ID as the match key where the module allows it, since it does not change when a user is renamed. | Sign in as an existing user after a UPN change and confirm no duplicate account is created. |
| Profile attributes (given name, surname, department) | User fields | Decide which fields sync on every sign-in and which are set once. Sync only attributes your Drupal policy needs. | Confirm an attribute change in Entra ID appears after the next sign-in. |
| Group claims (object IDs) | Drupal roles via mapping | Groups usually arrive as object IDs, not names. Build a translation table from group object ID to Drupal role and keep it under change control. | Each mapped group grants exactly the intended role, and unmapped groups grant nothing. |
| Group overage | Role assignment completeness | When a user belongs to many groups, Entra ID may omit the group claim and send a link for the application to query. Confirm your module and app registration handle this case. | Test with a user in a large number of groups and confirm roles still resolve. |
| Group removal | Role removal on next sign-in | Roles are typically recalculated at sign-in, so a removed group may take effect only at the user's next login. Decide whether that delay is acceptable. | Remove a user from a mapped group, sign in again, and confirm the role is dropped. Confirm whether existing sessions are ended. |
Hardening the Entra ID login for Drupal
Signing users in through Entra ID moves the main login decision outside Drupal, but the Drupal side still decides which assertions are trusted, which roles a user receives and how long a session lasts. The cards below cover the settings to review with your security and identity teams before go-live, and each one should be checked against your own policy.
Signed assertions and token validation
Confirm that the SAML module requires signed responses and assertions, and that the OpenID Connect client validates the issuer, audience, signature and expiry of every ID token. Reject any sign-in that arrives unsigned or from an unexpected tenant. Test with a deliberately altered token in a staging site so you know the rejection path works before production.
Certificate and client secret rotation
The SAML signing certificate and the OIDC client secret both expire, and an expired credential stops all sign-ins at once. Record the expiry dates in your change calendar, load the new certificate into Drupal before the old one is retired, and confirm that both certificates are accepted during the overlap. Ask who on your team owns this rotation when the person who set it up leaves.
HTTPS and redirect URL restrictions
Register only the exact HTTPS callback and logout URLs for your Drupal hostnames in the Entra ID app registration. Avoid wildcard redirect URIs and http callbacks in any environment that handles real accounts. Review the list whenever a hostname, staging site or preview environment is added, since stale entries are a common route for sign-in redirection abuse.
Disabling local password login for staff
Where policy requires federated sign-in for staff, decide which Drupal accounts keep a local password and which are blocked from using one. Keep at least one documented break-glass administrator path, stored under your secrets process, so a directory outage does not lock out the whole site. Confirm the final list of exempt accounts with the policy owner and review it on a fixed schedule.
Least-privilege role mapping
Map Entra ID groups to Drupal roles only for the permissions each group needs, and do not let a broad directory group receive the administrator role by default. Decide whether roles are set on every sign-in or only on first account creation, and test what happens when a user leaves a group. Review the mapping rules after each change to group membership design.
Session lifetime and failed sign-in logging
Set Drupal session and idle timeouts to match your access policy, and check whether Entra ID conditional access controls also apply to the session. Log failed sign-ins, assertion rejections and role changes to a central log store that your security team can query, and confirm retention periods with your own policy. Test that alerts fire for repeated failures.
Security advisories and module updates
The Drupal Security Team publishes advisories for core and contributed projects, and authentication modules are part of that flow. Subscribe to advisories for the SAML and OpenID Connect modules, and include them in your patch process so a fix in an authentication module is applied within the window your policy sets. Confirm that your Drupal version is still receiving security releases before relying on it for staff sign-in.
Common Entra ID login failures on Drupal and how to fix them
This table lists the sign-in failures teams most often hit when connecting Drupal to Microsoft Entra ID, with the likely cause and the fix for each. Read it as a first-response checklist: match the symptom you see in the login flow, then confirm the cause in the identity provider and Drupal logs before changing configuration.
| Failure | Likely cause | Fix |
|---|---|---|
| Redirect URI mismatch error at Entra ID | The reply URL registered in the app registration does not exactly match the callback path that the Drupal module sends, including scheme, host, port or trailing slash. | Copy the callback URL shown on the module settings page into the app registration's redirect URIs, then test again in a private browser session. |
| Tokens rejected as not yet valid or expired | Clock skew between the Drupal web servers and the identity provider, so the timestamps in the ID token fall outside the allowed window. | Enable time synchronization (NTP) on every web and PHP host, confirm the clock on each node, and check that containers inherit the host time. |
| Login succeeds but no groups arrive | The group claim is not configured in the Entra ID token configuration, or groups are assigned by a method the claim does not include. | Add the group claim to the token configuration, decide between object IDs and display names, and confirm the claim appears in a test sign-in before mapping roles. |
| Group overage on users with many memberships | Entra ID omits the groups claim when a user belongs to too many groups and returns a reference that Drupal cannot read directly. | Limit the claim to groups assigned to the application or use app roles, then confirm the mapping works for a user with a large membership set. |
| Duplicate Drupal accounts for the same person | The module matches accounts on a field that differs between sign-ins, such as email address versus the immutable object ID, or accounts were created before SSO was enabled. | Choose a stable matching attribute, such as the object identifier, before go-live, and merge or disable the duplicates with an audited script. |
| Certificate or client secret expired | The signing certificate or client secret in the SAML or OIDC configuration reached its expiry date, and no renewal reminder was set. | Record expiry dates in the operations calendar, rotate the secret or certificate ahead of time, and store the new value in your secrets manager. |
| Attempt to install the Azure AD-specific client on Drupal 10 or 11 | The OpenID Connect Microsoft Azure Active Directory client supports only Drupal 8 or 9, so it cannot be installed on current Drupal. | Remove that client and configure the SAML Authentication module or the generic OpenID Connect client, which support current Drupal releases. |
Questions buyers ask before building Entra ID SSO for Drupal
Can we use the Azure AD client module for Entra ID sign-in on Drupal?
No, not on current Drupal. The OpenID Connect Microsoft Azure Active Directory client module's latest stable release supports only Drupal 8 or 9, so it cannot be installed on a Drupal 10 or 11 site. Current builds use either the contributed SAML Authentication module (samlauth) or the generic OpenID Connect client from the OpenID Connect module. Your choice between them depends on how your Entra ID tenant is configured and which protocol your security team prefers. Confirm the module versions against your Drupal core version before the design is signed off, because the release notes for both projects change over time.
How much effort does Entra ID SSO for Drupal take, and what drives it?
Effort is driven mainly by the number of roles to map, the number of Drupal sites that share the sign-in, and how much account data must sync on each login. A single site with a few groups mapped to standard roles is a small piece of work. Multisite estates, custom user fields, multilingual login pages and strict claim requirements add design and testing time. Ask any provider for a fixed-scope quote that lists the sites, the groups to map, the attributes to sync and the environments to build, because those items set the price and duration more than the module choice does.
What must our organization provide before the work starts?
You need three things before the build can begin: access to the Entra ID tenant, rights to register an enterprise application or app registration, and a documented group design. Tenant access should cover read access to users and groups plus the ability to assign users and groups to the application. App registration rights let the team set redirect URIs, configure the signing certificate or client secret, and define the claims or optional claims Drupal needs. The group design must state which Entra ID groups map to which Drupal roles, who owns each group, and how removals are handled. Ask your identity team to confirm these rights early, since approval cycles often set the start date.
Can our internal team build Entra ID SSO for Drupal alone?
Often yes, if the team already runs Drupal in production and has someone who can administer the Entra ID tenant. The work involves Drupal configuration, module installation through Composer, claim handling, role mapping and test cases across login, logout and failed sign-in. The harder parts are usually the identity decisions: which groups are authoritative, how account linking works for existing local users, and what happens to sessions after a user is removed in Entra ID. Teams without Drupal development experience or without an identity administrator often find it cheaper to bring in a partner for design and testing. Compare the internal estimate with a written scope before deciding.
How long does testing take when the site has many roles?
Testing time grows with the number of role combinations, not just the number of users. Each mapped group needs at least one test account that signs in, receives the right Drupal role, and is denied access to content outside that role. Users who belong to several groups, users who leave a group, and users with no mapped group also need cases. Test environments should mirror the production tenant settings, including the claim names and the certificate or secret lifecycle. No duration is fixed here, so ask a provider to list the role matrix, the environments, the test accounts they will use and the acceptance criteria in the written scope.
What does ongoing maintenance include, such as certificate renewal?
Maintenance covers the identity connection, the Drupal modules and the Drupal core version. For SAML, the signing certificate and metadata must be renewed before expiry and the new metadata must be applied on both sides. For OpenID Connect, client secrets or certificates have expiry dates that must be tracked in Entra ID and in Drupal settings. Module updates follow the samlauth or OpenID Connect release cycle, and Drupal security releases arrive on a fixed schedule, so someone must watch advisories and apply patches. Ask for a maintenance calendar that names the owner of each renewal, the test steps after each change, and whether support is a retainer or an as-needed arrangement.
Which Drupal and PHP versions must the site run to use these modules?
Drupal 11 is the current major version, and the samlauth 8.x-3.14 release supports Drupal 10.3 and later and Drupal 11. Drupal 10 reaches end of life on December 9, 2026, so a new build should target Drupal 11 unless there is a documented reason not to. Drupal 11 requires PHP 8.3 or later, and Drupal 12 requires PHP 8.5 or later, according to the Drupal.org PHP requirements page. If your site is still on Drupal 7, it cannot be updated in place and must be migrated into a new site first, so the SSO work sits inside a wider migration plan. Confirm the exact module and core versions in your environment before the build.
How to test Entra ID sign-in before rollout
Test the identity flow in stages before any user signs in through Entra ID on the production site. Start in a test tenant or with a small pilot group of named users whose app role assignments and group memberships you control. For the SAML Authentication module, confirm that the assertion attributes arrive with the expected names and that the group claim carries the group identifiers your role mapping expects. For the generic OpenID Connect client, confirm the same thing for the ID token and the userinfo response. Record which claim names Entra ID actually sends for your app registration, because group claims can come back as object identifiers rather than display names, and that difference breaks role mapping silently.
Negative tests matter as much as the happy path. Sign in with a user who is not assigned to the enterprise application and confirm that Drupal refuses access and does not create an account. Remove a pilot user from the mapped group, sign in again, and confirm that the Drupal role is dropped on the next sign-in rather than kept from an earlier session. Check what happens to an existing local account that shares an email address with an Entra ID user, since account linking rules decide whether a second identity can take over an administrator account. Confirm these behaviors in your own environment, because account creation and role sync settings differ by module version.
Keep a local administrator login working throughout the rollout and test it before you switch the login form over. Document the rollback path as a short runbook: how to disable the external provider in configuration, which account signs in directly, and where that password or recovery credential is stored. After launch, monitor failed sign-ins, unexpected account creation, and role changes in the Drupal logs and in the Entra ID sign-in logs. Treat every update to the SAML or OpenID Connect module as an identity change. Before a security release from the Drupal Security Team reaches production, repeat the pilot tests on staging, since the Security Team publishes advisories on the third Wednesday window and those patches can touch login code.
How DeployOpen scopes and delivers Entra ID SSO for Drupal
DeployOpen scopes Entra ID sign-in for Drupal as a fixed-scope engagement, with the written scope fixing the authentication method, the tenant and group inputs, the role mapping rules, the test plan and the handover before any build work starts. The first decision in that scope is the method: the SAML Authentication module for a SAML service provider setup, or the generic OpenID Connect client for an OIDC application registration. The scope document should record which method was chosen and why, because the Entra ID side (enterprise application or app registration, claims, certificates or client secrets) differs for each. The scope should also name who in your organization owns the Entra ID tenant, who approves group and claim changes, and which Drupal environments (development, staging, production) receive the configuration.
The input list drives most of the work, so ask for it early. For group-to-role mapping, DeployOpen needs the Entra ID group object identifiers or names that correspond to each Drupal role, whether group membership is emitted as a claim or must be read from the Graph API, and how nested groups and users with no group membership should be handled. The test plan should cover first sign-in account creation, sign-in for each role, removal of a user from a group, disabled accounts in Entra ID, and logout behavior. Handover covers the configuration export, runbook, and the settings a Drupal administrator must keep in sync with Entra ID. Ongoing support, upgrades of the authentication module when Drupal core moves to a new major version, and periodic re-testing of role mapping are available as a retainer. DeployOpen implements inside your own cloud accounts, data centers or air-gapped networks. It prepares configuration and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications; independent auditors and certification bodies do that work.
