Learn Authentik - LDAP & Active Directory Source

#Introduction

In episode 16, Authentik trusted cloud identity providers through OAuth sources. Episode 17 covers a source closer to the enterprise world: the LDAP source, which imports users and groups from an existing directory — OpenLDAP, FreeIPA, or Active Directory (AD) — into Authentik.

Why synchronize? Organizations that already have AD don't want to move 500 users into the Authentik database manually. With an LDAP source, Authentik becomes an LDAP client: it periodically reads users and groups from the directory, creates internal users, and uses that data for login and policies. The directory remains the source of truth.

Analogy: you don't photocopy the entire employee archive into a new book. You build an automatic bridge that copies data from the old archive into the new system, then updates the copy on a schedule.

#Basic LDAP Source Configuration

In the Admin interface, open Directory → Federation and Social login → Create → LDAP Source. Core fields:

Field	OpenLDAP example	Active Directory example
Server URI	`ldaps://ldap.example.com`	`ldaps://dc1.ad.example.com`
Bind CN	`cn=admin,dc=example,dc=com`	`CN=svc-authentik,CN=Users,DC=ad,DC=example,DC=com`
Base DN	`dc=example,dc=com`	`DC=ad,DC=example,DC=com`
User object filter	`(objectClass=person)`	`(objectClass=user)`
Group object filter	`(objectClass=groupOfNames)`	`(objectClass=group)`

Server URI — the directory address; must be ldaps:// (port 636) or ldap:// with StartTLS for credential data. Several servers can be separated by commas for redundancy.
Bind CN and Bind password — the service account allowed to read the directory. Use a dedicated service account with minimal read rights, not a domain administrator account.
Base DN — the starting point of the search. Additional User DN and Additional Group DN deepen the search without changing the base DN.
Filters — determine which objects count as users and groups. Filters determine the sync scope: too broad a filter imports unwanted objects, too narrow a filter misses legitimate users.

Important

Make ldaps:// the standard. Passwords — even though Authentik never reads them (what's synchronized are hashes) — are still sensitive data that must not travel over an open channel. For AD, make sure LDAPS is active on port 636 before configuring the source.

#Mapping LDAP Attributes to Authentik

Users and groups from LDAP are mapped to Authentik properties via property mappings. Common built-in mappings:

Username — from the uid attribute (OpenLDAP) or sAMAccountName (AD).
Email — from the mail attribute.
Name — from the displayName or cn attribute.
Path — from the DN, for example goauthentik.io/sources/ldap.

Built-in mappings are enough for most cases. For special needs, create a custom mapping. The available context is ldap (the raw attribute dictionary) and dn (the object's distinguished name). Example combining two attributes:

Note the use of list_flatten — many LDAP attributes are lists, and this helper takes the single element. Expressions returning None are skipped.

#Sync Schedule

Synchronization runs automatically through Authentik's task system, by default every two hours (and once when the source is saved). Options you can set:

Sync users — user synchronization; Sync groups — group synchronization.
Sync users password — copies the password hash from LDAP. Only one source may enable it; without this option, login to Authentik still works for source users because it uses LDAP credentials during verification.
Parent Group — the parent group in Authentik for all imported groups.
lookup_groups_from_user — looks up group membership from attributes on the user (for example memberOf) instead of from the group. Required to handle nested groups in AD and FreeIPA.
delete_not_found_objects — deletes Authentik users/groups that no longer exist in the directory. Enable it only after you're sure the filters are correct, because the impact is account deletion.

Manual sync can be triggered from the Sync tab on the source, or via the worker command:

Run synchronization in the foreground

docker compose run --rm worker ldap_sync ldap-ad

And to check connectivity to the LDAP server:

Check the LDAP source connection

docker compose run --rm worker ldap_check_connection ldap-ad

Run these commands when troubleshooting: ldap_check_connection separates connection problems from synchronization problems, and ldap_sync in the foreground shows errors directly in the console.

#Using Active Directory Groups

After synchronization, AD groups appear as Authentik groups. Group membership can be used directly in policies (episode 6): grant an application access only to the DC-administrators group, enforce mandatory MFA for the staff group, and so on.

Two things to watch for with AD:

Nested groups — AD groups can contain other groups. Enable lookup_groups_from_user and set the group membership field to memberOf so indirect membership is correctly resolved.
Uniqueness field — AD uses objectSid as the stable identifier. Make sure this field is consistent; a changing identifier makes Authentik treat the user as a new entity.

#Troubleshooting Synchronization

When the import doesn't behave as expected, split the problem into two layers: connection and data.

Connection failed — run ldap_check_connection (example above). Common causes: untrusted server certificate, LDAPS port blocked by a firewall, or a bind account without read rights.
Users not imported — check the filters and base DN. Test the filter with a tool like ldapsearch against the same base DN; if that query doesn't return the expected objects, the source configuration won't either.
Passwords not synchronized — make sure the Sync users password option is enabled and only one source enables it.
Synchronization duplicates users — check the uniqueness field (for AD, objectSid). An unstable identifier makes Authentik treat the same user as a new entity on every sync.

The worker task log is the primary diagnosis source — sync tasks write the details of every created, changed, or deleted object, complete with execution timestamps.

#Difference from the LDAP Outpost

The term "LDAP" appears in Authentik in two places with opposite roles. Don't mix them up:

Aspect	LDAP Source	LDAP Outpost (provider)
Data direction	Directory → Authentik	Authentik → LDAP application
Authentik's role	LDAP client (reads)	LDAP server (serves)
Purpose	Import existing users/groups	Let legacy applications log in with LDAP
Example	Company's existing OpenLDAP/AD	Old apps that only understand the LDAP protocol

An LDAP source copies a directory into Authentik (one direction). An LDAP outpost does the opposite: Authentik presents its internal users as an LDAP server so legacy applications can bind. Episode 18 covers the LDAP outpost thoroughly.

Tip

If you already have a well-managed directory (AD or OpenLDAP), the LDAP source is the right choice — one source of truth, with Authentik as its consumer. If what you have is a legacy application that can only speak LDAP, you need an LDAP outpost. Both can be used together: the source for import, the outpost for service.

#Closing

This episode configured the LDAP source: understanding the server URI, bind DN, base DN and filter fields for both OpenLDAP and Active Directory, mapping attributes via property mappings with the ldap and dn context, setting the schedule and sync options, using AD groups for policies, and distinguishing the LDAP source from the LDAP outpost.

The key: the directory remains the source of truth, and Authentik copies it periodically — not the other way around. In episode 18, we reverse the direction with the LDAP outpost provider: Authentik acting as an LDAP server for legacy applications. See you there!