Keycloak : Server Admin Guide | App Documentation
User Federation
User federation allows Keycloak to connect to external user databases, such as LDAP or Active Directory, enabling authentication and user data synchronization without migrating existing user data into Keycloak. This feature is essential for organizations that maintain centralized user directories and wish to leverage Keycloak for authentication and authorization.
Configuring User Federation
To set up user federation in Keycloak:
- Access the Admin Console: Log in to the Keycloak Admin Console.
- Navigate to User Federation: In the left-hand menu, click on "User Federation."
- Add a Provider: Click on "Add provider" and select the type of external user store you wish to integrate, such as LDAP or Kerberos.
- Configure Connection Settings: Provide the necessary connection details, including connection URL, bind DN, and credentials.
- Set Synchronization Options: Choose synchronization settings to control how and when user data is synced between Keycloak and the external store.
- Define Mappers: Configure mappers to map attributes from the external user store to Keycloak's user model.(Keycloak, Keycloak, Keycloak)
For detailed guidance on each of these steps, refer to the Keycloak Server Administration Guide.(Keycloak)
Advanced Configuration and Custom Providers
If your organization uses a custom user store or requires advanced integration, Keycloak offers the User Storage SPI (Service Provider Interface). This allows developers to implement custom providers to connect Keycloak with virtually any external user database. The Keycloak Server Developer Guide provides in-depth information on creating and deploying custom user storage providers.(Keycloak, Keycloak)
Additional Resources
- Keycloak Documentation Overview: Explore all available guides and references at the Keycloak Documentation page.
- Keycloak Admin REST API: For programmatic management of user federation and other configurations, consult the Keycloak Admin REST API documentation.(Keycloak, Keycloak)
If you need assistance with specific configurations, such as setting up LDAP synchronization or creating custom mappers, feel free to ask!
Correct — the Storage SPI is not for storing AD DS user data retrieved via LDAP synchronization.
🔍 Clarification:
✅ When You Use Built-in LDAP User Federation:
Keycloak does not store user data in its internal database after LDAP sync (unless you explicitly enable "import"). Instead, it queries the external store (e.g., AD DS) on-demand via LDAP unless configured otherwise. This is the default user federation model, and it uses a built-in LDAP provider — you do not need the Storage SPI to use this.
You configure this via User Federation → Add provider → ldap in the Admin UI.
🛠️ The Storage SPI is for:
Creating custom providers to integrate with non-standard or unsupported user stores, such as:
- A legacy SQL database
- A flat file system
- A REST API for user authentication
- Custom LDAP variants with special behavior
You'd implement Storage SPI if:
- The external user source is not LDAP or Kerberos
- You need custom mapping logic
- You want to integrate with a backend that doesn't have a built-in provider in Keycloak
✅ TL;DR
| Use Case | Use Built-in Federation (e.g. LDAP) | Use Storage SPI |
|---|---|---|
| AD DS over LDAP | ✅ Yes | ❌ No |
| Custom SQL or REST-based user store | ❌ No | ✅ Yes |
| LDAP but need complex/unsupported logic | ⚠️ Maybe | ✅ Possibly |
| You want to cache or import users | ✅ Yes (with Import option) | ❌ Not SPI’s job |
Let me know if you'd like a sample configuration for Keycloak's LDAP provider or an example Storage SPI plugin.