Setting up Keycloak to connect to your AD server so that Keycloak can authenticate users against the AD. Here's a step-by-step guide to configure this integration:

Prerequisites

  • Keycloak server installed and running.
  • Active Directory server accessible from the Keycloak server.
  • Administrative access to both Keycloak and Active Directory.

Steps

  1. Log in to the Keycloak Admin Console:
  • Open your browser and navigate to the Keycloak admin console (e.g., http://<your-keycloak-server>/auth/admin/).
  • Log in with an administrative account.
  1. Select Your Realm:
  • If you haven't created a realm, create one or select the existing realm where you want to configure AD integration.
  1. Add User Federation Provider:
  • In the left-hand menu, click on User Federation.
  • Click Add provider and select ldap.
  1. Configure LDAP Settings:
  • Edit Mode: Choose READ_ONLY if you don't want Keycloak to modify the AD user data. Choose WRITABLE if you want Keycloak to be able to modify AD user data.
  • Vendor: Select Active Directory.
  • Connection URL: ldap://<AD-server-hostname>:389 for standard LDAP or ldaps://<AD-server-hostname>:636 for secure LDAP.
  • Users DN: The distinguished name (DN) where your users are stored in AD (e.g., OU=Users,DC=example,DC=com).
  • Bind DN: The DN of a user with read access to the AD (e.g., CN=Administrator,CN=Users,DC=example,DC=com).
  • Bind Credential: The password for the bind DN user.
  • User Search Filter: (sAMAccountName=*) or a custom filter to narrow down the users.
  1. Sync Settings:
  • Periodic Full Sync: Enable this if you want Keycloak to periodically sync all users.
  • Periodic Changed Users Sync: Enable this if you want Keycloak to periodically sync only changed users.
  1. LDAP Mappers:
  • Click on the Mappers tab to map LDAP attributes to Keycloak attributes.
  • Common mappers include:
  • Username LDAP Attribute: Typically sAMAccountName.
  • RDN LDAP Attribute: Typically cn.
  • UUID LDAP Attribute: Typically objectGUID.
  • User Object Classes: Typically person, organizationalPerson, user.
  1. Test the Connection:
  • Click on Test connection to ensure that Keycloak can connect to your AD.
  • Click on Test authentication to verify the bind credentials.
  1. Save Configuration:
  • Click Save to store your configuration.
  1. Sync Users:
  • After saving, you can perform a full sync to import users from AD to Keycloak.
  • Go to the User Federation tab, select your AD provider, and click Synchronize all users.

Additional Configurations

SSL/TLS Configuration

If you are using LDAPS (LDAP over SSL/TLS), ensure that:

  • Your Keycloak server trusts the certificate presented by the AD server.
  • The AD server's SSL certificate is added to the Keycloak server's truststore.

Role and Group Mappings

  • You can map AD groups to Keycloak roles to manage user permissions efficiently.
  • Go to the Mappers tab in the LDAP provider configuration and add mappers for groups.

Troubleshooting

  • Connection Issues: Ensure that the Keycloak server can reach the AD server and that firewall rules allow the necessary LDAP/LDAPS ports.
  • Authentication Issues: Verify the bind DN and credentials. Use an LDAP browser tool to test connectivity and authentication against AD.
  • Attribute Mapping Issues: Ensure that the LDAP attribute names match those used in your AD schema.