Keycloak User Federation

The Sovereign Bridge of the Enterprise Core

User Federation in Keycloak is the “Sovereign Bridge” that connects your modern identity layer to your legacy “System of Record.” For most enterprises, user identity begins and ends in Active Directory (AD) or an LDAP store. User Federation allow Keycloak to “Project” those identities into the modern world, making them available for OIDC and SAML applications without requiring a manual migration of 100% of your user data. For the IAM architect, User Federation is the engine of Infrastructural Continuity, ensuring that a password change on a Windows workstation is instantly recognized by your cloud-native Keycloak applications.

Core Mission

Legacy Directory Integration. Establishing a high-fidelity synchronization and authentication pipeline that allows Keycloak to serve as the modern face of traditional LDAP and Active Directory stores.

Like a Modern Storefront for an Ancient Warehouse: Imagine your organization has a massive, dusty warehouse (Your Active Directory) filled with millions of files (User Records). It works, but the filing system is too old for the modern internet. User Federation is the "Sovereign Storefront." It sits in front of the warehouse. When a customer (An App) asks for a record, the Storefront knows exactly where to find it in the warehouse, brings it to the front, translates it into a modern digital format (A Token), and hands it over. The warehouse stays the same, but it's now accessible to the whole world.

Active Directory Sync / LDAP User Portals / Hybrid Cloud IAM / Legacy Credential Reuse

The Federation Strategy Matrix

Designing for user federation requires choosing the right synchronization mode and performance settings.

Strategic Federation Profiles

Profile	Strategic Responsibility	IAM Implementation
Full Sync	Directory Mirror.	Pulling every user and attribute from LDAP into the Keycloak DB periodically.
Changed Users Sync	Incremental Update.	Only syncing the “Deltas”—users modified since the last successful sync cycle.
On-Demand (Import)	Just-In-Time Mirror.	Users are only created in Keycloak the first time they attempt to log in.
No-Import (Proxy)	Pure Identity Proxy.	Keycloak validates credentials against LDAP but never stores a local copy of the user.

The Federation Synchronization Flow

Bridging LDAP to Keycloak follows a “Read-Mapping-Commit” path designed for high fidelity.

graph LR
    Read[Query LDAP: Search Filters] --> Match[Attribute Mapping]
    Match --> Sync[Commit to Keycloak DB]

LDAP Extraction & Filtering

Keycloak initiates an LDAP query using your configured **Search Filters** (e.g. `(memberOf=CN=KeycloakUsers,OU=Groups,DC=sovereign,DC=corp)`). This ensures that only the relevant slice of your directory is ever exposed to the modern identity layer.

Sovereign Attribute Mapping

The "Mappers" translate LDAP fields into Keycloak attributes. This is where you map `sAMAccountName` to `username`, or `mail` to `email`. You can also map **Role Mappers**—automatically granting Keycloak roles to users based on their LDAP group memberships, ensuring that legacy authority is reflected in modern tokens.

Credential Validation (The Handshake)

When a user logs in, Keycloak performs a "Bind" operation against the LDAP server. It sends the provided password; if LDAP says "Success," Keycloak establishes the session. This means passwords never have to be synced or stored in Keycloak, maintaining a **Single Source of Truth** on-premise.

Technical Federation Implementation

Configuring an AD User Federation provider requires precise LDAP URI and filter syntax.

AD Provider Config (Conceptual UI)

# Configuring Keycloak to sync from Active Directory
Provider_Type: "ldap"
Console_ID: "Sovereign-AD"
Config:
  ConnectionURL: "ldaps://dc1.sovereign.corp:636"
  UsersDN: "OU=Users,DC=sovereign,DC=corp"
  BindDN: "CN=ServiceAccount,CN=Users,DC=sovereign,DC=corp"
  UserObjectClasses: "person, organizationalPerson, user"
  UsernameLDAPAttribute: "sAMAccountName"
  RDNLDAPAttribute: "cn"

Federation Implementation Guides

Master the technical ceremonies of legacy directory integration and attribute mapping.

Next Steps

Explore Keycloak User Federation Guide.
Review Active Directory Lightweight Directory Services (AD LDS).
Check Sync Health Metrics for monitoring daily directory sync performance.