Keycloak User Federation with LDAP and Active Directory allows you to leverage existing directory services for user management and authentication. This setup integrates seamlessly with Keycloak, enabling you to centralize user data and simplify identity management across your applications.

What is Keycloak User Federation with LDAP and Active Directory?

Keycloak User Federation with LDAP and Active Directory lets you connect your existing LDAP or Active Directory servers to Keycloak. This integration means that user data, including login credentials, roles, and attributes, is managed in your directory service, while Keycloak handles authentication and authorization for your applications.

Why use Keycloak User Federation with LDAP and Active Directory?

Using Keycloak User Federation with LDAP and Active Directory provides several benefits:

  • Centralized User Management: Manage user identities in one place, reducing duplication and improving consistency.
  • Single Sign-On (SSO): Enable SSO across multiple applications using a single set of user credentials.
  • Role-Based Access Control (RBAC): Define roles and permissions in your directory service, which Keycloak can enforce across applications.
  • Scalability: Easily scale your user base without modifying application code.

Setting Up Keycloak User Federation with LDAP

Let’s walk through the process of setting up Keycloak to federate users from an LDAP server.

Prerequisites

  • Keycloak instance running
  • LDAP server accessible
  • Admin credentials for LDAP server
  • Network connectivity between Keycloak and LDAP server

Step 1: Create a New Realm

  1. Log in to the Keycloak admin console.
  2. Navigate to Master and click on Add Realm.
  3. Enter a name for your realm and click Create.

