Drupal LDAP and Active Directory integration

How Drupal LDAP and Active Directory integration works

Many organizations already keep their staff identities in Active Directory or OpenLDAP and want the same credentials to work on an intranet Drupal site. The supported route on Drupal is the contributed Lightweight Directory Access Protocol module (the ldap project on Drupal.org). It handles login with LDAP credentials and provisions accounts in both directions: from LDAP into Drupal, and from Drupal out to LDAP. Its 8.x-4.13 release supports Drupal ^9.3, ^10 and ^11, so the release you install must match the Drupal core version you run. Confirm that compatibility against the project page before you choose a core version, because the module is one of the dependencies that decides whether an upgrade is cheap.

The integration lives inside the Drupal site. It does not replace the directory, change how passwords are stored, or become the system of record for who works at the organization. Active Directory or OpenLDAP remains authoritative for identities and group membership, and Drupal holds a local user entity for each person who has signed in, along with whatever roles and content ownership the site assigns. That split matters for decisions about account lifecycle. A user removed from the directory should lose access to Drupal, but the module only enforces this if the synchronization and the login rules are set up for it. Plan how disabled accounts, renamed users and users who never sign in again will be handled before you configure anything.

Before the build starts, the team should decide which LDAP attributes map to Drupal fields, which groups grant which roles, and which service account the site uses to bind to the directory. Ask your directory team for a read-only bind account with rights limited to the search base the site needs, and confirm whether the directory allows the connection over LDAPS or StartTLS. Those answers shape the configuration far more than the Drupal side does, and they are the first items to verify in a test environment.

What the Drupal LDAP integration needs before configuration

Most LDAP login problems start before the first configuration screen is opened. The Drupal version, the PHP runtime, the bind account, the network path and the trust chain for encrypted connections all have to be settled first. The cards below cover each of these, plus the attribute design and the named approvers who sign off on access.

Drupal and PHP version

Confirm the Drupal core line first, because the LDAP module's current 8.x-4.13 release supports Drupal ^9.3, ^10 and ^11. Drupal 10 requires PHP 8.1 or later and Drupal 11 requires PHP 8.3 or later, so an older PHP runtime blocks the upgrade before LDAP is even installed. Check whether your site is still on Drupal 7, which has no supported path to this module and must be migrated first. Drupal 7 sites are a migration project, not an LDAP configuration task.

Directory bind account

The LDAP module needs a service account to search the directory before it can authenticate a user. Ask for a read-only account scoped to the search base that holds users and groups, with no rights to change passwords or directory objects. Record its distinguished name, the password rotation policy and the expiry setting, because a silent expiry locks out every intranet user at once. Store the password in your secrets manager rather than in exported configuration.

Network path to directory servers

Drupal must reach every domain controller or OpenLDAP server it will query, on the ports your directory uses for LDAP and LDAPS. Test the path from each web node and each container, not only from a workstation, because firewalls often allow the admin subnet alone. Confirm DNS resolution for the domain name, since Active Directory logins depend on locating a domain controller, and agree on which servers Drupal may use if one fails.

Certificate trust for encrypted binds

Encrypted binds fail when the web server or PHP runtime does not trust the certificate chain issued by your internal certificate authority. Obtain the root and any intermediate certificates, install them in the trust store used by PHP on every node, and test with the directory's own tooling before enabling TLS in Drupal. Ask the directory team whether certificates rotate, since a renewed certificate with a new chain breaks logins without any change on the Drupal side.

Schema and attribute decisions

Decide which directory attribute becomes the Drupal username, which becomes the email address and which stays read-only, before mapping anything. Active Directory uses attributes such as sAMAccountName and userPrincipalName, while OpenLDAP often uses uid, so the choice changes login behavior and account matching. Confirm how disabled accounts are flagged, because Drupal should block sign-in for leavers even when a cached account still exists.

Named approvers for access

Name one owner who approves the bind account and one who approves the group structure that will drive role mapping. The bind account owner answers for read scope and rotation, and the group owner answers for which directory groups grant Drupal roles such as editor or administrator. Without named owners, group changes made in the directory can quietly grant publishing rights, so agree on who reviews changes before configuration begins.

LDAP module, SAML or OIDC: which integration fits

The Lightweight Directory Access Protocol module lets Drupal check a user's name and password directly against the directory, so Drupal itself talks to Active Directory or OpenLDAP over the network. It also provisions accounts in both directions, creating Drupal users from directory entries and, where you configure it, writing data back to the directory. This is the most direct path when the directory is the only identity source and the site sits on the internal network.

Direct credential check: Drupal receives the password and binds to the directory, so no separate login server is needed.
Directory requirements: Confirm that the service account, search base, user and group attributes, and any group membership queries you need are readable over a secured connection such as LDAPS or StartTLS.
Provisioning control: You define which entries become accounts and which attributes map to Drupal fields and roles.
Wrong choice when: the site is reached from outside the network, when the directory must not be reachable from the web tier, or when you need MFA or conditional access enforced by a cloud identity provider.
Operational load: every site holds directory credentials and query logic, so each change to the schema or group model must be tested in every site that uses it.

Before choosing this tab, confirm with your directory team which LDAP endpoints and service accounts they will allow from the Drupal network segment.

Configuring the LDAP module in order

This sequence takes a Drupal site from a fresh module install to a tested LDAP login, with users provisioned and groups mapped to roles, so each layer is proven before the next one depends on it. The team finishes with a pilot group that signs in against the production directory.

Confirm the Drupal version and install the module
The platform engineer checks the running Drupal core version against the Lightweight Directory Access Protocol module's requirements, which the 8.x-4.13 release lists as Drupal ^9.3, ^10 and ^11, and confirms the PHP version against the Drupal core requirement for that release. Install the module through Composer so the version is pinned in the codebase, then enable it in a non-production environment. Done means the module appears in the extend list without dependency errors and drush pm:list shows it as enabled. Inspect the Drupal status report and the Composer lock file for the pinned version.
Create a read-only bind account in the directory
The directory administrator creates a dedicated service account with read access only to the user and group branches that Drupal needs, and no write or password reset rights. Store its distinguished name and password in the secrets store your team uses, not in exported configuration. Done means a bind with that account succeeds from the Drupal host using an LDAP client tool, and a write attempt is refused. Inspect the directory's audit or access log for the bind entry and confirm the account is excluded from interactive login policies that do not suit a service account.
Set server, transport and encryption settings
The engineer enters the directory hostnames, port, and bind settings in the LDAP server configuration form, then chooses the transport. Use TLS with the directory's certificate chain installed on the Drupal web nodes, and confirm the certificate name matches the hostname entered. Ask the directory team which domain controllers or replicas Drupal should use and whether failover order matters. Done means the server status check reports a successful bind over the chosen encryption. Inspect the Drupal watchdog log (recent log messages) and the web server TLS handshake output if the bind fails.
Test the bind and a sample user search
Run a test search for one known test user from the server test screen, using a filter on the account attribute your organization uses for sign-in. Compare the returned attributes with what the directory administrator reports for that account. Done means the search returns exactly one entry with the expected distinguished name, mail and display name. If it returns nothing, check the base DN and the filter before changing anything else. Inspect the search results on the test screen and the watchdog entries for the query.
Set the user search base and login attribute
Enter the user search base so Drupal only searches the organizational units that hold intranet users, and set the login attribute that matches what staff type at sign-in, such as the account name or email address. Confirm that disabled accounts are excluded by the filter, since the module's authentication rules depend on the directory's account flags. Done means a test user from an in-scope unit signs in with directory credentials, and a user from an out-of-scope unit is refused. Inspect the login attempt results in the watchdog log and the Drupal user list for any unexpected account created.
Enable provisioning between LDAP and Drupal
Decide which direction provisioning runs. Enable creation of Drupal accounts at first LDAP login if the business process allows it, and map only the attributes that Drupal needs, such as name and mail. Keep Drupal-to-LDAP write provisioning off unless the directory owner has approved it in writing. Done means the test user's account appears in Drupal with the mapped fields populated and no unmapped data copied. Inspect the user edit screen for the test account and the watchdog entries recording account creation or field updates.
Map directory groups to Drupal roles
Map each directory group that represents an intranet role to a Drupal role, starting with the smallest set that the pilot needs. Confirm how nested group membership is handled, since the directory and the module may differ on whether indirect membership counts. Done means a test user in the mapped group receives the expected role after sign-in, and a user outside the group does not. Inspect the roles tab on the test account, and recheck after a second sign-in to confirm that removing group membership removes the role on the next login.
Pilot with one group before wider rollout
Enable LDAP login for one pilot group of real users in a staging copy of the production site, with the team watching login failures and unexpected accounts. Record each issue, including password expiry prompts, locked accounts and roles that do not match expectations, and fix them before opening access to other groups. Done means the pilot group signs in for a full working cycle without help desk tickets caused by the integration. Inspect the watchdog log, the directory's failed bind records and the accounts list after the pilot period.

