How to plan Matrix LDAP authentication when your users live in a directory
If your self-hosted Matrix deployment must accept existing directory accounts from LDAP or Active Directory, you need to choose the authentication path before you build anything else. The matrix-synapse-ldap3 module provides LDAP login on Synapse, but it is in maintenance mode, receiving bug and security fixes only, and it is not compatible with Matrix Authentication Service (MAS). For that reason, the projects point to Dex running alongside MAS as the LDAP backend for new deployments.
The projects document several ways to sign users in, and each one changes what you build. Synapse supports single sign-on through OpenID Connect providers, SAML2 and CAS, and it can use a password provider module such as matrix-synapse-ldap3. MAS uses upstream OpenID Connect providers such as Keycloak, Microsoft Entra ID, Google and Authentik, and it has no built-in SAML or LDAP upstream. Before you commit, confirm with your identity team which of these your directory can serve, and whether your Synapse version and MAS plan can use it. Ask the Matrix projects for the current compatibility notes rather than relying on older guides.
This page covers the prerequisites your directory team must provide, the build sequence, how directory attributes map to Matrix user IDs and display names, the security settings for bind accounts and TLS, the tests you should run before users log in, and the failure points that most often delay go-live. Plan the directory side first. Identify the service account that will bind to the directory, the search base and user filter, and which group or attribute decides who may use Matrix at all. Confirm whether the directory exposes accounts that are disabled, expired or locked, and how those states should affect Matrix access.
A mapping decision comes early. The localpart of each Matrix user ID is derived from an attribute in the directory, usually a login name or a stable unique identifier. Changing that attribute later creates a new Matrix identity and can orphan room history, so agree the source attribute with the directory owners and record it. Decide also how display names and email addresses are populated, and whether user changes in the directory should propagate on the next login or require an administrator action. Because the server_name setting fixes how user IDs are formed, settle it before the first user logs in.
Test with a non-production directory tree and a small group of pilot accounts. Verify successful and failed logins, disabled accounts, password changes, and users removed from the permitted group. Confirm that TLS certificates validate against the directory, that the bind account has read-only rights, and that logs do not record passwords. Then rehearse the migration path to MAS if your plan includes it, since the MAS migration guide describes that move step by step. Record the decisions and test results so your auditors and security team can trace how directory access to Matrix was approved.
What you need in place before you touch login settings
Login changes depend on three things: the Synapse platform, the connection to your directory, and the people who run the hosts in the login path. Work through these checks before you edit any configuration file, because most failed LDAP or Active Directory sign-ins trace back to one of them. Record each check so the directory, database and identity teams can confirm it.
Synapse platform floors
Synapse 1.143.0 and later require PostgreSQL 14 or newer, and 1.142.0 and later require Python 3.10 or newer. The Synapse documentation recommends PostgreSQL for production, with SQLite also supported. Check the database and interpreter versions on the hosts you plan to use, including any managed database service, and confirm which Python interpreter your install method uses. Both floors can block an upgrade before any login setting changes, so verify them first.
Confirm the Matrix release
Choose the Synapse release from the Synapse GitHub releases page at the time of work, because new versions appear regularly and the floors above depend on which release you pick. Read the upgrade notes for every release between your current version and your target. Record the version you selected and the date you checked it, so the change record shows which notes were reviewed.
Directory access account
Create a dedicated bind account in the directory for the identity component to search for users and groups. Scope its read permissions to the user and group containers that hold Matrix users, and confirm it can read the attributes the login mapping needs, such as the username and display name. Ask the directory team who owns the password, how it rotates and where it is stored. Use this account only for directory lookups, and keep it separate from personal administrator accounts.
LDAP or LDAPS reachability
Confirm that the hosts running the identity components can open a connection to the directory on the LDAP or LDAPS port your directory team operates, and that firewalls and network policy permit it. Prefer LDAPS so bind credentials are not sent in clear text. Test from the same host and network segment that will run the login component, because a path that works from a workstation may fail from a server.
Certificate trust for the directory endpoint
If the directory serves LDAPS with an internal certificate authority, the root or intermediate certificate must be trusted by the operating system or container image running the identity component. Confirm the certificate name matches the hostname you configure and check its expiry date. Ask the directory team how renewals are announced, because a lapsed certificate stops logins without any change on the Matrix side.
Named owner for Dex and MAS hosts
Dex and Matrix Authentication Service sit in the login path, so each host needs one named owner who can approve changes, respond to outages and hold the certificates and bind credentials. The owner should also be accountable for patching, backups and access to configuration files. Without a named owner, a directory change or a failed certificate renewal can stay unresolved until users report that they cannot sign in.
Why the LDAP3 module is a dead end for new MAS deployments
For a new Matrix deployment, the matrix-synapse-ldap3 module is a poor foundation if you plan to run Matrix Authentication Service (MAS). The module is an LDAP3 password provider: it lets Synapse check a user's LDAP username and password at login. Its repository says the project is in maintenance mode, receiving bug and security fixes but no new features. The same repository states that Synapse's password provider functionality is not compatible with MAS and that deployments should migrate to MAS, using Dex with MAS as the LDAP backend. Treat that statement as the project's own position on where directory login is going. Before you choose the module, confirm the version you would deploy and check its release history for the security fixes you would depend on.
The incompatibility follows from how MAS is built. The MAS migration guide states that MAS has no built-in SAML or LDAP upstream providers and does not support custom Synapse password provider modules. MAS authenticates users through upstream OpenID Connect providers, such as Keycloak, Microsoft Entra ID, Google and Authentik, so a directory cannot be attached to MAS directly. It has to sit behind an OIDC layer. Dex is the bridge the projects recommend for LDAP. It federates to the directory and presents OIDC to MAS. That chain adds a service you must deploy, secure, back up, patch and monitor, along with its own client registration and token settings. Scope that operational load before you commit to the MAS route, because it replaces a single Synapse setting with a second identity component.
The decision comes down to two options. The first is to stay on Synapse, keep the module, and accept maintenance-only status for a component that sits on your login path. That path is quicker to start, but it leaves you planning a later migration, and it may slow upgrades if the module lags a Synapse release you need. The second is to move authentication to MAS with Dex, which is the route the projects document. Synapse also supports single sign-on natively through OpenID Connect providers, SAML2 and CAS, so ask whether your directory can reach Synapse through one of those without the module. Record the choice in your architecture decision record with an owner, a review date and an explicit exit condition.
Active Directory on premises and Microsoft Entra ID are different systems, and each needs its own confirmation. Entra ID is an OIDC upstream that MAS supports, which may remove the need for Dex in a cloud identity setup. Confirm the tenant configuration, the claims Synapse or MAS will receive, and how group membership maps to Matrix roles. On-premises Active Directory is reached over LDAP, so the Dex connector needs your domain controller addresses, certificate trust for LDAPS, a bind account with the right scope, and attribute names that match your schema. Test a failed bind, a disabled account and a password change before go-live, because those cases decide who can still log in.
How to move directory login from Synapse to MAS through Dex
This sequence moves directory sign-in for Matrix from the matrix-synapse-ldap3 password provider to Matrix Authentication Service (MAS), with Dex translating LDAP or Active Directory into OpenID Connect. Each step ends with a check so the team knows whether to continue. The MAS migration guide sets the overall order of work, and this sequence fills in the directory-specific steps.
Inventory password-provider accounts and user IDs
The Synapse administrator lists every account that signs in through the LDAP password provider, with its full Matrix user ID, its directory username, and its admin or bridge status. Compare the localpart of each Matrix ID with the directory attribute that will become the login name, and record any accounts where they differ. Keep this inventory as the reference for later matching. The step is complete when every active account has a documented mapping from Matrix ID to directory identifier, and the team has agreed how exceptions will be handled.
Stand up Dex and bind it to the directory
The identity team deploys Dex in the same environment as the directory connection, using a read-only service account and TLS for the LDAP or Active Directory connection. They set the base search path, user filter and any group filters, then confirm the connector options against the current Dex documentation, since key names and behavior change between releases. The check is a successful bind by the service account and a user search that returns a known test account with the expected username and email attributes.
Register Dex as an upstream OIDC provider in MAS
The platform team creates an OAuth client for MAS in Dex, sets the redirect URI that MAS publishes for upstream providers, and adds the Dex issuer, scopes and claim mapping to the MAS upstream provider configuration. The claim that becomes the Matrix localpart must match the inventory from step one, so confirm the exact claim options in the current MAS upstream identity provider documentation. The check is that MAS shows Dex as a sign-in option and that the discovery document loads without errors.
Configure MAS with the homeserver
The Synapse team configures MAS with the homeserver details, the shared secret used between MAS and Synapse, and a database for MAS state, following the MAS migration guide for the required settings and their order. Confirm the homeserver endpoint and secret names in the current MAS and Synapse documentation before writing them into configuration. The check is that MAS starts cleanly, reports a working connection to Synapse, and that Synapse accepts requests that MAS makes on its behalf.
Test a pilot login on a small account set
The team selects a small group of pilot accounts from the inventory, including at least one account with admin rights and one account with a non-standard username mapping. Each pilot user signs in through Dex and MAS and the team checks that the resulting Matrix ID matches the ID recorded in step one, that existing rooms and message history are visible, and that the account's rights are unchanged. Record any mismatch and resolve it before moving more users. The step is complete when every pilot account returns the expected user ID and history.
Cut over and retire the password provider module
After the pilot passes, the Synapse team moves all remaining users to the MAS sign-in path, communicates the change, and removes the matrix-synapse-ldap3 module from the homeserver configuration. Because the Synapse upgrade notes warn that rollback can be difficult, keep a tested backup and a documented rollback decision point before removing the module. The check is that all active accounts sign in through MAS, Synapse starts without loading the module, and the logs show no password-provider authentication attempts.
How directory attributes map to Matrix accounts
This table compares each directory attribute that Dex or the LDAP provider returns with the Matrix field it fills, plus the server_name setting that fixes the form of every user ID. Read it before the first login, because the login identifier decides whether existing Matrix accounts are matched. Assign an owner to each mapping and verify it with a test account before rollout.
| Source attribute | Target field | Owner | What to verify |
|---|---|---|---|
| Login identifier (uid or sAMAccountName, as returned by Dex) | Localpart in @localpart:server_name | Directory team with Matrix admin | Choose one unique, stable value. Changing it later can create duplicate accounts for the same person. |
| Display name attribute (for example cn or displayName) | Matrix display name | Matrix admin team | Confirm the attribute is populated for all users and check when name changes reach the Matrix profile. |
| None (configuration value) | Domain in @localpart:server_name | Platform engineering | Decide before the first login, since it is part of every user ID. Confirm it matches your DNS and federation plan. |
| Group membership (memberOf or equivalent group claim) | Matrix admin role or room role, mapped in configuration | Matrix admin team, with directory group owners | Confirm each directory group maps to one role and who approves changes to that mapping. |
| Account status or disabled flag | Deactivation or lock of the Matrix account | IAM team with Matrix admin | Confirm whether disabled directory users can still log in and how their existing sessions are handled. |
| Existing local Matrix accounts (not a directory attribute) | Accounts already holding the same localpart | Matrix admin team | Compare existing localparts with the directory list before cutover to catch collisions and duplicates. |
Securing the directory bind and the trust between Dex and MAS
The directory bind is the one credential that can see every user, so it needs the tightest handling in the design. The cards cover the bind account, transport trust, secret handling, internal TLS, federation exposure and administrative access that keep the Dex and MAS path defensible after go-live.
Read-only bind account
Create a dedicated directory account for Dex that can search the user subtree and read only the attributes Dex maps. Confirm in the directory that it cannot write, reset passwords or read groups outside the scope Dex uses. Log failed bind attempts from this account and alert on them, because repeated failures often point to a stale password after rotation or to a guessing attempt against the bind.
LDAPS or StartTLS with validation
Send every bind and search over LDAPS or StartTLS, and configure Dex to validate the directory server certificate against your internal certificate authority. Check that the certificate name matches the hostname Dex connects to, and confirm the CA bundle is mounted in the Dex container. Chain errors usually appear as generic login failures, so test the connection from the Dex container before you test a sign-in.
Secrets held in a secret store
Keep the bind password, the OIDC client secret and any signing keys in a secret store such as OpenBao or your platform's secret manager, and inject them at runtime. Keep them out of values files, container images and Git history. Agree a procedure for a lost directory password: rotate it in the directory, update the store, restart Dex, then review bind logs for the period the old password was valid.
TLS between Dex, MAS and Synapse
Dex, MAS and Synapse exchange tokens and client credentials over HTTP, so each hop needs TLS. Issue these endpoints certificates from your internal CA, configure each client to validate its peer, and include the full issuer chain in every trust store. Schedule rotation of these internal certificates alongside the directory certificate, and test a rotation in staging before production.
Restricting the federation listener
Synapse federates on port 8448 by default. The Synapse configuration manual describes federation_domain_whitelist, where an empty list disables federation, and recommends firewalling the federation listener. Decide the federation policy before go-live, make the whitelist match it, and test from outside your network that the listener answers only where you intend.
Limiting admin and Dex configuration access
Restrict the MAS admin surface to an administrative network or VPN, and give each administrator an individual account. Confirm that multi-factor authentication is enforced at the upstream identity provider. Keep the Dex configuration in version control with protected branches, and review changes to the connector block, since a altered search base or user filter can widen who is able to sign in.
Common failures in LDAP and Active Directory login and how to fix them
This table lists the login failures teams most often hit when moving directory sign-in from the matrix-synapse-ldap3 module to Matrix Authentication Service with Dex. Read each row in order: the likely cause, the check to run, then the fix. Exact Dex connector and MAS upstream settings change between releases, so confirm every field name and value against the current Dex and MAS documentation before you change production.
| Failure | Likely cause | Check to run | Fix |
|---|---|---|---|
| Synapse module loaded but MAS still in use | The Synapse password provider is still configured, but MAS handles login and never calls it. | Confirm which service authenticates users and review homeserver config for password provider entries. | Remove the password provider block after MAS is live and point login at the Dex upstream. Confirm steps in the MAS migration guide. |
| Dex bind errors | The base DN is wrong or the service account cannot read the user subtree. | Test the bind with the service account from an LDAP client and compare the base DN with the directory tree. | Correct the base DN and grant the service account search rights on user entries. Confirm connector settings in current Dex docs. |
| Certificate chain errors on LDAPS | The directory certificate chain lacks an intermediate, or Dex does not trust the internal root CA. | Verify the full chain from the Dex host against the LDAPS port with an OpenSSL client test. | Install the issuing CA chain in the Dex trust store and restart. Do not disable certificate verification in production. |
| Users receive a new Matrix ID | The directory attribute mapped to the Matrix localpart differs from the one used for existing accounts. | Compare the claim Dex sends for a test user with the localparts of existing accounts. | Map the claim to the attribute used before. If IDs must change, plan a rename path with users and rooms before rollout. |
| Duplicate accounts after an identifier change | The identity was keyed on a mutable attribute, so a changed value created a second account. | List accounts that share a display name or email and compare their upstream subject values. | Decide which account keeps the identity, then deactivate duplicates through your documented admin process. Key identity on a stable attribute before go-live. |
| Expired or rotated service passwords | The bind password was rotated or the service account expired or locked out. | Test a bind with the stored credential and check the account's expiry and lockout state in the directory. | Update the secret in the Dex configuration source, restart Dex, and name an owner for each rotation schedule. |
| Login succeeds in Dex but fails at MAS redirect | The redirect URI, issuer or client secret in the MAS upstream entry does not match the Dex client. | Compare the redirect URI, issuer and secret on both sides, including scheme and trailing slashes. | Correct the mismatched value on the side that is wrong, then retest a full login in a clean browser session. |
What changes for existing users when you cut over
Existing users will notice the cut over in the login path first. Once Matrix Authentication Service (MAS) sits in front of the homeserver, a user who opens Element or another client is redirected to an upstream identity provider, such as Dex in front of your directory, to enter credentials, and is then sent back to the client. That redirect is different from the username and password form they used with the LDAP3 password provider, and it is the change most likely to generate help desk tickets. Plan a short guide with screenshots of the new flow, and confirm in the pilot exactly which screens appear, including any browser or client refresh a user must perform after the switch.
Users may also see a new session and device verification prompt. Depending on how the client and homeserver handle sessions after the change, a user may be asked to verify a device they previously trusted, or may find older sessions no longer listed as active. Confirm this in the pilot with a test account that has several devices and encrypted rooms, and record which devices need manual verification. Password resets and account lock-outs also move. Under the directory-backed model, the directory team usually owns password changes and lock-out policy, while the Matrix admin owns session and device state. Write down who handles a locked-out user, who resets a forgotten password, and whether a user can still change a local password that the homeserver would otherwise accept.
Existing accounts must be matched to directory identities before anyone logs in. Decide which attribute is the stable key, commonly the directory username or an immutable identifier, and confirm that the localpart of each Matrix ID maps to exactly one directory entry. Check for accounts that exist only in Matrix, accounts whose directory names have changed, service and bot accounts that never had a directory entry, and duplicate or disabled accounts. In the pilot, compare a sample of Matrix user IDs against the directory, and decide in advance how mismatches are resolved, because a wrong match can give one person control of another person's history.
Plan communication and a rollback window together. Tell users the date they will be redirected, what they must do on first login, and where to report problems, and give them a point at which the old login path closes. Set the rollback window in writing with the owner who can make the call. Rollback is the hard part. The Synapse upgrade notes warn that rolling back can be difficult because database schema changes between releases may not reverse cleanly. Any upgrade that runs alongside the authentication change can therefore make a return to the previous state impossible without restoring from backup. Before cut over, confirm with the Synapse and MAS release notes which schema changes run, take a tested PostgreSQL backup, and decide whether rollback means reverting configuration only or restoring the database to a point before the change.
Questions teams ask before they plan LDAP or Active Directory login for Matrix
Is matrix-synapse-ldap3 still safe to use with Synapse?
The module still receives bug and security fixes, but it is in maintenance mode and gets no new features, according to its repository. That makes it a reasonable choice for an existing Synapse deployment that works today, and a poor starting point for a new one. The repository also states that Synapse's password provider functionality is not compatible with Matrix Authentication Service, so it is a dead end if you plan to adopt MAS. Before you rely on it, confirm the current release against your Synapse version, check the open issues for your directory type, and record a migration path to MAS with Dex. Your security team should review that decision in writing, because the module's future depends on upstream maintainers.
Why can't Matrix Authentication Service connect to LDAP directly?
MAS has no built-in LDAP or SAML upstream provider, so it cannot bind to a directory the way Synapse's password provider does. MAS is designed to sign users in through upstream OpenID Connect providers such as Keycloak, Microsoft Entra ID, Google or Authentik. The MAS migration guide also states that MAS does not support custom Synapse password provider modules, which rules out reusing an LDAP module with it. The usual route is to place an identity broker between the two systems. Dex can present an LDAP or Active Directory backend to MAS as an OpenID Connect provider, so MAS receives standard tokens and never talks to the directory. Your team then owns one more service to run, patch and back up.
Does Active Directory work with Matrix through Dex?
Yes, Active Directory is a supported backend for the Dex route that the Matrix projects describe for LDAP directories, but the details depend on your directory configuration. Dex sits between MAS and the directory, authenticates users against LDAP, and returns OpenID Connect claims to MAS. Confirm the Dex connector and version you intend to use, how it handles your Active Directory schema, and whether group membership is needed for access control. Also confirm how your AD environment handles TLS, service account permissions and account lockout, since these affect the login experience and the security review. Treat the connector behavior as something to validate in a pilot, not something to assume from this summary.
What drives the effort of an LDAP or Active Directory login project for Matrix?
Effort depends on the written scope, and the main drivers are the following. The number of accounts affects synchronization, testing and the size of the pilot. Identifier mapping matters most: deciding which directory attribute becomes the Matrix localpart, and how existing Synapse users with password-based accounts are matched, often takes the most design time. The number of Matrix hosts and whether you run workers changes how many login endpoints must be configured and tested. Dex and MAS hosting choices, including whether they share infrastructure with existing identity services, change the build and the operations load. Testing covers failed logins, lockouts, group changes and rollback. Ask for each driver to appear as a line item in the quote, so you can see what changes the price or duration.
What does the work need from our team?
Plan for four inputs before the build starts. First, directory access: a read-only service account, documented search bases, and an owner who can answer schema questions. Second, certificate ownership: someone must control the TLS certificates for the directory, Dex, MAS and the Matrix domain, including renewal. Third, a pilot group of real users who can test logins and report problems before the rest of the organization is moved. Fourth, a change window that your operations team approves, because login changes affect every user and may require a Synapse restart. Your team should also name a decision owner for identifier mapping and for the cutover date. Missing any of these inputs usually delays the project more than the technical work does.
Can our own team build LDAP or Active Directory login for Matrix without a partner?
Yes, a team with experience running Synapse, an OpenID Connect provider and directory services can build this, and the Matrix and Dex documentation describes the components. The skills needed are directory administration, TLS, Synapse configuration, MAS deployment and secure testing. The main risks for an internal team are identifier mapping mistakes, which can strand accounts or create duplicate identities, and an unplanned move away from the deprecated module. Ask whether your team has done a Synapse upgrade with a database migration, since MAS adoption changes the authentication path in ways that resemble one. If those skills are thin, a fixed-scope engagement can cover design, build, testing and handover, with the scope agreed in writing before work starts.
What should we ask for in a fixed-scope quote for this work?
Ask for a written scope that lists each component: the Synapse version and deployment model, whether MAS and Dex are new or existing, the directory type and the number of accounts in scope, and how identifier mapping will be designed and documented. The quote should name the environments covered, such as development, pilot and production, and the testing included, such as the pilot group, failed-login cases and rollback. Confirm what is handed over, including runbooks, configuration and a summary of decisions. Ask which items are one-time and which recur, such as support or upgrades under a retainer. Ask what the client must provide, and what happens if directory or certificate access is delayed. Figures should follow from this written scope, so request timing and cost only once the scope is agreed.
How DeployOpen scopes and delivers Matrix directory login
DeployOpen plans Matrix directory login around the authentication path your homeserver will run on. Because matrix-synapse-ldap3 is in maintenance mode and its password provider is incompatible with Matrix Authentication Service, we first confirm which path fits your directory and Synapse version. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- The written scope names your directory type, such as Active Directory or another LDAP directory, and the account attributes involved.
- It records whether Synapse keeps its password provider module or moves to Matrix Authentication Service with Dex as the LDAP bridge.
- Scope also covers user mapping, deactivation handling, and which clients and admin accounts need directory access.
How we build
- We build the chosen route in a test environment that mirrors your directory, with test accounts for each login case.
- The directory bind account is set up with least-privilege read access, and every search filter is documented as configured.
- We test lockout, password change, group-based access and disabled-account behavior before any user sees the new login.
How we hand over
- Handover includes the configuration files, directory query settings and a runbook for each login path that was built.
- Documentation records the maintenance status of any module in use and the steps required to migrate to Matrix Authentication Service.
- Your team receives a rollback procedure, since Synapse upgrade notes warn that rolling back after schema changes can be difficult.
How we support
- Ongoing support, upgrades and testing are available as a retainer that can cover the homeserver, MAS and Dex components.
- A retainer can review upstream release notes so directory login changes are checked before each planned upgrade.
- Confirm response expectations, patch handling and escalation terms in the written agreement before signing any support commitment.
