Linking Keycloak to Microsoft Active Directory and its Nuances
I had a hell of a time getting Keycloak to link up to Microsoft Active Directory (AD) correctly over LDAP and then LDAPS. These are the steps I used to successfully do that so you do not run through the same pain! I am going to document this as secure LDAP against Windows AD with certificates and such. If you do not have certificates or are not doing ldaps:// type connections they you may be able to skip those steps.
This is not a “step 1 through step 47” type of write-up. It is an explanation to help you get going and hopefully get close without searching endlessly and using 8 different articles to finally get this to work. Hopefully this article at least gets that down to 2 or 3!
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.
Note the path to the truststore in the section below you need to add, the password default, and the enabled = false initially just to get this in there. You will have to make a truststore.jks file with the keytool command later for your .cer file. You should see other <spi … /> sections around line 550 or so in the standard *.ha.xml file. It can be the last one in that area.
<spi name="truststore">
<provider name="file" enabled="true">
<properties>
<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"/>
</properties>
</provider>
</spi>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.
Export that into a base-64 encoded .cer file you can use to import into a truststore. This tells Keycloak “hey, this is coming from a valid CA certificate” when it connects to LDAPS.
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.
If you are doing this inside a Keycloak container, with a “docker exec -it” type of command, make sure your certificate is in a directory mounted into the container so you can see it. You could do this in Java on your machine also if you have Java installed.
keytool -import -alias FQDN-OF-LDAP-SERVER -keystore /opt/jboss/keycloak/truststore.jks -file CERTIFICATE-FILE-EXPORTEDIf this is a new truststore you will need to create a password and keep it handy to update that standalone.ha.xml file. Again this is if you are using ldaps:// connections.
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.
If errors show up, troubleshoot those before going forward.
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.
Once the user is made, run a “dsquery” command so you know the “CN=,OU=” type of string that is required for connection and pulling users from proper groups. The example below uses the “svcopenrmfprouser” account and pulls back a big long string. That string is used in the Bind DN field later to connect to Windows AD.
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.
In Keycloak go to your proper realm and click the User Federation menu on the left. Choose the “ldap” option and then fill in the required information. Set the display name, edit mode as read only, vendor to Active Directory, and other options to your liking. Some may want Sync Registrations on, some may want them off. You need to test and tweak this to your liking to make sure it works.
Your Keycloak form shows up to enter all your required information. In the username LDAP, RDN LDAP as well as UUID LDAP attributes see the below image for what I used. I have seen some use the “samAccountName” type of attributes there and others use “cn”. I used “cn” in multiple fields and it worked. Again search Keycloak documentation and test those fields with your setup to make sure they work.
The User Object Classes are usually the ones automatically entered. And then enter the ldap://xxxxx URL to the server or ldaps:// if you are doing secure LDAP. Right there you can click “Test connection” to make sure you can see the LDAP/S URL. If not troubleshoot connection, DNS, path, network, and other items to ensure that Keycloak can see that machine.
Next you will add your Users DN which is the groups that you wish to automatically sync with Keycloak for Windows AD. Again, as everyone’s AD forest and trees are particular to them you will need to test this and see what you want to do. I put my “svc” user in the right OU. So the “Bind DN” let me just remove the username part and use the rest for my Users DN.
The example below is for a fictitious server setup in a lab I did for OpenRMF Professional. I used the search scope of Subtree, bind type simple, the Bind DN as the string from the “dsquery” command above and then that user’s password. Then you can click “Test authentication” to test that the user information is correct and can connect into LDAP/S. Again if there are errors, check the Keycloak logs to troubleshoot accordingly.
When all is working correctly Save it and sync one time to get your users in there. Check the Users listing to see if they showed up. Again if not, go back and troubleshoot using the logs.
Note this is NOT Active Directory Federation. It is user federation within Keycloak.
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.
When done click Save on that as well.
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!
Now you just need to test that those users can log in with their Windows AD and use the application(s) linked to Keycloak. This does it for this Keycloak realm. If you have multiple realms for multiple applications you may have to repeat this accordingly.
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.
Some points of reference below:
