EspoCRM LDAP Authentication With Active Directory

How EspoCRM LDAP authentication with Active Directory works

If your staff already have Active Directory accounts, the goal is usually one password for EspoCRM that follows the same lifecycle as their other corporate logins. EspoCRM's documented LDAP authorization, which includes an Active Directory example, makes this possible. When a user signs in, EspoCRM checks the submitted credentials against the directory rather than against a password stored in EspoCRM. The example uses port 389, sAMAccountName as the username attribute, and the person object class to find users under a base DN. Staff can then type their familiar Windows-style username, and EspoCRM can create a local user record automatically on first sign-in.

This is LDAP authentication, not OpenID Connect. EspoCRM is still the party that accepts the login and issues the session, so the integration is a directory bind plus a local account, not a token exchange with an identity provider. Be clear about what stays local. Roles, teams, permissions, and the user's place in EspoCRM's access model are configured inside EspoCRM and are not inherited from Active Directory groups by this method. The example also maps givenName, sn, title, mail and telephoneNumber onto the EspoCRM user record, so those profile fields follow the directory, while anything EspoCRM stores itself does not. Confirm this split with your security team before rollout, and check the current EspoCRM release notes for any group-based mapping options, since the supplied documentation does not describe them.

Before you build the configuration, decide which accounts can read the users DN, because EspoCRM needs a system user for that search. Plan that account as a read-only service account, and record who owns its password and how it rotates. Also decide whether automatic user creation is acceptable for every AD account in the search base, or whether the base DN should be narrowed to an approved group of staff. Those two decisions shape most of the security review.

What you need before enabling AD sign-in in EspoCRM

Active Directory sign-in depends on decisions made outside EspoCRM as much as inside it. The cards below cover the platform baseline, the directory account and scope, and the network and transport checks that your directory and security teams should confirm before any configuration starts.

Supported EspoCRM and server stack

Confirm the EspoCRM release line and server stack first, because the LDAP settings are applied in the administration area of a running instance. The server configuration docs list PHP 8.3 to 8.5, MySQL 8.0 or newer, MariaDB 10.6 or newer or PostgreSQL 15, on Apache, Nginx or IIS, with cron required for background jobs. Check the current release on the releases page before you pin a version, since EspoCRM 10.0.0 is the current major line in the facts supplied.

Read-only directory service account

EspoCRM binds to the directory with a system user that needs read access to the DN where Espo users live. Ask your directory team for a dedicated service account with no interactive logon and no rights to change users or groups. Record its distinguished name and password in your secrets store, and agree who rotates the password and when, because a rotation that is missed will stop all staff from signing in.

Users DN and sign-in scope

Set the base DN to the organizational unit or group that holds only the people allowed to use EspoCRM, not the whole domain. Also agree whether sign-in is limited to members of a specific AD group, since the documented example creates users automatically on first login. Decide who is excluded, such as contractors, disabled accounts or service accounts, and confirm how those accounts will be filtered before go-live.

Directory host, port and reachability

Identify the domain controller or directory endpoint EspoCRM will query, and confirm the network path from the EspoCRM server to it through host firewalls and segment rules. The documented Active Directory example uses port 389. Ask the directory team whether that port is permitted from the EspoCRM subnet and whether a failover controller should be named, because a single unreachable host blocks every login.

TLS and certificate requirements

Do not assume the transport model. Confirm with your directory team whether binds must be encrypted, which certificate authority issued the directory certificates, and whether the EspoCRM server must trust that chain. Ask them to confirm whether plain-text binds are permitted in your environment. Record the answer before you copy the documented example, because credentials sent over an unencrypted channel are a security decision, not a default.

Login attribute and fallback plan

The documented setup uses sAMAccountName as the username attribute, so staff sign in with their short account name. Confirm that every user in scope has a unique value for that attribute and that the attribute is populated. Also plan a fallback admin login that does not depend on the directory, and agree who holds it and how it is audited, so an outage in Active Directory does not lock administrators out of the CRM.

Configure the AD bind, username attribute and base DN

This sequence connects EspoCRM to your Active Directory domain controller so that staff can sign in with their sAMAccountName, with accounts created automatically on first login. Each step ends with a check that proves the directory connection, the username mapping and the user creation work before wider rollout.

Create a read-only system bind account
A directory administrator creates a dedicated service account in Active Directory that EspoCRM uses to search for users. It should have read access to the container that holds the EspoCRM users and no administrative group membership. Record its distinguished name and password in your secrets store, not in personal notes. The step is complete when the account exists, is enabled, and its password is stored where the EspoCRM administrator can retrieve it.
Set the LDAP host and port
In the EspoCRM administration area, open the LDAP authentication settings and enter the host name of your domain controller or directory endpoint, along with the port. The documented Active Directory example uses port 389. Confirm with your directory team whether that endpoint is reachable from the EspoCRM server and whether your policy requires encrypted transport. The check is a successful test bind using the system account. If the bind fails, verify network path, DNS resolution and the account credentials before going further.
Set sAMAccountName as the username attribute
Set the Username Attribute option to sAMAccountName. This tells EspoCRM to match the short login name that staff already use on Windows, rather than a full user principal name or email address. Keep the account naming convention in mind, because the value entered at login must match this attribute exactly. The check is a directory search that returns the pilot account when queried by its sAMAccountName.
Set the person object class and base DN
Enter the person object class used for user entries in your directory and the base DN that contains the EspoCRM users. Scope the base DN to the organizational unit that holds staff who should have CRM access, not the whole domain, so that service accounts and disabled groups are excluded. Confirm the exact object class and OU path with your directory administrator, since naming differs between organizations. The check is that a search under the base DN lists the pilot user and no unintended accounts.
Enable automatic user creation
Turn on automatic user creation so that an EspoCRM user record is created the first time a directory user signs in. Map the directory attributes to the matching EspoCRM fields, including givenName, sn, title, mail and telephoneNumber as in the documented Active Directory example. Decide in advance which roles and teams new users receive, because automatic creation alone does not grant the access your teams need. The check is a newly created user record with the expected name, email and role after the pilot sign-in.
Test a plain username login with a pilot account
Sign in to EspoCRM with the pilot account using only its sAMAccountName and directory password, without the domain prefix or email address. Confirm the login succeeds, the user record was created or matched, and the attribute values appear on the profile. Then test a wrong password and a user outside the base DN, and confirm both are refused. Those checks show that the username mapping and scope behave as designed before you widen access.

How Active Directory attributes map to EspoCRM user fields

This table compares each documented Active Directory attribute with the EspoCRM user field it populates, and notes what the directory does not control. Read it as a checklist: confirm each attribute exists and holds a value for your staff before you rely on the mapping. The main takeaway is that sign-in identity comes from the directory, while roles, teams and permissions remain EspoCRM settings.

Active Directory attribute	EspoCRM user field	What to confirm before go-live
sAMAccountName	Username (login name)	Unique per account and the value staff type at sign-in; the username attribute is set to this in EspoCRM
givenName	First name	Populated for every account that should sign in, so profile names are not blank
sn	Last name	Populated consistently, since it appears in record ownership and assignment lists
title	Title on the user record	Filled for roles where the value is useful; blank values simply leave the field empty
mail	Email address	Matches the address used for notifications and any mailbox settings; check for duplicates across accounts
telephoneNumber	Phone number	Format is consistent with how staff expect to see numbers; confirm it is maintained by your directory team
Group membership (not mapped in this example)	Roles, teams and default permissions	Assigned inside EspoCRM by an administrator; directory groups do not set these in the documented example

Choosing the directory setup for your environment

This is the simplest layout: every staff member who should use EspoCRM sits under one organizational unit, and one base DN covers them all. The LDAP settings point the search at that container, the Username Attribute is set to sAMAccountName so people can type their usual domain account name, and the system bind user needs read access only to that OU and its child objects. Sign-in scope is easy to reason about because anyone inside the container can authenticate and anyone outside it cannot.

Base DN: one distinguished name for the users container, with no wider search root than necessary.
Bind user scope: a service account with read access to that container, not to the whole domain.
Who can sign in: members of the container who also have an active, enabled account.
Automatic creation: new users who first sign in get an EspoCRM account, so confirm which default roles and teams they receive.
Attribute mapping: confirm that givenName, sn, title, mail and telephoneNumber are populated consistently in that OU.

Before configuring, ask the directory team whether disabled, contractor or service accounts sit in the same OU, because those accounts would still be searchable by the bind user.

Many organizations keep staff in several OUs, for example by business unit, region or subsidiary, or they run more than one domain. EspoCRM takes one base DN per LDAP configuration in the setup described by the vendor documentation, so a single broad base DN at the forest root can make the search slow and can expose accounts that should not use the CRM. In this layout you need to decide whether one wide search root is acceptable or whether separate configurations, or a deliberate parent container that holds only CRM users, better match your access model. Confirm with the directory team how users are grouped before choosing.

Base DN: pick the narrowest container that holds every intended CRM user, which may mean moving users into a dedicated OU.
Bind user scope: a bind account must be able to read every container in scope, so each additional domain or OU widens its reach.
Who can sign in: users under the chosen base DN only, so cross-domain users may be excluded unless the base DN covers them.
Username collisions: identical sAMAccountName values in different domains can clash, so confirm uniqueness.
Cross-domain trust: confirm whether the directory team allows the bind user to query another domain at all.

Ask for the full list of containers that hold people who need CRM access and the names of any domains involved.

Securing the bind account and the sign-in path

The bind account, the server configuration and the local fallback path together decide how far a directory compromise can reach into EspoCRM. Each card below covers one control to design before go-live, and each one has a check you can run against your own environment.

Least-privilege read-only bind account

The system user EspoCRM uses to search the directory should be a dedicated service account with read access only to the users DN it needs. It should not be a domain administrator, a member of privileged groups, or a personal account. Confirm with your directory team that the account cannot write attributes, reset passwords or read unrelated organizational units. Test the account's reach with an LDAP query tool before you enter it in EspoCRM.

Bind credentials in server configuration

The bind password is stored in EspoCRM's configuration, so the file holding it needs the same protection as other secrets. Limit read access to the web server account and administrators, keep the file out of web-accessible paths and out of version control, and log who can change it. Plan a rotation step for the bind password that updates the configuration and tests sign-in in the same change window.

Encrypted transport for LDAP traffic

The reference Active Directory setup uses port 389, which carries directory traffic without TLS unless you add it. Decide whether LDAP runs over LDAPS or StartTLS before go-live, because bind credentials and user attributes would otherwise cross the network in a readable form. Confirm the certificate chain that EspoCRM's server trusts for your domain controllers, and test with a non-production account first.

Local admin fallback outside AD

Keep at least one local administrator account in EspoCRM that does not depend on Active Directory. If the directory, its certificates or the bind account fail, this account is the only way to repair the configuration. Store its credentials in a sealed vault with a documented owner, and test it on a schedule. Restrict it to recovery work and do not use it for routine administration.

Password policy and 2FA for local accounts

Local accounts, including the fallback admin, sign in with EspoCRM's own password rules, so the password policy and two-factor settings must be configured there. The security docs recommend enforcing a password policy and requiring 2FA. Confirm these settings are enabled for every local account, because they do not apply the same way to directory users.

MFA enforcement for directory users

EspoCRM's own two-factor authentication is not compatible with OIDC, and LDAP sign-in is checked against the directory rather than EspoCRM's password store. Confirm with your identity team whether MFA is enforced at the directory or at a sign-in gateway in front of EspoCRM before go-live. If the answer is no, record that gap as an accepted risk with an owner.

Admin accounts and IP restrictions

Staff who administer EspoCRM should use a separate, non-admin account for daily CRM work. The security docs also recommend restricting access by IP address. Map which networks may reach the admin interface and the login page, then apply those rules at the reverse proxy and in EspoCRM where supported. Verify the rules from an allowed network and from an outside address.

Common AD login failures in EspoCRM and how to fix them

This table pairs each common Active Directory sign-in failure in EspoCRM with its likely cause and the fix to try first. Read it in order when a login fails, starting with bind errors, since a failed bind blocks every other step. Most failures trace back to four settings: the system bind user, the base DN, the username attribute and the automatic user creation option.

Symptom	Likely cause	Fix
Bind fails for every login	The system bind user name, password or DN format is wrong, or the account is locked or disabled in Active Directory.	Test the system user credentials against the directory outside EspoCRM, then re-enter them using the full distinguished name. Confirm the account has read access to the users DN.
Users not found, no results returned	The base DN is set higher or lower than the OU that holds the staff accounts, so the search never reaches them.	Set the base DN to the OU or container that holds the EspoCRM users, then retry a known account. Avoid a domain root search unless the directory is small and access is reviewed.
Login rejected with a valid password	The username attribute is not sAMAccountName, so EspoCRM searches on a field the user does not type or does not have.	Set the username attribute to sAMAccountName, as the Active Directory example in the EspoCRM documentation shows, and have users sign in with their short logon name.
Login rejected after an email or UPN style entry	Users type the user principal name or email address, but EspoCRM matches only the attribute configured for username lookup.	Decide one login format for staff and communicate it. Use the short logon name for plain username logins, and document the format in your onboarding guide.
Valid AD user gets no EspoCRM account	Automatic user creation is off, so the directory account authenticates but nothing is created in EspoCRM.	Enable automatic user creation in the LDAP settings, then confirm the default role and team assignments before the first pilot login.
Name, email or phone fields are empty	The mapped directory attribute (givenName, sn, title, mail or telephoneNumber) is missing or blank on the AD user object.	Check the attribute values on a sample account with an AD administrator. Fill the source data in the directory or remove the mapping for fields you maintain elsewhere.
Connection times out or is refused	A firewall, security group or network segment blocks traffic from the EspoCRM host to the domain controller on the LDAP port (389 in the documented example).	Test connectivity from the EspoCRM host to the directory on the configured port. Ask the network team to open that path for the EspoCRM host only, and confirm DNS resolves the directory host name.
Sign-in works for some staff, not others	Accounts sit in different OUs outside the base DN, or the user lacks the object class the search filters on.	Compare the DN of a failing account with the base DN. Widen the search to a parent OU only where needed and confirm the person object class is present on those accounts.

Questions buyers ask before enabling Active Directory sign-in

How much effort does EspoCRM LDAP sign-in with Active Directory take?

Effort depends mostly on how the directory is organized and how much the rollout has to prove before it reaches staff. A single domain with one users container and clean account attributes is the simplest case. Effort rises with the number of organizational units that hold people who need access, the number of domains or forests, nested group logic, and whether accounts carry the attributes you want to map into EspoCRM. A security review, change approval and a test plan add time that is often larger than the configuration itself. Ask any partner to break its quote into directory analysis, configuration, security review, testing and handover, so you can see which part drives the number.

Can an internal admin set up Active Directory sign-in alone?

A capable EspoCRM administrator can read the official LDAP documentation and configure the connection, but the work touches three areas that rarely sit with one person: the directory, the application and security. The directory side needs someone who can create a read-only system account and confirm which base DN and object class hold your users. The security side decides how the bind password is stored, whether the connection is encrypted and who approves the change. Most teams that succeed with this work in-house assign those responsibilities explicitly and test with a pilot group before enabling sign-in for everyone.

What do the directory and security teams need to provide?

The directory team typically provides the DNS name of a domain controller, the port and transport to use, a read-only system user that can search the users DN, and confirmation of the sAMAccountName value for each person. The security team provides guidance on how the system bind password is stored and rotated, which accounts may use the service identity, and whether the traffic must be encrypted. Both teams should agree on who may disable an account, since that change should flow from the directory and not depend on a separate EspoCRM setting. Confirm these needs with your own directory owner before the build starts.

How long does testing usually take for AD sign-in?

No duration can be stated in advance because testing length depends on scope. A narrow rollout to one team with a few test accounts is much shorter than a rollout across several organizational units, with different attribute values and a required approval process. Testing should cover a successful bind, a failed password, a disabled directory account, a user missing from the base DN, first-login user creation, attribute mapping for name, title, email and telephone, and the fallback path for administrators. Ask a partner to state the test cases and the environments they will use in the written scope.

Does Active Directory sign-in replace the need for a local admin account?

