Spring Security LDAP with Microsoft Active Directory

Stories about project management and coding

Spring Security LDAP with Microsoft Active Directory

The following describes how to easily configure Spring Security to use Microsoft Active Directory as the user repository.

This guide is based on the official Spring guide for Securing a Web Application and shall focus on the LDAP / Microsoft Active Directory part.

It uses the default Spring Boot configuration for most things, including the session store. Baeldung has a good write up on this topic.

The full example project can be found in my Github repository.

LDAP vs LDAPS

The configuration for using LDAP without SSL is the easiest, but I would strongly recommend to use LDAPS (or LDAP over TLS) to connect to the LDAP / Active Directory server. Otherwise, your users credentials will be transmitted in cleartext to the server, making your setup vulnerable to MITM attacks. I will not explain the how to accomplish non-TLS connections in this guide.

Most guides one can find on the subject of LDAP authentication for Spring Security, like the official one, use either an integrated LDAP server or plain, (unsecured) LDAP.
The most common problem when trying to use LDAPS is the fact that Java uses its own keystore for known root certificate authorities (called truststore).

To make the Java runtime accept the Active Directory root CA, you have three options:

  1. Import the root CA certificate into the global truststore.
    This would require you to import the certificate every time the truststore gets replaced. This can includes JRE updates, setting up the project on a new developers machine, deploying the project to a new server or just using docker.
  2. Use JRE runtime parameters to load the truststore every time the project starts.
  3.  Include the truststore in your package and programmatically load the truststore when the project starts.

We are going to use the third option in this guide.

Replacing the global truststore

When loading a truststore that only contains the Active Directory root certificate, you will run into troubles when trying to open SSL / TLS connections to server not belong to the domain. For these instances, you have to either import the concerned SSL certificates into the truststore or import the AD root certificate into a global truststore and at this one to your project (which will then again generate more work when the root CAs need updates).

Getting the right Active Directory Certificate

To get the AD root certificate, you need to know one of the domain controller hostnames.
Use the following openssl command to view the certificate presented by the server:

This should show you the details for the Active Directory root certificate.

This command uses the default LDAPS port 636, in case this port does not work for your setup, you can try port 3269, the LDAPS port to query the global catalog server (which we wil use later).

To save the the certificate in x509 format:

Now we need to import the certificat into a new (or existing) truststore:

This will create a truststore with the default jks format.

Setting up Spring Security with LDAPS

Spring Boot comes with lots of default settings, this enables us to quickly setup the project with with Security. Follow the official guide for the necessary steps. The following shall only describe the LDAPS part.

Copy the truststore file created in the last step to /src/main/ressource in your project (we use the name cacerts.jks in this guide, make sure the filename matches the configuration below).
Your project structure should look something like this:

There are multiple ways to configure Spring Security to use LDAP as the authentication provider.
Active Directory would require you to adapt the default LDAP provider with certain settings (like using the sAMAccountName as the username field.).
Luckily Spring provides a specific default implementation for Active Directory called ActiveDirectoryLdapAuthenticationProvider. We only have to create a bean of this type and Spring Boot will take care of the rest.

Here is a simple WebSecurityConfigurerAdapter that also creates the ActiveDirectoryLdapAuthenticationProvider bean.

It will present the default Spring Security login page.
Make sure you replace “domain.name” mentioned in the code below with your domain name. You can provide multiple domain controllers by comma-separating them as below.

This code will replace the global truststore with the one you created and query the global catalog server with the provided credentials.

If everything works, you should be presented with the default login page:

The server will take the supplied credentials and try to an LDAP bind, if this opperation is sucessfully, the user details are available to the web context.

Leave a Reply

Your email address will not be published. Required fields are marked *