Attributes and group to role mapping between directory and Drupal

This table maps directory attributes such as login name, mail, display name and group membership to Drupal user fields and roles, showing the direction of provisioning and who owns each value. Read it before configuring the LDAP module so every field has one owner and a defined behavior when a user leaves a directory group. The main takeaway is that role removal only behaves predictably if you decide, per role, whether the directory or Drupal is the source of truth.

Directory attribute or event	Drupal target	Provisioning direction	Who owns the value
sAMAccountName or uid (login name)	Drupal username and LDAP authentication name	Directory to Drupal, at first login	Directory team, changed only in the directory
mail	User email field	Directory to Drupal, on each sync	Directory team, Drupal edits should be disabled
displayName or cn	Display name or full name field	Directory to Drupal, on each sync	Directory team, Drupal edits should be disabled
memberOf group membership	Drupal role assigned by mapping rule	Directory to Drupal, on login and scheduled sync	Directory team defines group, Drupal site owner defines role
Group removed from memberOf	Mapped role removed on next sync	Directory to Drupal, role removal follows the directory	Directory team, confirm the removal setting before go-live
Account disabled or deleted in directory	Drupal account blocked or kept per policy	Directory to Drupal, on sync or failed login	Directory team, Drupal policy sets whether content is reassigned
Drupal-only role such as content editor added by an admin	Drupal role not present in directory	Drupal only, not written to directory	Drupal site owner, must be excluded from directory-driven removal
Profile fields maintained by users, such as bio or preferences	Drupal user fields	Drupal only, not synced from directory	Site users and Drupal site owner

How provisioning between LDAP and Drupal affects account lifecycle

The first decision is whether Drupal accounts should exist before a person ever signs in, or only once they authenticate. The LDAP module supports provisioning from LDAP to Drupal, so you can create accounts at first login (just-in-time) or run a scheduled bulk import of directory users. Just-in-time creation keeps the Drupal user table limited to people who have actually used the site, but it means roles, group memberships and content assignments cannot be prepared in advance. Bulk provisioning lets editors be assigned before the first login, at the cost of a larger user table and a sync job you must monitor. Confirm in your module version which provisioning modes are available, how the sync is scheduled and whether group membership changes are applied on each login or only on sync. Whichever you choose, test a user who is removed from the directory and confirm what Drupal does with that account.

Disabling a user in Active Directory or OpenLDAP does not automatically remove their Drupal account, so the deactivation path needs an explicit design. Decide whether a departed user is blocked at the next login attempt, blocked by a scheduled sync that compares directory state with Drupal, or deleted after a retention period. Each choice affects content ownership. Drupal content is attributed to the author account, and deleting that account requires a reassignment, so plan a default owner (for example, a content team account) and confirm what the module and core user deletion options do with nodes, revisions and files. Blocking is usually the safer first step because it preserves attribution and audit history. Record the retention rule in your access policy before go-live.