No. Directory sign-in controls how staff authenticate, but it does not remove the need for a local administrator account in EspoCRM. A local admin is useful when the directory or the connection is unavailable, and it is the account you use for recovery. The EspoCRM security documentation advises against using admin accounts for daily work and recommends restricting password recovery for admins, so keep the local admin account for emergencies, protect it with a strong password and two-factor authentication where supported, and record who may use it. Confirm the recovery procedure in your own environment before enabling sign-in for all users.

What should a written quote for AD sign-in include?

A useful quote lists each deliverable and the environment it applies to. Ask for the directory assessment, the number of domains and organizational units in scope, the system account design, the TLS approach, the attribute mapping list, the test plan with named test cases, the rollback plan, the handover documentation and any post-go-live support. Also ask what the partner needs from your team and what happens if the directory structure differs from what was assumed. Costs that recur, such as ongoing support or a retainer, should be separated from the one-time implementation.

What breaks most often after enabling AD sign-in?

The most common problems come from the directory rather than EspoCRM. Users are placed in an organizational unit outside the base DN, so they cannot sign in even though their password is correct. The sAMAccountName differs from the name people type, or accounts share attribute values that EspoCRM expects to be unique. A system account password expires, which blocks all directory sign-ins at once. Plan a monitoring check for failed binds, a documented owner for the system account password, and a list of which directory groups or units must stay in scope after reorganizations.

What changes for staff, admins and the directory team after go-live

After go-live, password changes and lockouts move to Active Directory. Staff reset passwords through the directory, not inside EspoCRM, and a locked AD account blocks EspoCRM sign-in as well. The service desk needs to know this before the first ticket arrives, because a user who tries to reset an EspoCRM password will not find a way to do it there. Confirm with your identity team which self-service reset tool staff should use, and whether the EspoCRM login page should point people to it.

Disabling an AD account is now the offboarding step that actually removes CRM access. A leaver's account is disabled in the directory, and the next login attempt fails. Existing EspoCRM user records remain with their history, so the CRM team still needs its own process for reassigning open accounts, leads and cases. New hires need an AD account before they can reach EspoCRM at all, which means the onboarding request should go to the directory team first. Ask them to confirm how quickly a new account appears in the Espo Users DN after creation, since that determines when a new starter can sign in.

Admins keep full control of roles and teams inside EspoCRM. Directory membership does not assign CRM permissions, so someone still has to set each user's role and team after automatic user creation. Review the mapped attributes, such as mail, title and telephoneNumber, whenever the directory schema or the way staff are grouped changes, and recheck the bind account's permissions when the directory team rotates its service credentials or restructures the users container. A change in either place can break sign-in for a whole group without any visible error in the CRM.

How DeployOpen scopes and delivers EspoCRM directory sign-in

DeployOpen treats directory sign-in as a scoped piece of work inside your infrastructure, not a generic setting. We agree what the LDAP connection must do with your Active Directory forest, build and test it in your environment, and hand over the configuration and the steps your team needs to run it.

How we scope

Confirm which Active Directory domain controllers and ports EspoCRM can reach, and whether they use encrypted connections.
Define the system bind account, its least-privilege read access to the users DN, and who owns its password.
Agree the base DN, username attribute, user creation rules and attribute mapping in writing before build starts.

How we build

Configure the LDAP authorization settings in EspoCRM on a staging instance that mirrors your production hosting.
Test plain username logins with sAMAccountName, including disabled accounts, users outside the base DN and mistyped passwords.
Verify that givenName, sn, title, mail and telephoneNumber map to the intended EspoCRM user fields and that new users receive the roles you set.

How we hand over

Deliver a written configuration record listing each setting, its value and the reason it was chosen.
Document the bind account rotation steps, the fallback login path for administrators and the troubleshooting checks for failed binds.
Walk your administrators through the test cases so they can repeat them after upgrades or directory changes.

How we support

Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
Ongoing support, upgrades and re-testing after EspoCRM or Active Directory changes are available as a retainer.
Confirm with your directory team how group membership, password policy and account lockout will apply before go-live.

EspoCRM LDAP authentication with Active Directory