How Keycloak federates LDAP and Active Directory users
Keycloak can read users from LDAP or Active Directory through its user federation provider, so employees keep their existing directory accounts and passwords for sign-in to applications in a Keycloak realm. The directory stays the place where people are created, disabled and grouped, while Keycloak becomes the component that issues tokens to applications. Identity teams should treat this as a design exercise with several separate decisions, not as a single checkbox in the admin console. The work is harder than it looks because each part of the federation has its own rules. Attribute mappers decide which directory fields become Keycloak user attributes, and a mismatch in a single field such as the username or email attribute can lock out whole populations. Password validation is a separate choice: Keycloak can validate credentials by binding to the directory, which keeps passwords in one place, or it can store or import hashes, and each option changes what happens when a password is changed or an account is locked. Group semantics also differ, because directory groups, nested groups and Keycloak roles and groups do not map one to one without explicit group and role mappers. Deprovisioning and Kerberos sign-in add further decisions about what happens to sessions and tokens when a user leaves, and whether integrated Windows authentication is needed at all. The Keycloak server administration guide documents LDAP and Active Directory user federation, along with Kerberos federation, and it is the primary reference for the settings described here. Before a build, confirm the release line against the upgrade notes. The current release is 26.8.1, and the 26.8 upgrade notes include changes that affect operators, such as enforced SMTP StartTLS and mandatory validation of backchannel logout tokens from external providers. Those notes should be read against the version you intend to deploy. A useful first step is to write down, for each attribute, group and credential type, which system is authoritative and what should happen when that system changes. Ask the directory team for a read-only service account, a list of the attributes applications need, and the naming of the groups that represent application access. Test with a copy of the directory or a representative test organizational unit, and confirm how disabled accounts, password resets and group removals appear in Keycloak before any production users are federated.
Which Keycloak components carry directory federation
Directory federation in Keycloak is not one setting but a set of linked objects inside a realm. Each one controls a different part of how users, groups and credentials move from LDAP or Active Directory into Keycloak, and a fault in any of them shows up as a sign-in or sync problem that looks like something else.
User storage provider for LDAP or Active Directory
This is the realm-level component that tells Keycloak a directory exists and how to reach it. In the admin console it sits under the realm's user federation settings, where you choose the LDAP or Active Directory provider and set the edit mode, which determines whether Keycloak is read-only, writable, or unsynced. Confirm the edit mode with your identity team before anything else, because it decides what Keycloak may change in the directory.
Connection and search settings
These fields hold the connection URL, bind account, TLS or StartTLS choice, and the users DN and search filter that bound Keycloak's view of the directory. Errors here usually surface as failed test connections or users that never appear. Ask your directory team for a service account with the least rights needed to read the search base, and confirm the certificate chain Keycloak will trust.
User attribute mappers
Attribute mappers translate directory attributes such as mail, displayName or employee identifiers into Keycloak user profile fields. They sit on the provider's mappers tab and decide which values Keycloak trusts as identity data. Map only the attributes your applications need, and check which attribute is treated as the unique username, since a mismatch here creates duplicate accounts after go-live.
Group and role mappers
Group and role mappers copy directory group membership into Keycloak groups or client roles, which applications then read in tokens. They are configured on the same mappers tab and are often the source of access decisions, so they carry more risk than attribute mappers. Test them with real users from each group, and confirm nested group handling against what your applications expect.
Synchronization settings
Synchronization controls whether Keycloak imports users in bulk, refreshes them on a schedule, and removes accounts that no longer exist in the directory. These settings are found on the provider's settings page and determine how quickly a leaver loses access and how much load the directory carries during sync. Decide the sync schedule and removal behavior in writing before enabling them in production.
Kerberos provider for integrated sign-in
The Kerberos provider is a separate realm component that lets users with an existing Windows or domain session sign in without typing a password. It requires a service principal, a keytab file and correct DNS and browser configuration, and it is configured apart from the LDAP provider even though both rely on the same directory. Confirm the keytab handling and rotation process with your Active Directory administrators.
Read-only, imported or writable: which federation mode fits
This table compares the three ways Keycloak can federate LDAP or Active Directory users: read-only, imported with local copies, and writable. Read each row against your directory ownership model, because the operational cost of each mode follows from who is allowed to change users, passwords and attributes. Confirm the exact import, sync and write-back settings in the server administration guide for the Keycloak version you deploy.
| Decision point | Read-only federation | Imported users (sync) | Writable federation |
|---|---|---|---|
| When it fits | The directory is the single source of truth and no application needs Keycloak to change user records | Directory stays authoritative but applications need local user IDs, Keycloak-only attributes or sessions that survive directory outages | Keycloak must create, update or reset users in the directory, for example for self-service password change or onboarding |
| Who owns password changes | The directory team, through its own tools or helpdesk process | The directory team, with Keycloak validating credentials against the directory at sign-in | Shared or delegated, so the password change path and its policy must be designed and tested explicitly |
| Users removed from the directory | Sign-in fails at the next authentication because the directory no longer returns the user | Depends on the removal and sync settings, so confirm whether the local copy is disabled or deleted at the next synchronization | Removal is usually driven from the directory side, so confirm how deletions propagate and whether local records are kept |
| Bind account permissions | Read access to the user search base and the attributes Keycloak maps | Read access plus whatever is needed for synchronization queries, which should still avoid write rights | Write rights on the attributes or objects Keycloak may change, scoped to specific containers and attributes only |
| Keycloak-only attributes | Not stored with the user record in the directory, so they must live in Keycloak's local user store and are lost if the realm is rebuilt without a backup | Stored in the local copy and kept across sync cycles, which needs a plan for conflicts with directory changes | Can be written back to the directory where the schema allows, but extra attributes add schema change requests to the directory team |
| Sync frequency trade-off | Not applicable for authentication, but group and role mapper caching still needs a refresh policy | Shorter intervals reduce stale attributes and deprovisioning lag but increase directory query load; longer intervals do the reverse | Write-back timing should be tested so a password or attribute change is visible in both systems in the order your users expect |
| Directory outage behavior | Users cannot sign in while the directory is unreachable, unless another credential path is provided | Existing local copies may allow some lookups, but password validation still depends on the directory, so confirm the cached behavior for your version | Same dependency as read-only for sign-in, plus a failure mode where write-back queues or fails silently, so monitor write errors |
| Settings to confirm in the admin guide | Edit mode, search and bind settings, attribute mappers and the cache policy for the chosen Keycloak version | Import settings, synchronization schedule options, removal handling and how local attributes are retained | Edit mode values, password update behavior, write permissions required by the bind account and any attribute mapper write options |
Keeping Active Directory as the source of truth
When Keycloak federates users from Active Directory, the directory should own identity data. Account creation, disablement, password ownership and changes to core attributes such as name, email, department and manager should originate in Active Directory and reach Keycloak through the federation provider's synchronization and authentication paths. Keycloak should hold only the data that belongs to it: sessions, consents, local realm roles, client-specific attributes and credentials that Keycloak itself issues, such as OTP or WebAuthn registrations. Keeping those two categories separate is the foundation for everything else in this section, because it determines which system an administrator should change when something is wrong.
The failure mode to plan for is silent drift. Keycloak's administration console allows administrators to edit federated user attributes, and in some configurations those edits are stored locally rather than written back to the directory. Over time, the value shown in Keycloak no longer matches Active Directory, and the discrepancy is only noticed when a token claim is wrong or an access decision fails. Prevent this with a written ownership list that names, for each attribute and each function, the system of record and the team allowed to change it. Include at least username, email, enabled state, password, group membership, and every attribute mapped into tokens. Review the list whenever a mapper is added, and treat any attribute without a named owner as a gap to close before go-live.
Revocation is the control most often assumed rather than tested. Before go-live, disable a dedicated test account in Active Directory and confirm that Keycloak blocks sign-in after the next synchronization or authentication attempt, depending on how the federation provider is configured. Then confirm that existing sessions and refresh tokens for that user are handled as your policy requires, since access may persist until token lifetimes expire unless sessions are ended. Repeat the test for a group-based removal, because group membership changes often follow a different path than account disablement. Record the results as evidence for your access review.
The exact behavior depends on the chosen mode and settings. A read-only provider, a writable provider, and a provider with import and periodic synchronization each handle disablement, password checks and attribute refresh differently, and the synchronization interval and cache settings affect how quickly changes appear. Confirm these behaviors with your own Keycloak version and the current Keycloak server administration guide before writing the ownership list, rather than relying on this summary. Ask your implementation partner to include the revocation test and the ownership list as named deliverables in the written scope.
How to configure Active Directory federation step by step
This sequence takes a team from an unconfigured Keycloak realm to a working LDAP or Active Directory user federation, proven first in a non-production realm with a test user, a disabled account and a counted user import.
Confirm directory reachability and bind account
Your directory administrator creates a dedicated bind account with read access only to the user objects and attributes Keycloak needs, and no rights to change directory data. From a host that will run Keycloak, confirm that the directory controllers resolve by name and that the LDAP port and the LDAPS port respond on the network path your firewall rules allow. Confirm that the bind account can authenticate and search the intended base. Done when a simple bind and a test search from that host succeed and return the expected user entries, and a deliberately wrong password is refused.
Enable LDAP over TLS before any sign-in
Before Keycloak sends the bind password or any user credential, configure the directory to accept TLS connections and confirm that the certificate chain is trusted by the Keycloak server's truststore. Test the encrypted connection from the Keycloak host using the directory's hostname, because certificate name mismatches are a common cause of failure. Treat plaintext LDAP as unacceptable for production sign-in. Done when a TLS handshake to the directory completes with a verified certificate and the bind account authenticates over that encrypted channel.
Create a non-production test realm
Create a separate test realm in your Keycloak environment so that federation settings, mappers and sync behavior can be validated without touching the realm that serves production applications. Keep the realm's clients limited to a test application that you control. Record the realm name and the environment it belongs to in your change record. Done when the test realm exists, is separate from production, and an administrator can log in to its admin context without affecting other realms.
Add the LDAP or Active Directory provider
In the test realm's user federation settings, add an LDAP provider and select the vendor type that matches your directory, such as Active Directory or a generic LDAP directory. Enter the connection URL using the TLS endpoint, the bind DN and the bind credential, and the users DN as the search base. Use the connection test and authentication test buttons in the provider form to confirm both steps before saving. Done when both tests report success on the saved provider and the provider appears in the realm's user federation list.
Set search base and user object filters
Narrow the users DN and the custom user search filter so that only the intended population is visible to Keycloak, for example a specific organizational unit or a group of accounts. Confirm the username attribute, the RDN attribute and the UUID attribute that your directory uses for stable identity. Choose the edit mode deliberately: read-only keeps the directory as the source of truth, while writable modes allow Keycloak to change directory data and require explicit approval from your directory owners. Done when a search with the filter returns only the expected users and the chosen edit mode is recorded for the change review.
Map attributes and test sign-in with real accounts
Configure the user attribute mappers that copy email, first name, last name and any other required attributes from the directory into Keycloak user profiles, and note which attributes are read-only in the chosen mode. Then sign in to the test application with an enabled test user and confirm that the user's profile fields are populated. Next, disable a test account in the directory, wait for the next authentication or sync, and confirm that Keycloak refuses sign-in for that account. Done when the enabled user signs in successfully and the disabled account is refused with no local password fallback.
Run a user synchronization and check imported counts
Trigger a full user synchronization from the provider page and then a changed-users synchronization, and review the reported counts of added, updated, removed and failed users. Compare the added count with the number of accounts your directory query returns for the filtered base, and investigate any gap, such as accounts outside the search base or accounts missing a required attribute. Confirm that the sync result for a deleted or disabled test account matches what you expect. Done when the counts reconcile with the directory query and you have a written record of the sync outcome to compare against in production.
Repeat in production after a validated test
Only after the test realm passes every check above, apply the same provider settings, filters, mappers and edit mode to the production realm through your normal change process, with the bind account, TLS configuration and filters reviewed by your directory owners. Run the connection and authentication tests again, sign in with one enabled test user, and repeat the synchronization count check. Keep the test realm as a reference for future changes. Done when production shows the same test results and counts as the validated test realm.
Mapping directory groups and roles without copying the tree
The group and role mappers decide what the directory's structure means inside Keycloak, and they are the place where a federation project most often grants more access than anyone intended. Before enabling any mapper, decide which directory groups should become Keycloak groups at all. Most organizations need only a small set, such as the groups that govern application access, and copying the whole directory tree creates a second, drifting hierarchy that nobody owns. Keep the mapping list short, name each mapper for the directory group it reads, and record who approves changes to it.
Nested groups need a deliberate choice. Keycloak can represent the directory's hierarchy or flatten it so that a membership in a child group is treated as a membership in the parent group, and the exact behavior depends on the mapper settings and the version in use. Do not rely on memory or on a forum answer for this. Confirm how nested group membership is read, whether membership is inherited upward or downward, and how the directory's own primary group attribute is handled, in the Keycloak server administration guide for your version. Then write down the expected result for each group you plan to map.
Each directory group can be mapped to a realm role or a client role. Realm roles are visible across every client in the realm, so a broad realm role mapped from a large directory group can reach applications its members should never touch. Client roles keep the grant inside one application and are usually safer for line-of-business access. For a small, stable set of administrative permissions, a hardcoded role assigned directly to a user or group in Keycloak can be safer than a mapped role, because the grant no longer depends on the directory staying exactly as it is. The trade-off is that the grant is no longer managed in the directory, so the administrator who assigns it becomes responsible for reviewing it.
The largest risk is a broad mapping that grants an administrative role by accident. A common pattern is a group with a generic name, such as one used for a helpdesk or a legacy application, that quietly contains members from another team. Limit the group search base to the organizational units that actually hold Keycloak-relevant groups, so that the mapper cannot see groups elsewhere in the forest. Exclude or avoid mapping any group that carries directory administration privileges. Renaming a directory group also has an operational effect: the mapper matches on the group's identifier or name, so a rename can silently stop a grant from applying or, if a new group reuses the old name, start applying one to the wrong people.
Before rollout, test a real user from each mapped group and from several groups that should not grant access. Check the resulting Keycloak groups, realm roles and client roles in the admin console, then check the tokens the application receives. Repeat the test after a directory change, such as a rename or a move between organizational units, because that is when grants change without anyone reviewing them. Ask the team that owns the directory for a list of groups with administrative rights, and keep that list with the mapper configuration so that reviews can compare the two.
What drives Active Directory federation effort and cost
This table lists the factors that raise or lower the work of federating LDAP or Active Directory users into Keycloak, with a way to reduce each one. Read each row as a lever: the cost is the internal and partner time spent on that driver, and a written scope sets the final quote.
| Driver | Why it moves effort or cost | How to keep it down |
|---|---|---|
| Number of directories, domains and forests | Each directory needs its own connection, bind account, search base, certificate trust and mapper set, and cross-forest trust adds testing. | Confirm the directory count in discovery, federate only the forests that hold users who sign in, and document each connection separately. |
| Realms and clients that consume federated users | Every realm that imports or brokers the same directory repeats mapper, role and client configuration, and each client adds token and claim testing. | Use one realm pattern consistently, share client scope and mapper definitions, and keep the number of realms that read the directory small. |
| Quality of directory data | Duplicate accounts, stale or disabled users, and inconsistent attributes such as mail or employee ID cause import errors, wrong links and manual cleanup. | Clean the directory before the first import, agree on the authoritative attribute for username and email, and remove stale accounts from the search base. |
| Group model complexity | Nested groups, dynamic groups and group-to-role mappings need translation into Keycloak groups and roles, and each rule needs its own verification. | Simplify the group model before federation, map only the groups that grant application access, and avoid mirroring every directory group. |
| Write-back requirements | Writable mode lets Keycloak change directory objects, which adds service account permissions, change conflict handling and a security review. | Start in read-only mode unless a named process needs writes, and document each attribute that Keycloak may change. |
| Kerberos scope | Kerberos sign-in needs a service principal, keytab handling, DNS and time synchronization, and browser configuration on client machines. | Limit Kerberos to the realms and clients that need seamless desktop sign-in, and test it against a pilot group of workstations first. |
| Attribute and mapper scope | Importing every attribute widens the data Keycloak stores and the tokens it may issue, and each mapper needs review and testing. | Scope mappers to the attributes that applications need, and remove default mappers that are not used. |
| Number of environments with separate test accounts | Development, test and production each need directory connections, test users, group membership and sign-in tests, which multiply verification work. | Use one documented test directory or OU per environment, keep configuration as code where possible, and confirm the test account policy with the directory team. |
Kerberos sign-in and what the domain must provide
Kerberos sign-in lets a domain-joined user reach Keycloak and be authenticated without typing a password, because the browser presents a ticket issued by the domain's Kerberos key distribution center. Keycloak accepts that ticket through its Kerberos provider, which is configured per realm and tied to the directory federation you have already set up. This is a federation sign-in path, not a general single sign-on pattern, so the decisions here sit with the identity team and the directory team together. Plan it as a dependency on the domain, not as a Keycloak setting you can finish alone.
The domain must provide several things before the Keycloak side works. A service principal name for the Keycloak host has to exist in the directory, and a keytab generated for that principal has to be made available to Keycloak in a way that protects the key material. The host name clients use must resolve correctly in DNS, and forward and reverse lookups should agree with the Kerberos realm configuration, since a mismatch is one of the most common causes of failed negotiation. Hosts involved in the exchange must also keep their clocks in sync, because Kerberos rejects tickets whose timestamps fall outside the permitted skew. Confirm the tolerated skew and the time source with your directory team rather than assuming defaults.
The client side is a separate dependency. A browser will only send a negotiation request to hosts it has been told to trust. For Windows domain members using Chromium-based or Firefox browsers, that usually means adding the Keycloak host to an approved list through policy, and the exact browser settings differ by browser version and management tooling. Users on macOS, Linux or unmanaged devices may need different steps, and some clients will never send negotiation requests at all. Test each supported browser and operating system combination against a non-production realm before you promise users a passwordless experience.
Plan a fallback to password-based sign-in from the start. Mobile apps, command-line tools, non-domain devices, contractors on unmanaged laptops and some third-party applications will not complete a Kerberos exchange, and Keycloak must still offer the normal login form for them. Decide how the Kerberos provider is ordered within the authentication flow, how a failed negotiation falls through to the password form, and whether users see an error or a quiet fallback. Also decide who supports users who are blocked on a device outside the supported list.
The Keycloak server administration guide documents the Kerberos provider and the settings it accepts. The exact configuration depends on the operating system, the Keycloak version and the directory product in use, so confirm each of these against the current documentation and your own test environment before production. Ask your directory team to verify the service principal, keytab and DNS records in writing, and ask your DeployOpen or internal engineers to record the browser policy used for each client group. Treat these checks as acceptance criteria for the Kerberos part of the rollout.
Securing the bind account, LDAP traffic and secrets
A directory federation gives Keycloak a standing credential into your identity store and a path to every user record it can read. The controls below limit what that credential can do, protect it in transit and at rest, and keep changes to the federation visible to the people who answer for them.
Dedicated bind account with minimal rights
Create a service account used only by Keycloak for this federation, separate from any administrator or personal account. Grant it read access to the attributes and groups the realm actually maps, and nothing more. For Active Directory, confirm that the account is not a member of privileged groups and that its password policy and expiry match your service account standards. Review the granted rights whenever mappers change.
TLS with certificate validation enabled
Connect to the directory over LDAPS or StartTLS and keep certificate validation on, so Keycloak verifies the directory server's certificate chain and host name. Import the internal certificate authority into the truststore Keycloak uses, and avoid disabling validation to get a connection working. Apply the same rule to every path in the production configuration guidance, since a plaintext bind leaks the bind credential on the wire.
Bind credential kept in a secrets store
Keep the bind password in a secrets mechanism your platform already runs, and reference it from the federation configuration rather than typing it into the admin console or a realm file. Realm exports can include federation settings, so check the export for any plaintext credential before sharing or committing it. Confirm who can read the secret, how it is rotated, and what breaks during rotation.
Restricted search bases and filters
Set the users DN and group search base to the organizational units that hold the people Keycloak should sign in, instead of the directory root. Narrow user and group filters so disabled, service and contractor objects that should not authenticate are excluded. Narrow scope limits what a compromised federation can enumerate and keeps synchronization focused on the population the realm is meant to serve.
Admin console separated from end-user access
Administer the federation from the admin console on its own hostname or context path, reached only from administrator networks or a restricted access path. End-user sign-in endpoints stay on the public frontend. Confirm this split with your reverse proxy rules, because federation settings and the bind credential should not be reachable from the same routes that serve application sign-in.
Audit trail and approved write-back
Enable admin event logging for changes to user storage providers, mappers and sync settings, and forward those events to your log platform. Treat any write-back to the directory as a privileged action: broad write permissions on the bind account need a documented approval that names the attributes, the business reason and the owner. Review the approval record and the audit events together during each access review.
How to verify federation works and fails safely
Define the test set before you cut users over to the directory. A federation rollout is only proven when a fixed list of cases has been run against the realm you intend to operate, with the expected result written down for each one. Start with successful and failed password sign-in for test users drawn from the directory's own populations, including a user in each mapped group. Add a disabled account, which must be refused at sign-in, and confirm the refusal comes from the directory state rather than from a local flag someone set by hand. Keep the test accounts in a dedicated test OU or group so they can be created, changed and removed without touching production identities.
Next, test the changes that happen after sign-in works. Remove a test user from a group that is mapped to a Keycloak role, run a synchronization, and confirm the matching role disappears from the user's token on the next login. Change an attribute such as a display name or email in the directory, trigger synchronization, and check that the change appears in the Keycloak user record. Then test an account that is locked or expired in the directory. Decide in advance whether Keycloak should refuse sign-in, and verify that the behavior you observe matches that decision. If Kerberos single sign-on is in scope, sign in from a domain-joined client and confirm the session is established without a password prompt, and test the same user from a machine outside the domain.
Then test the failure paths, because these are where federation most often fails open. Stop the directory or block the connection from Keycloak and observe what users see and whether existing sessions and local accounts behave as the design says. Enter a wrong bind password in the user federation provider settings and confirm the administrator receives a clear, specific error in the admin console and server logs rather than a generic sign-in failure. To confirm that no local fallback account grants access the directory has revoked, pick a disabled or removed directory user who has a Keycloak local account from an earlier period, attempt sign-in, and check the user record and the role mappings to make sure no path bypasses the directory decision. Confirm the answer with the configured import mode, since the behavior differs between read-only and writable federation.
Record evidence for every test as you run it: the test case identifier, the account used, the expected result, the observed result, the time, the Keycloak version and the person who ran it. Store these records where the compliance and handover owners can find them, and link them to the change record for the cutover. This record supports internal review and the handover to the operations team. It does not on its own establish any audit outcome, and you should confirm with your assessor which evidence format and retention period they expect for the controls you are relying on. Re-run the core cases after each Keycloak upgrade and after any change to the directory schema, group structure or bind account, because those are the changes most likely to silently break mappings.
Questions teams ask before federating Active Directory into Keycloak
How much effort does directory federation take in Keycloak?
Effort depends mostly on the state of the directory and the decisions made before any configuration starts. No duration is given here because it varies by environment. The main drivers are directory quality (duplicate or stale accounts, inconsistent attributes, multiple domains or forests), the federation mode (read-only or writable), how much group and role mapping the applications need, and whether Kerberos sign-in is in scope. Each one adds design, testing and coordination with directory administrators. Ask any partner to show which of these they have assessed and how each affects the estimate, and confirm the answer against your own directory before you budget.
Can our own team set up Active Directory federation in Keycloak?
Often yes, if the team already runs Keycloak in a non-production environment and has someone who understands the directory schema, bind accounts and Kerberos. The configuration itself is documented in the Keycloak server administration guide, so the difficulty usually lies in the surrounding decisions: which mode to use, how groups map to roles, how disabled accounts are handled and how the change reaches production without locking users out. Teams without earlier directory integration work often underestimate testing with real accounts and coordination with Active Directory administrators. A practical test is whether one person can document the design, build it in a test realm and explain the failure cases to the identity team. If not, a fixed-scope engagement can cover design and build while your team takes over operations.
Is writable LDAP mode required for Active Directory federation?
No. Read-only mode is the usual starting point when Active Directory remains the source of truth for identities, passwords and group membership. In read-only mode, Keycloak reads users and groups and does not write changes back to the directory. Writable mode lets Keycloak create or update attributes and, depending on configuration, passwords in Active Directory. That requires a service account with additional rights, which directory administrators often resist, and it places responsibility for write errors on the directory side as well. Choose writable mode only when a documented business requirement needs Keycloak to change directory data. Confirm the exact permissions and sync behavior for your Keycloak version in the server administration guide before approving the account.
How do nested groups work with Keycloak and Active Directory?
Nested groups are the case teams most often underestimate. Active Directory groups can contain other groups, so a user may inherit membership through several levels that a simple lookup does not show. Confirm how the group mapper in your Keycloak version handles nested membership, and test it with a user who inherits access through your actual structure. Then decide where the mapping belongs. Mapping every directory group to a Keycloak role creates a large role set that is hard to audit. A smaller set of groups that represent application access, mapped to client roles, is usually easier to review. Agree the naming and ownership of those groups with directory administrators before configuration, because a later rename can silently change access in applications.
What happens when a user is disabled in Active Directory?
The answer depends on how users are imported and synchronized, so confirm it in a test realm before go-live. Keycloak can import users from the directory and synchronize changes on a schedule or on demand, depending on the federation settings. A user disabled or removed in Active Directory should be unable to sign in once Keycloak reflects that change. Sessions and tokens already issued stay valid until their lifetimes end or are revoked, so plan token lifetimes and session revocation as part of deprovisioning. Test the full path: disable the account, run the sync, attempt a new sign-in and check active sessions in each connected application. Document who owns the sync schedule and what the team does when a sync fails.
What does the identity team need from directory administrators?
Plan for a defined list of inputs before the build starts. Directory administrators typically provide a dedicated read-only bind account with a scoped search base, LDAP or LDAPS endpoints that Keycloak can reach through the network path you approve, and the certificate chain used for TLS. They also explain the object model: which attributes hold usernames, email addresses and department data, how groups are nested, which domains or forests are in scope, and which accounts are service or test accounts. If Kerberos is in scope, they must create the service principal and keytab with the agreed encryption settings and confirm time synchronization. The identity team owns the realm design, client mapping and test plan. Agree on change windows and a named contact on each side before work begins.
What should a written scope for an Active Directory federation include?
A written scope should state what the work covers and what it excludes, so both sides can check delivery at the end. Include the directories and domains in scope, the federation mode and the reason for it, the attribute and group mappings to be delivered, whether Kerberos sign-in is included, and the TLS and certificate handling. Add the test plan with the accounts used, the cutover and rollback steps, the documentation and handover sessions, and who on each side does what. Name the environments covered and how issues found after acceptance are handled. DeployOpen agrees scope, deliverables and timelines in writing before work starts, and a quote follows from that written scope. It does not publish a price list, so ask every bidder to address the same items so the quotes can be compared.
Which directory data problems break Keycloak federation most often?
Most failures come from directory data more often than from Keycloak settings. Duplicate usernames across domains, missing or inconsistent email addresses, stale service accounts, and attributes stored in different formats across systems cause sign-in errors or wrong attribute values. Multiple forests or domains add trust and naming questions that must be settled first. Before configuration, export a sample of users and groups, then check that the attributes Keycloak will use as the username and email are unique and complete. List accounts that should not be imported at all. Fix problems at the source where the directory owner can do so, because clean-up made only inside Keycloak can be overwritten at the next sync.
How DeployOpen scopes, builds and hands over directory federation
DeployOpen plans, implements, integrates, documents and supports self-hosted Keycloak inside your own infrastructure. For LDAP and Active Directory federation, we start by agreeing which directory is the source of truth, then build and document the federation around that decision. Each engagement is fixed-scope, with the written scope agreed before work starts.
How we scope
- Written scope names the directories, domains or forests, and the realms and applications that will use federated users.
- We record whether each directory connection is read-only or writable, and which attributes and groups Keycloak may change.
- Scope also states whether Kerberos sign-in is in or out, and how synchronization schedules and directory outages are handled.
How we build
- Configure LDAP or Active Directory federation in a non-production realm, with bind account and TLS settings verified first.
- Map groups and roles from the directory to Keycloak, and test each mapper with sample accounts from each organizational unit.
- Set up Kerberos sign-in only where the environment supports it, and test browser and service account configuration end to end.
How we hand over
- Handover documents federation settings, sync schedule, mapper list and the named owner of each directory connection.
- Runbooks cover bind account rotation, diagnosing failed synchronization and the steps when the directory is unreachable.
- Test evidence records sign-in results for each realm, directory and user group that the written scope covers.
How we support
- Ongoing support is available as a retainer covering directory changes, Keycloak upgrades and synchronization troubleshooting.
- Retainers can include retesting federated realms before each Keycloak minor release is promoted to production.
- Confirm with your directory team who approves schema, attribute and group changes that affect Keycloak sign-in.
