Linking Keycloak to Microsoft Active Directory and its Nuances

Eventual Windows AD LDAPS setup using Keycloak for Application Login

Keycloak XML Settings for SSL

To use LDAPS, the standalone.ha.xml file you use in Keycloak needs a section added. If you use docker or images in K8s, the configuration you use has to be updated accordingly. I use docker, so I have a mounted path to my standalone.ha.xml so I can update it.

<spi name="truststore">
<provider name="file" enabled="true">
<property name="file" value="/opt/jboss/keycloak/truststore.jks"/>
<property name="password" value="changeit"/>
<property name="hostname-verification-policy" value="ANY"/
<property name="enabled" value="false"/>

Exporting your Certificate to use

Whether you use Windows Certificate Manager for AD or self signed certs, you need to have the .cer file of the Certificate Authority certificate to do secure LDAP against AD for Keycloak. If you are doing ldap:// versus ldaps:// this may not matter as much to you.

Adding the AD Certificate to a Truststore for Keycloak

Now with the .cer file and the truststore.jks lines in your configuration you can create the truststore and add the certificate into it. You will need to run a command like the following below. The -keystore parameter points to the new truststore.jks file. And the -file parameter points to the certificate .cer file you exported earlier.

keytool -import -alias FQDN-OF-LDAP-SERVER -keystore /opt/jboss/keycloak/truststore.jks -file CERTIFICATE-FILE-EXPORTED

Running Keycloak with the Truststore and SPI settings

Now in your standalone.ha.xml file you can edit the password and set enabled = true in that SPI area you added earlier. In order for this to set correctly and work, you will need to restart Keycloak. It will pull the configuration in and use it. Make sure you look at the logs to ensure it is listening to the Admin port and has no errors restarting.

Creating the Domain User in Microsoft AD

Now we switch over to Windows AD. In your AD, setup the user in Active Directory you wish to use to sync the usernames into Keycloak. I usually have a “svcxxxxxxxx” type name starting with “svc” so I know it is a service account. Please use whatever your organization describes for that. The user should only need to be a Domain User but you can test that and tweak as you go for least privileged access.

dsquery user -name svcopenrmfprouser*

User Federation in Keycloak with LDAP settings

Now that we have Keycloak setup for LDAPS and we have our Windows AD user and password, we can setup Keycloak to talk to Windows AD.

User Federation using LDAPS with Windows AD
Example Keycloak User Federation using LDAPS setup for Windows Active Directory

Syncing the User Federation settings

Once you know the LDAP/S setup works you can go down to “Sync Settings” and specify the batch size, sync period, and such according to your requirements. Hover over the ? icons to not the required information in those fields for the period in seconds.

Final Steps to Setup User Roles/Groups/Permissions

That just gets the users into your listing. You may still need to assign roles or groups/permissions to the users once they are in there depending on your setup and applications using Keycloak. But you are pretty close if you successfully get to this step!

Wrapping it all Up

If you are doing LDAPS realize that your CA certificate and possibly the Windows AD certificate you are using on the machine that LDAPS points to will eventually expire. You will have to make sure you note when that happens and update the certificates accordingly.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Dale Bingham

Dale Bingham

CEO of Soteria Software. Developer on OpenRMF. Software Geek by trade. Father of three daughters. Husband. Love new tech where it fits. Follow at @soteriasoft