How an authentik LDAP source syncs users from OpenLDAP
Your directory already holds the users, groups and passwords, and authentik has to sign those people in to your applications. The supported method is the authentik LDAP source, which imports users and groups from the directory into authentik. The sync creates and updates objects only inside authentik. It does not write anything back to the directory, so creating a user in OpenLDAP or 389 Directory Server from authentik needs custom automation that you would plan and test separately. This page covers OpenLDAP and 389 Directory Server, along with other LDAP servers that expose the same kind of user and group tree.
Before you configure the source, decide what the sync should see. The source takes a base distinguished name for users and another for groups, and these scopes determine which accounts become authentik users. Confirm with your directory team which organizational units hold active people, which hold service accounts, and how disabled accounts are marked, because a scope that is too broad imports accounts you never meant to sign in. Property mappings then translate directory attributes, such as the mail and display name fields, into authentik user attributes. Check the mappings against a few real test accounts before you run a full sync, and confirm how your server names the group membership attribute, since that differs between OpenLDAP schemas and 389 Directory Server deployments.
Password handling is the decision with the most security impact. With the LDAP password backend, authentik checks the password against the directory at login. The option to update the internal password on login is off by default. If you turn it on, authentik stores a hash of the LDAP password the first time each user signs in through that backend. That gives you a local copy for fallback and faster checks, but it also means authentik holds credential material that the directory no longer controls, so a password change or account lockout in the directory will not remove the stored hash. Write down whether you need that behavior, who owns the decision, and how you will handle users who leave the directory. Test a password change and a disabled account in a staging environment before you rely on either.
Prerequisites for syncing OpenLDAP or 389 Directory Server into authentik
An LDAP source is only as reliable as the environment underneath it. The items below cover the authentik version, the directory account, the network and TLS path, the database and the sizing decisions that must be settled before any source is configured. Confirm each one in your own environment first, because a gap in any of them shows up later as a failed or partial sync.
A supported authentik version
Check the version you plan to run against the authentik security policy before choosing it. The policy lists 2026.5.x and 2026.8.x as the series receiving security fixes, and the project announces security releases at least 24 hours in advance. Confirm which series your team can keep current, since LDAP source behavior and settings can change between releases and an upgrade mid-project adds risk.
A read-only directory bind account
Create a dedicated service account in OpenLDAP or 389 Directory Server with read access to the users and groups under the search base you plan to sync. Ask the directory team to confirm the account can read the attributes you will map, including group membership and any password-related attributes they are willing to expose. Keep it separate from personal and administrative accounts, and record who owns its password rotation.
Search base and scope design
Decide which organizational units or subtrees authentik should read before you connect. A narrow base limits what enters authentik and shrinks the blast radius of a mistaken filter, while a broad base pulls in service accounts and retired staff. Document the base DN, the user and group filters and the owners who approve changes to them.
Network paths and TLS certificates
Open the path from the authentik server and worker containers to the LDAP server on the port you will use, and confirm that the directory presents a certificate authentik can validate. Get the CA chain for an internal certificate authority in hand before testing, and ask the directory team how they will handle certificate renewal. Check that firewalls and load balancers in between do not drop long-lived LDAP connections.
A dedicated PostgreSQL database
authentik stores all configuration and data in PostgreSQL, and the worker container runs background tasks such as directory syncs. Provision a managed or separately operated PostgreSQL instance for production rather than relying on a bundled test database, and confirm backup and restore responsibilities before the first import. Imported user records and any hashes stored locally will live in this database.
Sizing for the user population
Size the authentik server and worker for the number of users and groups you expect to import, not only for the first login test. The Docker Compose guide positions a host with at least 2 CPU cores and 2 GB of RAM for test and small-scale production, so larger populations need a deliberate capacity review. Confirm the expected object counts and sync frequency with your directory team.
Directory server versions to confirm
Record the exact OpenLDAP or 389-ds-base version your directory runs before you test. The current OpenLDAP releases are 2.7.1 (feature) and 2.6.15 (long term support), and 389-ds-base 3.3.1, 3.2.3 and 3.1.5 were released on September 7, 2026. Confirm with the OpenLDAP Project or your distribution vendor which release your servers should run and how they are patched, because the directory is the source of truth for every imported object.
Configuring the LDAP source in authentik step by step
This sequence connects authentik to your OpenLDAP or 389 Directory Server, imports the users and groups you intend to manage, and confirms that a directory user can sign in through the LDAP password backend. Each step ends with a check so the next step starts from a known state.
Create a read-only bind account in the directory
Your directory administrator creates a dedicated service account that authentik uses to bind and search. Grant it read access to the user and group subtrees you plan to import, and do not give it write access, since authentik's LDAP source only creates or updates objects inside authentik. Confirm the account works by running an LDAP search with it from a host that can reach the directory, using the same bind DN and password you will enter in authentik. The check passes when the search returns the expected entries and an invalid password is rejected.
Confirm TLS and network reachability to the directory
Confirm that the authentik server and worker containers can reach the directory on the LDAP port you intend to use. Obtain the certificate chain for the directory's TLS endpoint, because authentik needs it to validate the connection when you enable TLS in the source. Ask your directory team whether the server certificate covers the hostname you will put in the server URI. The check passes when a TLS handshake succeeds from inside the authentik container network, not only from your workstation.
Create the LDAP source with server URI and bind credentials
In the authentik admin interface, create a new LDAP source and enter the server URI, the base DN for the directory, and the bind DN and password of the service account. Set the TLS options to match your directory's certificate setup, and provide the CA certificate if your directory uses a private CA. Save the source without enabling broad sync yet. The check passes when the source page saves without error and the connection status shows the bind succeeding.
Set user and group search filters and sync scope
Define the search base and object filters for users and groups so that only the intended entries are imported. For OpenLDAP, common object classes are inetOrgPerson or posixAccount for users and groupOfNames or posixGroup for groups, but confirm the classes used in your own schema. Limit the scope to the subtrees that belong to this source, so that service accounts and retired users stay out of authentik. The check passes when a dry search with these filters returns the expected count of users and groups from your directory.
Review property mappings before importing
Open the source's property mappings and confirm which LDAP attributes populate authentik user fields such as username, email, name and group membership. Map the attribute that holds the unique user identifier and check that it is stable, because it governs how authentik matches an entry on later syncs. Decide whether group membership is taken from the user entry or from the group entries, and document the choice. The check passes when a sample user preview shows every required field populated correctly.
Decide on storing password hashes locally
Decide whether authentik should store a hash of each user's LDAP password after login. The source's Update internal password on login option is off by default, and it stores a hash only when users sign in through the LDAP password backend. Record this decision with your security team, since turning it on creates a local copy of password-derived data in authentik's database. The check passes when the option matches the approved decision and the change is documented.
Run the initial sync and verify object counts
Trigger the first sync from the LDAP source and watch the background task in the admin interface until it completes. Compare the number of users and groups created in authentik with the counts from your directory search, and check a sample of entries for correct attributes and group membership. Confirm that the source does not change anything in the directory itself. The check passes when counts match the expected filtered totals and sampled entries show correct data.
Test one login through the LDAP password backend
Sign in to authentik as a test user from the imported set, using the directory password, and confirm the login succeeds through the LDAP password backend. Then try a wrong password and confirm it fails. If you enabled local hash storage, repeat the successful login and check the user record for the updated internal password state. The check passes when the valid login completes, the invalid one is rejected, and the user's group membership is visible in their profile.
Mapping directory attributes to authentik users and groups
This table compares the directory attributes a team typically maps into authentik user and group fields, and notes where OpenLDAP and 389 Directory Server schemas differ. Read each row as a question to answer in your own schema before you build the property mappings, because the attribute names and group models in your directory decide what authentik receives.
| Directory attribute | authentik field and purpose | Schema notes and what to confirm |
|---|---|---|
| uid (or sAMAccountName equivalent) | Username, the field users type at sign-in and the value most applications receive | Both OpenLDAP and 389 Directory Server commonly use uid for login names, but your schema may use another attribute. Confirm it is unique across the search base and stable over time. |
| Email address, used for notifications, recovery and some application claims | Usually present in both schemas, but multi-valued in some directories. Confirm which value is primary and whether unverified addresses can appear. | |
| cn | Display name or full name in the user profile | cn is a naming attribute and is not guaranteed unique. Do not use it as a username or correlation key. |
| entryUUID or nsUniqueId | Stable external identifier used to correlate an entry across renames and moves | OpenLDAP exposes entryUUID and 389 Directory Server uses nsUniqueId. Confirm which one your source and mappings read, since DN-based identifiers change when entries move. |
| memberOf (overlay-generated) | Group membership on the user, if the server maintains it | memberOf is not always enabled by default. In OpenLDAP it depends on the memberof overlay, and in 389 Directory Server on the MemberOf plugin. Confirm it is configured before relying on it. |
| member or uniqueMember (groupOfNames, groupOfUniqueNames) | Membership list read from the group object to build authentik group membership | Group objects store members as DNs, so the mapping depends on the group object class in your schema. Confirm which class your directory uses and whether nested groups are present. |
| cn on group objects | authentik group name, which should be unique within the source | Group names may collide across organizational units. Confirm uniqueness or plan a naming convention before the first sync. |
| Password hash attributes (userPassword) | Not mapped as a profile field. Stored hashes are handled by the source's password settings, not by property mappings | Hash schemes and whether the directory returns hashes to bind operations differ by server and configuration. Confirm the scheme and access control policy with your directory team before enabling local password storage. |
Choosing sync scope and password handling for each directory
OpenLDAP is the most common starting point for this topic, and the current releases are the feature release 2.7.1 and the long term support release 2.6.15. Which one your directory runs changes what you should expect from its configuration and upgrade cadence. Most production installations use the MDB backend, slapd's main database backend, which is built on LMDB. The backend matters for sync because the authentik LDAP source reads through standard LDAP queries, so scope and filters must match how the directory models people and groups.
- Base DN and filters: Confirm the organizational unit that holds people and the one that holds groups. Limit the sync scope to those branches rather than the whole tree.
- Group model: Confirm whether groups use
groupOfNames,groupOfUniqueNamesorposixGroup, and whether membership is stored on the group or on the user. - Password storage: Ask which hash scheme the directory uses for
userPassword, since the password backend must verify against it. - Release and upgrades: Ask whether the server runs 2.6.15 LTS or 2.7.1 and who owns upgrades.
- Update internal password on login: Leave this off until the directory owner agrees that storing a local hash in authentik is acceptable.
Confirm the sync scope, the group model and the password policy in writing with the directory owner before the source is configured.
389 Directory Server is an LDAPv3 server that supports asynchronous multi-supplier replication for fault tolerance and high write performance. Its schema, configuration and access controls can be changed online through LDAP operations, so the directory owner may adjust attributes while sync is running. Administration usually goes through dscreate to create instances, dsconf for configuration, which works locally or remotely, and dsidm for identity content such as users and groups. These tools shape how you ask the owner for the attributes and groups authentik needs.
- Replication topology: Ask which supplier receives the authentik bind and read traffic, and whether a failover supplier is planned.
- Attribute mapping: Confirm the attributes used for username, email and display name, as well as any custom schema added online.
- Group structure: Confirm whether groups are static or dynamic, because dynamic membership can change results between syncs.
- Access controls: Ask for a read-only bind account with ACIs limited to the sync branches, so authentik cannot modify the directory.
- Password backend: Confirm whether the server returns hashes that authentik can verify, and whether the directory owner allows local hash storage.
Ask the owner to share the dsconf output for the relevant suffix and the ACI list for the bind account before you finalize the sync scope.
Other LDAP directories, including commercial directories and custom builds, vary more in schema, group modeling and password handling than OpenLDAP or 389 Directory Server. Your work is mostly discovery. You need to learn how the server exposes users, groups and credentials before you set filters or property mappings. Because authentik creates and updates objects only inside authentik, every field you map must come from data the directory actually holds and is allowed to share.
- Schema discovery: Request the schema or a sample entry for one user and one group, then map each attribute to an authentik property.
- Nested or referenced groups: Confirm whether group membership is recursive or stored through references, since this affects how you read group structure.
- Password verification: Ask whether the server supports a simple bind for password checks and whether it stores hashes that can be validated over TLS.
- Transport security: Confirm that the server offers LDAPS or StartTLS and that the certificate chain is trusted by authentik.
- Operational limits: Ask about bind rate limits, paging and lockout policy, which can affect sync frequency and login behavior.
Write down the answers from the directory owner, including who approves schema changes, before you build the mappings.
Securing the directory bind, TLS and stored password hashes
An LDAP source gives authentik a standing connection to your directory, and that connection carries credentials, password material and user lifecycle decisions. The controls below cover who authentik binds as, how the connection is protected, where it can be reached from, how bind secrets are kept, what gets stored locally, and how removals in the directory reach authentik.
Read-only bind account
Create a dedicated service account in the directory with read access only to the user and group subtrees that the source's sync scope covers. Do not bind with an administrator account, because authentik only needs to read objects to import them. Confirm with your directory team which attributes the account can read, and test that it cannot modify entries. If your directory later needs writes from authentik, that requires custom automation, since the LDAP source does not create users in the external directory.
Encrypted transport with certificate validation
Protect the bind and every sync query with LDAPS or StartTLS, and make sure authentik validates the directory's certificate against your internal certificate authority rather than accepting any certificate. A bind over plain LDAP sends the account password and the password checks made at login across the network in a form anyone on the path can capture. Ask the directory team for the issuing CA chain, the certificate's subject name, and its renewal date, and confirm that the hostname in the source matches the certificate.
Network path limited to authentik
Allow the LDAP port only from the authentik server and worker containers, because the worker runs the scheduled sync and the server handles password checks at login. In a Kubernetes or Docker deployment, that means the egress address of the node or pod network, not a broad subnet. Review firewall rules on the directory side as well, and confirm which replica or load balancer address authentik connects to when the directory runs several servers.
Bind credentials kept as secrets
Store the bind password in your secrets system or in the deployment's secret store, not in a value typed into the admin interface or committed to a configuration repository. Limit who can read the authentik admin role that edits sources, since that role can see or change the bind settings. Plan a rotation step: change the directory password, update the source, run a sync, and confirm the sync succeeds before the old credential is removed.
Local hashes from Update internal password
The option Update internal password on login is off by default. When you turn it on, authentik stores a hash of the LDAP password locally each time a user logs in through the LDAP password backend. Decide this before go-live, because it moves a copy of password material into the authentik database, which PostgreSQL holds and your backups then carry. Document the choice, restrict database and backup access accordingly, and confirm with your security owner whether a local copy is acceptable.
Removals and disables in the directory
The LDAP source creates and updates objects in authentik only, so a user disabled or removed in the directory is not deleted in authentik by the source itself. Test what happens on your sync schedule with a disabled test account, and confirm how the disabled state is read from your directory's attributes. Define the process for offboarding, including revoking active sessions and any local password hash, rather than relying on a sync to finish that work.
What storing LDAP password hashes in authentik means for your audit
Leaving Update internal password on login off keeps the LDAP directory as the only place where password material lives. That setting is off by default. With it off, authentik checks each login against the LDAP server through the LDAP password backend and does not keep a copy of the password hash. The directory remains the system of record for credentials, so your existing password policy, lockout and offboarding controls on the directory continue to apply to every sign-in that passes through authentik. For most audits, this is the simpler position to explain because the credential store is unchanged from what the assessor already reviewed.
Turning the setting on creates a second credential store that you must govern. According to the authentik LDAP source documentation, when a user logs in through the LDAP password backend, authentik stores a hash of the LDAP password internally. From that point, a disabled or removed user in LDAP can still have a hash in authentik, so the offboarding runbook must disable the user in both places, and your access reviews must cover the authentik user record as well as the directory entry. Confirm with the authentik documentation how the stored hash is handled when a source user is deactivated or deleted in LDAP, and document the answer in your control narrative before enabling the option.
Before enabling it, ask the security and compliance owners to review four things: where the hash is held and who can reach the authentik database and backups, which password policy governs the stored hash compared with the directory, how credential changes made in the directory reach authentik, and whether the change is recorded in the system of record your auditor will sample. Ask your vendor or DeployOpen to confirm the hash scheme and the exact update behavior for your authentik version, and treat backups of the PostgreSQL database as in scope for the same controls.
Common LDAP sync failures in authentik and how to fix them
This table pairs common LDAP source failures with their likely causes and checks you can run yourself. Read it by symptom: find the row that matches what authentik shows, confirm the cause with the listed check, then apply the fix. Most sync problems trace back to the bind account, the search base, the certificate chain or the group schema.
| Failure | Likely cause | Check and fix |
|---|---|---|
| Bind failure or invalid credentials | The bind DN is wrong, the password is expired or the account lacks read access to the user and group subtrees | Test the bind DN and password with an LDAP client from the authentik host. Confirm the account can read the users and groups containers, then update the bind credentials on the source. |
| Sync finds zero users | The base DN points at the wrong container or the user search filter does not match the object class used in your directory | Browse the directory with an LDAP client using the same base DN and filter. Correct the base DN first, then adjust the filter until the expected entries return. |
| Certificate validation error on LDAPS | The directory certificate is not signed by a CA that authentik trusts, the hostname does not match the certificate or an intermediate certificate is missing | Check the certificate chain and subject name against the server hostname. Add the internal CA certificate to the certificate store authentik uses, then rerun the sync. |
| Groups or memberships missing | The membership attribute differs from what the source expects, such as member versus memberUid, or group objects sit outside the configured group base DN | Inspect one group entry and one user entry with an LDAP client. Confirm the attribute names and group base DN, then align the property mappings with what the server actually returns. |
| Users remain active after removal from the directory | authentik only creates or updates objects during sync, so deleted or disabled directory accounts are not automatically cleaned up by default | Confirm how the source handles missing accounts in its current settings. Compare an account deleted in the directory with its status in authentik, then disable it through a policy or a scheduled review if your process requires it. |
| Logins fail after enabling the internal password option | Users are checked against LDAP on first login, the stored hash is not refreshed as expected, or the LDAP password is changed while an old internal hash remains | Test a login with a known account and review the source's password backend settings. Confirm the LDAP password is correct, then reset the internal password for the affected user so the next login updates it. |
| Sync runs but attributes are empty | Property mappings reference attribute names that do not exist on your server or the schema differs from the default | Read a sample entry from the directory and list its attribute names. Update the property mappings to match those names exactly, then run a single-user sync to verify. |
What syncing OpenLDAP into authentik costs and requires from your team
What drives the effort of syncing OpenLDAP into authentik?
The main drivers are how your directory is structured, how many users and groups it holds, and how much of the existing login behavior you need to keep. Schema differences such as custom object classes, multi-valued attributes and non-standard group membership (member versus memberUid, or nested groups) change the property mappings you must write. Scope matters too: a sync limited to one base DN and a few groups is far smaller than a full tenant-wide import. Password handling adds work, because you must decide whether authentik validates passwords against LDAP and whether it stores local hashes. TLS setup, certificate trust and service account permissions are often the step that takes longest to get right in a corporate network. Ask any partner to review these items explicitly in the written scope.
Can our team set up the LDAP source without outside help?
Yes, a team with working knowledge of LDAP and authentik can build a basic LDAP source themselves, and the authentik LDAP source documentation covers the core configuration. The work that tends to need more experience is property mapping against an unfamiliar schema, validating which groups should sync, and testing login behavior across password policies. Teams usually weigh internal time against the risk of getting scope wrong in production, especially when the directory is shared with other systems. An outside partner is most useful for a fixed-scope review, mappings and test plan, or handover documentation. Either way, confirm who will own the source after go-live.
How long does an OpenLDAP to authentik sync project take?
Duration depends on directory size, schema complexity, the number of groups and applications that depend on them, and how many test cycles your change process requires. No fixed duration applies to every environment, so ask for a timeline that is tied to a written scope rather than a generic figure. A small directory with standard schema and a single sync scope is generally faster than a directory with nested groups, custom attributes and several consuming applications. Plan time for access approvals, certificate work and a parallel-run period where users can still sign in through the existing path. Ask the partner to list which phases depend on your team's responses.
What must our team provide before an LDAP sync engagement starts?
The team needs to supply the inputs that the design depends on, since guesses about the directory cause most rework. Typical items include:
- Read access for a dedicated bind account with the search base and scope confirmed in writing
- Schema documentation, including object classes, custom attributes and how group membership is stored
- A set of test accounts covering users, disabled users, and members of each group that matters
- The TLS approach, including the CA certificate that authentik must trust
- Written decisions on password validation and whether local hashes may be stored
Ask for the same list in the proposal so that you can check your own readiness before the work starts.
Does authentik create users in OpenLDAP when we add them in authentik?
No. The authentik LDAP source imports users and groups from the directory and creates or updates objects only inside authentik. Creating or changing users in OpenLDAP from authentik requires custom automation, which you would need to design, build, test and operate. If your joiner and leaver process depends on provisioning into the directory, budget for that automation as a separate workstream with its own security review. Confirm the direction of data flow in the design document before the build starts, because it determines where the system of record sits.
Does authentik store passwords from OpenLDAP locally?
By default it does not store them, but you can enable an option that stores a hash of the LDAP password in authentik when a user logs in through the LDAP password backend. The option named Update internal password on login is off by default, so the decision is explicit. Storing hashes affects your security review, retention rules and incident response, and it changes what happens if the directory password later changes or the account is disabled. Document the choice, confirm it with your security team, and test the path where a password changes in OpenLDAP outside authentik.
What recurs after an LDAP sync goes live?
Several activities recur after go-live, and they are usually larger in cost than the initial build. The sync must be monitored for failures, mappings must be revisited when directory schema or group structure changes, and authentik itself must be upgraded on a supported version. Authentik publishes security releases with at least 24 hours advance notice and lists 2026.5.x and 2026.8.x as the supported versions receiving security fixes, so plan a regular upgrade window and a test environment. OpenLDAP and your PostgreSQL database also need patching and backups on their own schedules. Ask for a support model that names who responds to sync failures and how changes are tested before they reach production.
Is authentik free to use with an LDAP source?
The authentik repository places most of its code under the MIT license, and the LDAP source is part of the open-source code base. Code in the authentik/enterprise/ directory is under a separate enterprise license, so check which features you rely on. The pricing page lists Open Source as free with community Discord support, while Enterprise adds features such as Microsoft Entra ID and Google Workspace integrations, mTLS, and enhanced audit logging. Confirm with the vendor that every feature in your design is available under the edition you choose, and ask any services partner to separate software licensing costs from implementation fees in the quote.
How DeployOpen scopes and delivers an authentik LDAP source
DeployOpen plans and implements the LDAP source in authentik inside your own infrastructure, from directory discovery through sync scope, property mappings and password handling. Engagements are fixed-scope, with the scope, deliverables and timeline agreed in writing before work starts.
How we scope
- We inventory the OpenLDAP, 389 Directory Server or other LDAP directory, its schema, base DNs and bind accounts.
- We define which OUs, user classes and groups sync into authentik and which stay out of scope.
- We agree in writing whether password validation against LDAP and local hash storage are part of the work.
How we build
- We configure the authentik LDAP source, property mappings and group handling in a non-production environment first.
- We test sync scope, attribute mapping and password login with representative test accounts before cutover.
- We document the source configuration, mappings and known limits, and confirm with your team how sync problems will be diagnosed.
How we hand over
- We deliver the configuration, mapping definitions, test results and runbook for your platform and directory teams.
- We walk your administrators through the sync schedule, the effect of removed directory entries and the lockout procedure.
- We confirm which items need customization, such as creating users in the directory from authentik, and record them as separate work.
How we support
- Ongoing support, upgrades and continuous testing for the authentik and directory setup are available as a retainer.
- We can review sync logs and mapping changes after each authentik release, following the upgrade guidance for your version.
- We recommend confirming vendor support terms for your directory server with its own maintainers before the retainer starts.