Step 2: Configure LDAP User Storage

  1. In the newly created realm, go to User Federation.
  2. Click on Add Provider and select ldap.
  3. Fill in the required fields:
    • Vendor: Choose Other if your LDAP server is not listed.
    • Connection URL: The LDAP server URL (e.g., ldap://ldap.example.com:389).
    • Users DN: Base DN for user entries (e.g., ou=users,dc=example,dc=com).
    • Bind DN: DN for binding to the LDAP server (e.g., cn=admin,dc=example,dc=com).
    • Bind Credential: Password for the bind DN.
⚠️ Warning: Ensure that the bind DN has read access to the user entries.

Step 3: Map LDAP Attributes to Keycloak

  1. In the LDAP provider settings, navigate to the Mappers tab.
  2. Click on Create to add a new mapper.
  3. Configure mappers for essential attributes like username, email, and roles:
    • Username Mapper: Maps LDAP attribute to Keycloak username.
    • Email Mapper: Maps LDAP attribute to Keycloak email.
    • Role Mapper: Maps LDAP groups to Keycloak roles.

📋 Quick Reference

  • usernameMapper - Maps LDAP uid to Keycloak username.
  • emailMapper - Maps LDAP mail to Keycloak email.
  • roleMapper - Maps LDAP memberOf to Keycloak roles.

Step 4: Test the Configuration

  1. Go back to the User Federation page.
  2. Click on the LDAP provider to open its settings.
  3. Click on Test Connection to verify connectivity.
  4. Click on Test Authentication to ensure user authentication works.
✅ Best Practice: Regularly test your configuration to catch issues early.

Common Issues and Troubleshooting

Issue: Connection Refused

Symptom: javax.naming.CommunicationException: Connection refused

Solution: Verify network connectivity between Keycloak and LDAP server. Check firewall rules and ensure the LDAP port is open.

Issue: Invalid Credentials

Symptom: javax.naming.AuthenticationException: [LDAP: error code 49 - Invalid Credentials]

Solution: Double-check the bind DN and password. Ensure the bind DN has the necessary permissions.

Issue: User Not Found

Symptom: javax.naming.NameNotFoundException: [LDAP: error code 32 - No Such Object]

Solution: Verify the Users DN and search filters. Ensure they match the LDAP directory structure.

🎯 Key Takeaways

  • Configure LDAP provider with correct connection details
  • Map essential LDAP attributes to Keycloak
  • Regularly test the configuration for connectivity and authentication

Setting Up Keycloak User Federation with Active Directory

Setting up Keycloak with Active Directory follows a similar process but requires some specific configurations.

Prerequisites

  • Keycloak instance running
  • Active Directory server accessible
  • Admin credentials for Active Directory
  • Network connectivity between Keycloak and AD server

Step 1: Create a New Realm

Follow the same steps as in the LDAP setup to create a new realm in Keycloak.

Step 2: Configure Active Directory User Storage

  1. In the newly created realm, go to User Federation.
  2. Click on Add Provider and select ldap.
  3. Fill in the required fields:
    • Vendor: Choose Microsoft Active Directory.
    • Connection URL: The AD server URL (e.g., ldaps://ad.example.com:636).
    • Users DN: Base DN for user entries (e.g., DC=example,DC=com).
    • Bind DN: DN for binding to the AD server (e.g., CN=Administrator,CN=Users,DC=example,DC=com).
    • Bind Credential: Password for the bind DN.
⚠️ Warning: Use LDAPS for secure connections to AD.

Step 3: Map AD Attributes to Keycloak

  1. In the AD provider settings, navigate to the Mappers tab.
  2. Click on Create to add a new mapper.
  3. Configure mappers for essential attributes like username, email, and roles:
    • Username Mapper: Maps AD attribute to Keycloak username.
    • Email Mapper: Maps AD attribute to Keycloak email.
    • Role Mapper: Maps AD groups to Keycloak roles.

📋 Quick Reference

  • usernameMapper - Maps AD sAMAccountName to Keycloak username.
  • emailMapper - Maps AD mail to Keycloak email.
  • roleMapper - Maps AD memberOf to Keycloak roles.

Step 4: Test the Configuration

  1. Go back to the User Federation page.
  2. Click on the AD provider to open its settings.
  3. Click on Test Connection to verify connectivity.
  4. Click on Test Authentication to ensure user authentication works.
✅ Best Practice: Regularly test your configuration to catch issues early.

Common Issues and Troubleshooting

Issue: Connection Refused

Symptom: javax.naming.CommunicationException: Connection refused

Solution: Verify network connectivity between Keycloak and AD server. Check firewall rules and ensure the LDAPS port is open.

Issue: Invalid Credentials

Symptom: javax.naming.AuthenticationException: [LDAP: error code 49 - Invalid Credentials]

Solution: Double-check the bind DN and password. Ensure the bind DN has the necessary permissions.

Issue: User Not Found

Symptom: javax.naming.NameNotFoundException: [LDAP: error code 32 - No Such Object]

Solution: Verify the Users DN and search filters. Ensure they match the AD directory structure.

🎯 Key Takeaways

  • Configure AD provider with correct connection details
  • Map essential AD attributes to Keycloak
  • Regularly test the configuration for connectivity and authentication

Security Considerations

Integrating LDAP and Active Directory with Keycloak involves several security considerations:

Secure Connections

Always use LDAPS (LDAP over SSL/TLS) to encrypt communication between Keycloak and your directory service. This prevents eavesdropping and man-in-the-middle attacks.

🚨 Security Alert: Never use plain LDAP (`ldap://`) in production environments.

Manage Permissions

Ensure that the bind DN used by Keycloak has only the necessary permissions. Avoid using administrative accounts for binding, as this increases the risk of unauthorized access.

Regular Auditing

Enable logging and auditing in both Keycloak and your directory service. Regularly review logs to detect and respond to suspicious activities.

Password Policies

Implement strong password policies in your directory service to protect user accounts. Keycloak can enforce additional policies, such as password expiration and complexity requirements.

💜 Pro Tip: Use LDAPS certificates signed by a trusted CA to avoid certificate validation errors.

Comparison: LDAP vs. Active Directory

FeatureLDAPActive Directory
StandardizationOpen standardMicrosoft proprietary
PlatformCross-platformWindows-based
FeaturesBasic user managementAdvanced features (Group Policy, DNS)
IntegrationEasy with KeycloakSeamless with Keycloak
SecurityRequires LDAPSBuilt-in security features

Conclusion

Integrating Keycloak with LDAP and Active Directory provides a powerful way to manage user identities and authentication. By following the steps outlined in this guide, you can set up a secure and efficient user federation system. Remember to prioritize security, regularly test your configuration, and map attributes correctly to ensure smooth operation.

Go ahead and implement these steps in your environment. Happy coding!