For each attribute, name one system of record. Typically the directory owns identity fields such as username, email, name and group membership, while Drupal owns site-specific data such as editorial preferences, notification settings and profile content. Write this down as a table during design, because the LDAP module can be configured to overwrite Drupal fields on every login, which silently discards local edits if the directory is not the owner. Also decide whether any Drupal changes are pushed back to the directory. Provisioning from Drupal to LDAP is supported by the module, but writing to a production directory from a web application is a change your directory team must approve, and it should be tested against a non-production tree first.

Securing the bind account, transport and Drupal login

The LDAP module gives Drupal a standing connection to your directory, so the bind account, the transport and the admin login path each need their own controls. The cards below cover those controls and the patch routine that keeps the Drupal side current.

Read-only, least-privilege bind account

Create a dedicated service account in Active Directory or OpenLDAP that can read only the attributes Drupal needs, such as the login name, mail and group membership. Do not reuse a personal or domain administrator account. Ask the directory team to confirm that the account cannot write, reset passwords or read attributes such as password hashes. Record who owns the account, when its password rotates and which directory logs show its activity.

Encrypted connections with certificate validation

Use LDAPS or StartTLS so credentials never cross the network in clear text, and configure the Drupal LDAP server settings to validate the directory's certificate chain. Turning off certificate verification to get a connection working is a common shortcut that leaves the bind open to interception. Confirm the certificate's hostname matches the address Drupal connects to, and plan renewal before the certificate expires.

Narrow search base and filters

Set the base DN to the organizational units that hold people who should sign in, rather than the whole directory root. Add a filter so that disabled accounts, service accounts and contractors outside the intranet scope do not become Drupal users. A narrow base limits both what Drupal can see and how much the directory must search on each login. Review the base and filter together whenever the directory structure changes.

Bind password outside the database

Keep the bind password out of the Drupal database and out of exported configuration, because configuration exports are often committed to version control. Supply it from the environment, a secrets manager or an encrypted file that the web server user can read but that is not in the web root. Confirm that the Drupal deployment process never prints the password in logs or in the admin interface, and rotate it on a schedule your directory team can support.

Protecting the administrative login path

Users who sign in through LDAP still need a route to the Drupal admin interface if the directory is unavailable. Keep a local administrator account with a strong, unique password, or document a break-glass procedure, and restrict the /user/login and admin paths to trusted networks or an identity-aware proxy where the design allows. Test the fallback before go-live so that a directory outage does not lock out the team that must restore service.

Security advisories and scheduled patching

Subscribe the operations team to Drupal Security Team advisories that name the LDAP module or Drupal core, and track the CVE identifiers and risk scores each advisory publishes. Drupal ships security releases on a set weekly window, so plan a standing patch slot in that window rather than waiting for a crisis. Test LDAP login on a staging copy after each core and module update, because authentication breaks are easy to miss until users report them.

Common LDAP login and sync failures and how to fix them

This table lists the failures teams most often hit when Drupal authenticates users against Active Directory or OpenLDAP, with the likely configuration or directory cause, the first diagnostic step and the fix. Work down the rows in order of login flow: bind, certificate, user lookup, role mapping, account creation and scheduled sync.

