How authentik keeps nested AD and LDAP groups intact
Directory groups in most organizations nest several levels deep, and application access often depends on membership in a group three or four levels down. The short answer is that authentik 2026.8 LDAP sources can preserve those nested hierarchies through the Sync Group Parents option, and since authentik 2025.12 a group can have multiple parents and inherits every permission granted to its ancestor groups. Together these two releases let a directory hierarchy arrive in authentik as a hierarchy rather than as a flat list of groups that someone must rebuild by hand.
The supported method is the built-in LDAP source, which reads group objects and their membership from Active Directory or another LDAP directory. Before you enable the option, confirm in your own environment that your directory exposes the group membership attributes your source expects, and check the exact option name and behavior in the authentik 2026.8 release notes. Run a sync against a test OU first so you can compare the parent relationships authentik creates with the nesting you see in your directory tools.
This page does not cover writing password changes or group changes back to the directory, which is a separate source feature with its own limits, and it does not cover Microsoft Entra ID, which is a different source type with its own group handling. It also does not describe how to design application policies for each group. Treat the parent relationships as the input to those decisions, and plan the policy review as a separate step once the hierarchy is in place and verified.
What you need before enabling Sync Group Parents
Sync Group Parents depends on the authentik version, the LDAP source configuration and the state of groups already in authentik. Work through these items in order before you change the source, because a wrong base DN or a stale group object is easier to fix before the first sync than after nested memberships have been written.
Confirm authentik 2026.8 or later
The Sync Group Parents option is part of authentik 2026.8, so the server and worker must both run that release or newer. Check the version on both containers before you edit the source. Read the 2026.8 release notes for any breaking changes, and follow the sequential upgrade rule if you are moving from an older release, since you cannot skip versions. Confirm the upgrade path with your own change process before you schedule it.
Scope the bind account
The LDAP source authenticates to the directory with a bind account. Give it read access to the user and group objects under the search base and to the attributes that describe group membership, and nothing more. Confirm with the directory team that this account can read the nested group objects that hold the parent references, since a bind account that sees only a subset of groups will produce a partial hierarchy without an obvious error.
Secure the connection with LDAPS
Plan LDAPS or another encrypted channel before the first sync, because the bind password and directory data cross the network. Confirm that authentik trusts the certificate chain of your domain controllers, including any internal certificate authority, and test the connection from the authentik worker's network segment, not only from an administrator workstation. Certificate trust failures are a common reason a source appears configured but never syncs.
Set the base DN and object classes
The base DN determines which part of the directory authentik can see, and the group object classes determine which entries count as groups. For Active Directory these are usually group objects, while OpenLDAP-style directories often use groupOfNames or posixGroup. Write down the base DN and object classes, then compare them with a sample of nested groups. If a parent group sits outside the base DN, its child will have no parent link in authentik.
Map existing group objects
Groups that already exist in authentik from earlier syncs, manual creation or another source can conflict with groups arriving from LDAP. Decide which source owns each group before you enable parent sync, and rename or merge duplicates in a controlled way. Record the current group list and the permissions attached to each group, so you can compare the results after the first sync and confirm that no inherited permission was granted by accident.
Confirm the directory layout with your team
The exact Active Directory forest, domain and domain controller setup varies by organization, and this page does not describe your environment. Ask your directory administrators to confirm the forest and domain structure, which domain controllers answer LDAP queries, and whether group nesting crosses domain boundaries. Treat their answers as the input to every other check on this list.
Configure the LDAP source and enable Sync Group Parents
This sequence creates an LDAP source in authentik, scopes group sync, turns on Sync Group Parents, and confirms that imported child groups point to their parents before any permissions depend on the hierarchy.
Confirm the directory prerequisites
Before touching authentik, the directory team confirms the service account used for binding, the base distinguished name that holds users and groups, and the LDAP endpoint authentik can reach from its server and worker containers. Ask the directory owner to confirm which group objects are nested under which parents, since that structure is what authentik will reproduce. Confirm that the authentik version in use is 2026.8 or later, because Sync Group Parents is available from that release. The step is done when the team has a written list of the bind account, base DN, group search base and the target authentik version.
Create the LDAP source in authentik
An administrator opens the Admin interface, goes to the Directory section, and creates a new LDAP source. The administrator enters the server URI, the bind account and password, and the base DN, then selects the property mappings that the deployment uses for users and groups. Save the source and run a connection test or a first manual sync if the interface offers one. The step is done when the source appears in the list as enabled and the connection test reports success without bind or certificate errors.
Set the group sync scope
On the same source, the administrator sets the group search base and group object filter so that only the directory groups intended for authentik are read. Limit the scope to the organizational units that hold the groups for applications, and exclude unrelated trees, because parent links can pull in ancestors outside the intended scope. Review the user sync scope separately so group membership resolves to users that authentik will actually create. The step is done when the scope is written down and matches the list agreed in the prerequisite step.
Enable Sync Group Parents
The administrator turns on the Sync Group Parents option on the LDAP source and saves the change. This setting tells authentik to read the parent relationships of each synced group rather than flattening the directory into standalone groups. Note the setting state in the change record, since a later sync without it will not rebuild the parent links. The step is done when the saved source shows Sync Group Parents enabled and a reviewer has confirmed the change in the record.
Run the initial sync
The administrator starts a full sync of the source from the Directory section and watches the sync task status and logs until it reports completion. Look for warnings about groups whose parent could not be found, which usually indicate a scope that excludes an ancestor or a group object filter that is too narrow. Resolve those warnings by adjusting the scope and running the sync again rather than editing groups by hand. The step is done when the task finishes without errors and the warning list is empty or explained in the change record.
Check the parent links for a child group
In the Directory section, the administrator opens a group that is known to be nested in the directory, such as a team group under a department group, and checks that its parent field lists the expected group. The reviewer repeats the check for a second-level group and for a group with more than one directory parent, if one exists, since multiple parents are supported from 2025.12. Compare each result with the directory structure from the prerequisite step. The step is done when every sampled child group lists the parent the directory shows, with any mismatch logged for follow-up.
Confirm inherited permissions before relying on the hierarchy
Because groups inherit permissions from their ancestors, the administrator tests one application or policy bound to a top-level group and signs in as a user who belongs only to a nested child group. The test confirms whether the access the user receives matches the design. Record the account, the group and the result. If the result does not match, correct the group structure in the directory and sync again, instead of granting access directly in authentik. The step is done when the test account gets the expected access and the result is recorded for the change review.
How directory group attributes map to authentik groups
This table compares how common directory group attributes and relationships translate into authentik group, parent and membership data during an LDAP or Active Directory sync. Read each row as a sync input, then confirm the matching authentik behavior in your version before you enable Sync Group Parents. The main takeaway is that nested access depends on both parent links and user membership syncing correctly.
| Directory concept | authentik result | What to verify |
|---|---|---|
| Group distinguished name (DN) | Identifies the source group during each sync run | Which attribute your source uses to match existing groups on re-sync |
| Group name | Becomes the authentik group name | Naming changes in the directory can create duplicate groups |
| member attribute on the group | Lists users and nested groups that belong to the group | Whether nested group DNs appear in member values on your directory server |
| memberOf attribute on the user | Lists groups a user belongs to, read during user sync | Whether your LDAP server exposes memberOf, since some servers do not |
| Nested group relationship | Creates parent links in authentik when Sync Group Parents is enabled (2026.8) | That parent links appear after a test sync in a non-production source |
| Direct user membership | Users listed in a group appear as direct members of that authentik group | Direct members in a test group match the directory membership exactly |
| Inherited access through ancestors | Members of child groups receive permissions from ancestor groups (2025.12 and later) | That the access granted through parents is intended and documented |
| Multiple parent groups | A child group can have more than one parent (2025.12 and later) | That multiply nested groups in Active Directory map to the expected authentik parents |
How permissions inherit from ancestor groups
Since authentik 2025.12, a group inherits all permissions from its ancestor groups, and a group can have more than one parent. When you sync nested LDAP or Active Directory groups with Sync Group Parents, those inherited permissions follow the directory hierarchy. A user who is a member of a small leaf group can therefore receive application access, admin roles or policy bindings that were granted to a group several levels above it. The effect is the same whether the grant was made in authentik by hand or arrived through the sync, so the directory structure becomes part of your authorization model.
The main risk is a broad parent group that grants more than its name suggests. In Active Directory, groups such as an organizational unit's all-staff group or a delegated administration group often sit near the top of the tree for reasons unrelated to application access. Once those groups become parents in authentik, every descendant inherits what they hold. Check each ancestor for application assignments, admin role membership and policy bindings, and confirm with the directory owners why each group is nested where it is. Also check the reverse case: a group that now has two parents may pick up grants from both branches, which can be broader than either branch intended.
Before go-live, run a review of every group that will receive parents from the sync. List the effective permissions of a sample of leaf-group members in a test instance, compare them with what the directory owners expect, and remove or move grants from ancestors that are too broad. Confirm the exact behavior for your authentik version in the authentik 2025.12 release notes and the authentik 2026.8 release notes before you rely on it, and repeat the review after any directory reorganization, because a moved group can change access without any change in authentik.
Checking custom policies against nested groups
Application access policies decide whether a user may open an application at all. They are bound to an application or provider and run each time a user starts a login. With nested groups, the question is whether the user's effective membership includes the group named in the policy. Confirm how your version reports membership before writing tests, because a user shown under a child group in the admin interface may or may not satisfy a policy bound to the parent.
- Choose one target per depth: Pick a leaf group, a middle group and a top-level group that a policy references, and create one test user who belongs only to the leaf.
- Expected allow: Users in the targeted group and in its descendants should be admitted if inheritance applies in your version (confirm this in the 2026.8 release notes).
- Expected deny: Users in a sibling branch or an unrelated top-level group should be refused with the policy message you configured.
- Binding order: Test with the policy bound alone, then with other bindings present, since an earlier denial can hide the result you are checking.
- Record for each test: the user, the directory group path, the application, the policy name, the result and the matching event log entry.
Check that the event log names the policy that produced each decision, so an auditor can trace an allow or deny back to a specific rule.
Expression policies evaluate a short expression against the request context and return a pass or fail. Group tests usually check whether a group name or identifier appears in the user's group data. The important detail is which groups that data contains: direct memberships only, or direct memberships plus inherited ancestors. Read the attribute your version exposes, then test the expression instead of assuming the answer.
- Write one membership test per policy: Keep each expression focused on a single group so that a failure points to one rule.
- Depth matrix: Run the expression for a leaf user, a middle-level user and a top-level user, and record whether each returns true for each targeted group.
- Expected results: A user in a descendant group should pass a check on an ancestor only if inheritance is active; a user elsewhere in the tree should fail.
- Name collisions: Create two groups with the same display name under different parents and confirm the expression matches the group you intended, since name-based checks can match the wrong object.
- Record: the expression text, the authentik version, the test user, the expected value, the observed value and any error output from the policy.
Repeat the full matrix after each sync and after any upgrade, because a change in how group data is loaded can change expression results without any edit to the policy.
Flow policies control whether a stage in a login, enrollment or recovery flow runs. A group-based flow policy can, for example, allow enrollment only for members of a branch of the directory, or require an extra stage for a privileged group. Because flows execute in order, membership may not be fully known at the first stage, so the position of the policy in the flow determines what it can check. Confirm stage order before you design the test.
- Map the flow: List each stage in order and note where the group-based policy is bound, so each test records the stage that did or did not appear.
- Depth tests: Log in with a leaf user, a middle-level user and a top-level user, and note whether the gated stage appears for each.
- Expected allow: Users within the permitted branch should reach the gated stage and complete it.
- Expected deny: Users outside the branch should see the denial message, or the stage should be skipped in the way you specified.
- Record: the flow slug, the stage order, the binding order, the user, whether the stage was shown and the final outcome of the flow.
Run the flow as a new test user after every change to bindings, because flow policies apply to sessions that start after the change and cached sessions can hide an error.
The three policy types share one test matrix, so the evidence can be reviewed in one place. Each row in the matrix combines a policy, a test user, a depth level, an expected result and an observed result. A matrix like this is useful to your security team, to the platform team who maintains the sync and to any assessor who asks how group-based access was verified. The matrix should be kept with the change record for the directory sync.
- Build one row per combination: Cover each policy type against each depth level, including at least one negative case per policy.
- Use dedicated test accounts: Keep test users in a test group that carries no production entitlements, and document who can change their membership.
- Capture the sync state: Record the sync time, the directory source, the group parent settings and the authentik version, since any of these can change the result.
- Define pass criteria: Mark a row as passed only when the observed result matches the expected result and the event log shows the policy that decided it.
- Retest on change: Rerun the matrix after an upgrade, a change to Sync Group Parents, a directory restructure or any edit to a bound policy.
Ask your authentik contact or the release notes for the exact upgrade and sync behavior in your version, then store the signed-off matrix with your access review evidence.
Securing the LDAP bind account and sync scope
A group sync reads a directory on behalf of a bind account, and the scope of that account and of the base DN decides what authentik can see and what it can change. The cards below cover the controls that keep the nested group hierarchy accurate without giving the sync more reach than it needs.
Least-privilege bind account
Create a dedicated service account in the directory whose only job is reading users and groups. It should have read access to the objects the sync needs and no rights to modify users, group membership or password attributes. Confirm with your directory team that the account cannot write to the group objects whose parents authentik will read, since a sync that can edit the hierarchy can also corrupt it at the source.
Restricting the sync base DN
Point the LDAP source at the narrowest base DN that contains every group in the hierarchy you intend to preserve. A parent group outside the base DN cannot be resolved, so the child relationship is lost, while an overly broad base DN pulls in service and administrative groups you did not plan to expose. Test the chosen base DN against a copy of the tree before enabling it in production.
Using LDAPS for the bind
Bind over LDAPS or StartTLS so the bind credential and directory data are not sent in clear text across the network. Verify that authentik trusts the certificate chain of your domain controllers, including any internal certificate authority, before enabling the source. Certificate errors are a common reason a sync stops, and they are easier to diagnose before the schedule is live.
Protecting the bind credential
Store the bind password in a secrets mechanism your platform team controls rather than in a shared configuration file or a ticket. Limit who can read it, rotate it on a schedule your directory policy requires, and plan the rotation so the sync is updated in the same change window. Ask your team to confirm how the credential is exposed in the authentik configuration and in backups of the database.
Limiting who changes group parents
Parent relationships in authentik determine inherited permissions, so editing them is a privileged action. Restrict the admin roles that can modify groups, and keep manual parent changes to a small set of named administrators. Where a parent link is maintained by the directory, changes made by hand in authentik can be overwritten on the next sync, so agree on one owner for each relationship.
Auditing permission changes
Record who changed group parents, group membership and application access, and when. Enhanced audit logging is listed among authentik's enterprise features on its pricing page, so confirm with the vendor or your account contact whether the edition you plan to run includes it and what the open-source edition logs by default. If the open-source logging is not enough for your review process, plan an external log pipeline before go-live.
Why nested groups do not appear or grant access
This table lists the failures teams most often hit when mirroring nested LDAP or Active Directory groups into authentik, with the likely cause and the fix for each. Read it as a checklist after a sync that shows flat groups, missing members or unexpected access. Most problems trace back to one setting, the scope of the sync, or policies that only look at direct membership.
| Symptom | Likely cause | Fix |
|---|---|---|
| Groups appear flat, with no parent relationships | Sync Group Parents is not enabled on the LDAP source, so hierarchy is not carried over (available from authentik 2026.8) | Enable Sync Group Parents on the source, run a sync, then confirm parent links on a sample nested group |
| Parent groups are missing from authentik | The parent group sits outside the sync scope, such as a different base DN or filter, so the link has no target | Widen the group search base or filter to include the ancestor groups, then re-sync |
| Circular nesting causes odd or incomplete results | Group A contains B and B contains A, often from legacy nesting in Active Directory | Find the loop with a directory query, remove one membership in the directory, then re-sync |
| Users lose or gain group membership after directory changes | Membership is refreshed on sync runs, so changes made between runs are stale until the next run | Set the sync schedule to match how often groups change, and verify membership after a known directory change |
| Users receive permissions they did not expect | Since authentik 2025.12, groups inherit all permissions from ancestor groups, so a broad parent grants access to every child member | Review permissions on top-level and intermediate groups before enabling the sync, and remove grants that should stay local |
| Access policy denies users who are clearly in the right group | The policy checks only direct membership, so users who inherit through a parent group are not matched | Rewrite the policy to evaluate the effective group set, and test it with a user who is a member only through a parent |
| Policy allows access that it should block | A policy written for a leaf group is reused on a parent, or a deny rule is bypassed by inheritance | Test each policy against a leaf member and an ancestor member, and confirm the expected outcome in both cases |
Questions teams ask before syncing nested groups
What does it cost to sync nested LDAP groups into authentik?
No price is published for this work, and the total depends on the scope agreed in writing before work starts. The main cost drivers are the size of the directory, the number of nesting levels that must be preserved, the number of custom policies that read group membership, and how much testing you require. A larger directory with deep nesting and several policies takes more build and test time than a flat directory with one policy. Ask any partner, including DeployOpen, for a quote that lists the directory scope, the policies in scope, the test cases and who performs each step. Your own cost is mainly staff time from directory and application owners. Authentik itself is free to self-host under the Open Source edition, so the license is not usually the main cost of this topic.
How long does nested group sync take to set up and verify?
The duration depends on directory size and test coverage, and no fixed timeline applies to every environment. A small directory with a few nesting levels and a short list of applications can be checked quickly. A large Active Directory forest with many nested groups, group-based application access and custom policies needs more time to map parents, confirm inherited permissions and test edge cases such as users who belong to several parent groups. Schedule time for a test sync in a non-production instance, a review of results with the owners of each application, and a repeat sync after any change to the source. Ask for the expected stages and what each one depends on, rather than a single number.
What access and people do we need before the work starts?
You need four things before work starts: directory administrator access or a delegated account that can read the group objects you plan to sync, a bind account in authentik's LDAP source with read permission on users and groups, a set of test users who represent your real group structures, and a named owner who decides how parent groups should grant access. The owner must approve which permissions flow down from ancestor groups, because from authentik 2025.12 groups can inherit all permissions from their ancestors. Without that decision, a user placed under a broad parent group could gain access to applications you did not intend. Confirm these items with your directory team early, since account requests often take the longest.
Can our own team sync nested groups without a partner?
Yes, a team with directory and authentik experience can do this internally, provided it has time to test. The configuration itself is an LDAP source setting, and authentik 2026.8 added the Sync Group Parents option to preserve nested hierarchies. The harder part is deciding which parent groups should grant which permissions and proving that inherited access is correct across your applications. Teams that run this internally usually build a test user set, document each group's intended access and review the results with application owners before enabling the sync for all users. A partner can take on that design and verification work under a written scope if your team lacks the time or the directory knowledge.
Does the Open Source edition of authentik include LDAP sync?
LDAP sources are part of authentik's provider and source functionality, and the Open Source edition is free to self-host under the MIT license for most of the code. Confirm the exact feature availability for your version in the release notes before you plan, because the Sync Group Parents option is introduced in authentik 2026.8 and multi-parent groups with inherited permissions arrive in 2025.12. The enterprise features on the pricing page include Microsoft Entra ID and Google Workspace integrations, mTLS, and enhanced audit logging, which are separate from LDAP sync. Confirm the licensing position with authentik and your own counsel before you commit.
Which authentik version do we need for nested group sync?
Sync Group Parents for LDAP sources requires authentik 2026.8 or later, and inherited permissions from ancestor groups depend on the multi-parent group model introduced in 2025.12. Plan your upgrade path before you begin, since authentik upgrades must follow the sequential rule documented for the project. Check the security policy to confirm your target version is still receiving security fixes, and confirm the current release on the GitHub releases page before you schedule the change.
What should we test before enabling nested group sync for all users?
Test the cases that break most often in nested directories, not only the happy path. Include a user who sits under two parent groups, a group nested several levels below an application group, a group removed from its parent in the directory, and a user whose access should be denied despite membership in a child group. Check each custom policy that reads group membership against the expected result. Record the expected and actual access for each case, have the application owner sign off, and repeat the test after every directory change that touches group structure.
How DeployOpen scopes and delivers nested group sync
DeployOpen scopes nested group sync in writing before any configuration changes. The scope document names the directory sources in play, the authentik version the deployment will run, and the applications whose access depends on group membership. It also records which group hierarchy the work must preserve, which groups are authoritative in Active Directory or LDAP, and which decisions stay with your team, such as whether authentik may write to the directory. Because the Sync Group Parents option arrived in authentik 2026.8, the scope should confirm the target release against the authentik 2026.8 release notes and the security policy's list of supported versions before the build starts. Fixed-scope delivery means the deliverables and timelines are agreed up front, so the sign-off criteria are known before any sync runs.
The review phase reads the directory and the policy estate together. For the directory, that means mapping which group nesting levels carry meaning, which groups are used only for mail or other non-access purposes, and whether any group has multiple parents that will now inherit permissions. For authentik, it means listing every custom policy, binding and application that evaluates group membership, and checking how each one behaves once ancestor permissions are inherited. Expect that to surface policies written on the assumption that membership was flat. Testing runs against a non-production authentik instance with a representative subset of groups and test accounts, and each finding is logged with an owner and a disposition. Your team should confirm the lab sync scope, service account rights and any change windows before testing starts.
Handover covers the configuration as code or documented settings, the test evidence, a runbook for re-running the sync after a directory change, and a short list of monitoring points for sync errors. Retainers are available for ongoing work after handover, such as upgrading authentik across releases, reviewing new directory groups, and re-running access tests when policies change. The retainer scope, response expectations and any SLA are agreed in writing, and nothing in this section should be read as a commitment to a specific response time. To compare quotes from DeployOpen or other partners, ask each for a written scope that lists the directory sources, the authentik version, the policy review method, the test cases and the handover artifacts.