Failure	Likely cause	Diagnostic step	Fix
Bind refused	The service account DN or password is wrong, the account is locked or expired, or the bind DN lacks read access to the user search base.	Test the bind with an LDAP client from the Drupal host using the same DN, password and server. Check the account state in the directory and its logs.	Correct the bind DN and password, grant the service account read access to the search base, and use a dedicated account with a non-expiring password policy agreed with your directory team.
Certificate validation errors on LDAPS or StartTLS	The directory certificate is issued by an internal CA that PHP does not trust, the certificate name does not match the host name configured in Drupal, or the chain is incomplete.	Connect with openssl s_client to the directory port and compare the subject and issuer with the configured server name. Confirm which CA bundle PHP uses on the web server.	Install the internal root and intermediate CA certificates in the PHP trust store, use the host name that appears in the certificate, and keep certificate verification enabled rather than turning it off.
Users exist in the directory but cannot log in	The user search filter excludes them, for example a disabled-account flag, a missing object class, or a group membership required by the filter. The login attribute does not match what the user types.	Run the configured user filter against the directory with a known test account and compare the result with what Drupal logs for that name.	Adjust the user filter and base DN to match the intended population, and confirm the login attribute (such as sAMAccountName or userPrincipalName) with the people who will sign in.
Login succeeds but the account is not allowed	Drupal's own status for the account is blocked, or an access rule on the site restricts the account before role assignment happens.	Check the Drupal user status and any role or permission rule that runs at login. Compare the account state with the directory group membership used for access.	Set the provisioning rule so new accounts are active only when the directory condition is met, and document which group grants site access.
Group to role mapping not applied	The group attribute or DN format used in the mapping differs from the directory value, group membership is nested and not expanded, or roles are assigned only at account creation and not refreshed at later logins.	Read the groups returned for a test user with the same query Drupal uses and compare the DN strings character by character. Check whether the mapping runs on every login or only once.	Match the group DN or name format exactly, enable the nested group lookup if your directory uses it and confirm, and configure role updates on each sign-in so removed memberships also take effect.
Duplicate accounts from mismatched login attributes	Existing local accounts use a different identifier, such as an email address, from the attribute the directory now supplies. Case differences or domain prefixes create a second username.	List Drupal accounts that share the same email or a similar name with the directory user, and note which attribute was used to create each one.	Choose one stable unique identifier, normalize case and domain prefixes in the mapping, and merge or disable the duplicates with a documented, reviewed script before enabling sync.
Provisioning or sync does not run	The scheduled job that imports or updates accounts is not enabled, the cron or queue runner on the host is stopped, or the job fails silently after an earlier error.	Check the last run time and any error messages in the site logs, and confirm the scheduler runs on the host or container where Drupal executes.	Enable the sync schedule, confirm cron or the queue runner is running on the correct node, and set alerts on failed runs. Schedule the run to match the change rate you agree with your directory owners.
Mapping works in testing but fails in production	Test and production directories differ in base DNs, group names or certificates, or the production web tier cannot reach a domain controller on the required port.	Compare the configuration exports for each environment and test network reachability from the production web nodes to each directory server.	Keep directory settings in environment-specific configuration, open the required ports between the web tier and directory servers, and retest bind, lookup and mapping after each change.

What teams ask before hiring help for LDAP and Active Directory

What drives the effort and cost of an LDAP integration for Drupal?

The main drivers are the directory itself, the number of login paths, and how much provisioning and role logic you need. A single Active Directory forest with clean user objects and a few group rules is far smaller work than several directories, nested group structures, or users who must be created, updated and removed in both systems. Cost components are planning and design time, configuration and custom code where mappings are unusual, testing against real directory accounts, and deployment into your environment. Some costs are one-time (design, build, cutover) and some recur (module updates, directory changes, support). Ask any provider for a written scope that lists directories in scope, provisioning directions, group-to-role rules, environments and who runs the handover.

How long does an Active Directory login integration take to deliver?

Duration depends on how many decisions are still open when the work starts. Teams that already know their group model, service account policy and test plan move faster than teams that must first agree on which AD groups map to Drupal roles. The largest variables are the number of environments (development, staging, production), the approval cycle for directory access and service accounts, and whether provisioning must run in both directions. Ask for a timeline tied to named milestones and to the dependencies you control, such as account requests and firewall changes, rather than a single unexplained figure.

What must our team provide before the work starts?

Expect to provide several items before any configuration begins:

Read access to the directory for a bind account with clearly limited rights, plus the base DNs and attributes Drupal needs.
A written group design that names which groups grant which Drupal roles and what happens when a user leaves a group.
Test accounts covering normal users, users in each role, disabled users and users with unusual attributes.
Network paths and certificates for LDAPS or StartTLS from the Drupal servers to the domain controllers.
Named owners for approvals, security review and the production change window.

Can our internal team set up LDAP login for Drupal without outside help?

Often yes, if the team has Drupal administration skills, someone who understands the directory schema, and time for testing. The LDAP module is contributed and documented on Drupal.org, and its current release supports Drupal 9.3 and later, 10 and 11. The harder parts are usually not the login screen but the decisions around provisioning, role mapping, account cancellation and password policy, plus a rollback plan. Assess whether the team can own those decisions after launch, who will review module updates, and whether anyone can test failover and bind account rotation. An outside partner is most useful for design review, complex mappings and a documented handover.

When should we choose SAML or OIDC instead of LDAP for Drupal?

Choose SAML or OIDC when your identity provider can authenticate users and you do not want Drupal to hold direct directory bind credentials. Modern identity providers such as Entra ID or Okta are common reasons. Drupal's contributed SAML Authentication module and the OpenID Connect module both support federated sign-in and can create accounts on first sign-in. LDAP stays a reasonable choice when the directory is the system of record, the site is intranet-only, or the team already runs and supports it well. Many organizations keep LDAP for backend provisioning while using federation for sign-in. Confirm which identity provider you run and whether it already exposes the claims or attributes you need.

What should we ask for in a written quote for this work?

Ask the provider to state the directories and Drupal environments in scope, the login method, the provisioning direction for create, update and disable events, the exact group-to-role rules, and the test cases that will be run. Request a list of deliverables such as configuration documentation, a runbook for bind account rotation, and a handover session. Also ask which items depend on your teams, how change requests are priced, and what is excluded, such as directory cleanup or SAML work. A quote that describes these points in writing makes it easier to compare providers and to hold the scope to account.

What operational risks should we plan for after go-live?

The most common issues after launch are expired or over-privileged bind accounts, group changes that are not reflected in Drupal roles, accounts that remain active after leaving the organization, and module updates that need retesting against your directory. Plan for LDAPS certificate renewal, monitoring of failed bind attempts, and a documented procedure for emergency local administrator access. Review role mappings whenever the directory team changes group structures. Ask your provider how they will document these checks so your operations team can run them without the original builders.

How DeployOpen scopes and delivers the LDAP integration

DeployOpen plans, builds, documents and supports self-hosted Drupal integrations inside the client's own infrastructure, including the directory connection that authenticates intranet users. Each Drupal LDAP and Active Directory engagement starts from a written scope that names the directory, the account model, the role mapping and the handover materials before any build work begins.

How we scope

Confirm which directory is authoritative: Active Directory, OpenLDAP or FreeIPA, and which forest or domain holds the users.
Document the attributes, groups and nested group rules that map to Drupal roles and who approves each mapping.
Agree in writing whether accounts are created, updated and disabled from LDAP, from Drupal, or both, and what happens to orphaned accounts.

How we build

Configure the contributed LDAP module on the Drupal version your site runs, with service account credentials stored outside the codebase.
Test login, failed login, password change, lockout and deprovisioning paths against a staging directory before any production change.
Review the role mapping with the client's identity team using test accounts that represent each group the site relies on.

How we hand over

Deliver configuration exports, a mapping table, and runbook notes for rotating the bind account and changing group rules.
Record the decision on whether to stay with LDAP or move to SAML or OIDC, with the reasons and the affected Drupal modules.
Walk the client's administrators through login troubleshooting, sync logs and the steps to confirm provisioning is working.

How we support

Ongoing support, Drupal core and module upgrades, and continuous testing are available as retainers after handover.
Track the Drupal core release schedule and the LDAP module's supported Drupal versions so upgrades are planned before end of life.
Re-run login and provisioning tests after directory changes, Drupal updates or security releases from the Drupal Security Team.