2 Ways to setup LDAP Active Directory Authentication in Java - Spring Security Example Tutorial

The LDAP authentication is one of the most popular authentication mechanism around the world for enterprise application and Active directory (an LDAP implementation by Microsoft for Windows) is another widely used LDAP server. In many projects, we need to authenticate against active directory using LDAP by credentials provided in the login screen. Sometimes this simple task gets tricky because of various issues faced during implementation and integration and no standard way of doing LDAP authentication in a Java web application. Even though Java provides LDAP support but in this article, I will mostly talk about spring security because of it's my preferred Java framework for authentication, authorization, and security-related stuff.

We can do the same thing in Java by writing your own program for doing LDAP search and then LDAP bind but as I said its much easier and cleaner when you use spring security for LDAP authentication.

Along with LDAP Support, Spring Security also provides several other features which are required by enterprise Java application like Role-based Access Control, SSL Security, encryption of passwords and session timeout facilities.

Btw,  a decent knowledge of the Spring Framework is required to effectively use Spring Security in your project. It's not mandatory but unless you understand core concepts like Spring bean, dependency injection, container and how Spring works, it would be very difficult to use Spring security properly.

And, if you are not familiar with Spring security, it's better to spend some time learning it and if you need a recommendation, there is no better course than Spring Framework 5: Beginner to Guru by John Thompson on Udemy, one of the most up-to-date courses which cover Spring 5.0 features like Reactive development, etc.

1. LDAP Authentication Basics

Before getting deep into LDAP authentication on Active Directory, let's get familiar with some LDAP term because most of the time user is doing it the first time and they are not very familiar with typical LDAP glossary such as Dn, Ou, Bind or search, etc.

Dn - Distinguished name, a unique name which is used to find the user in LDAP server like Microsoft Active Directory.

Ou - Organization Unit

Bind - LDAP Bind is an operation in which LDAP clients sends bind request to LDAP user including username and password and if LDAP server able to find user and password correct, it allows access to the LDAP server.

Search - LDAP search is an operation which is performed to retrieve Dn of the user by using some user credential.

Root - LDAP directory's top element, like Root of a tree.

BaseDn - a branch in LDAP tree which can be used as a base for LDAP search operation like dc=Microsoft,dc=org"

If you want to know more about LDAP and Spring Security integration, you can also check out Spring Security Core: Beginner to Guru by John Thompson on Udemy. It's a great course to learn essential Spring Security concepts. 

2. LDAP Authentication in Active Directory Spring Security

There are two ways to implement active directory authentication using LDAP protocol in spring security, the first way is a programmatic and declarative way which requires some coding and some configuration.

On the other hand, the second way is an out of box solution from spring security which just requires configuring ActireDirectoryAuthenticationProvider and you are done. we will see both approaches but I suggest using the second one because of its simplicity and easy to use a feature.

2.1 Active Directory Authentication using LDAP in Spring Security -Example 1

Configuration

Add the following configuration into your spring application-context.xml file, I would suggest putting this configuration in a separate application-context-security.XML file along with other security-related stuff.

1) Configuring LDAP Server
In order to configure LDAP server, please put following XML snippet into Spring security configuration file:

<s:ldap-server 
  url="ldap://stockmarket.com"   //ldap url
  port="389"                    //ldap port
  manager-dn="serviceAcctount@sotckmarket.com" //manager username
  manager-password="AD83DgsSe"                 //manager password
/>      

This configuration is self-explanatory but briefly few lines about manager-in and password, LDAP authentication on the active directory or any other LDAP directory is performed in two steps first an LDAP search is performed to locate Dn(Distinguished Name) of the user and then this Dn is used to perform LDAP Bind.

If the bind is successful than user authentication is successful otherwise it fails. Some people prefer remote compare of password than LDAP bind, but LDAP bind is what you mostly end of doing. 

Most of the Active directory doesn't allow Anonymous Search operation, so to perform an LDAP search your service must have an LDAP account which is what we have provided herein manager-in and manager-password.property.

In Summary, now LDAP login will be done in these steps:

1. Your Service or application binds itself with LDAP using manager-dn and manager-password.
2.  LDAP search for the user to find UserDn
3.  LDAP bind using UserDn

That's complete the LDAP login part.

Now, let's move to next part of configuration LDAP authentication provider. 

2) Configuring LDAP Authentication Provider

This section specifies various authentication provider in spring-security here you can see your LDAP authentication provider and we are using userPrincipalName to search user inside Microsoft's Active directory.

<s:authentication-manager erase-credentials="true">
<s:ldap-authentication-provider
   user-search-base="dc=stockmarketindia,dc=trader"
   user-search-filter="userPrincipalName={0}"
/>

<s:authentication-provider 
  ref="springOutOfBoxActiveDirecotryAuthenticationProvider"/>
</s:authentication-manager>

Now a small piece of coding is needed to pass the userPrincipalName and authenticate the user.

public boolean login(String username, String password) {
   AndFilter filter = new AndFilter();
   ldapTemplate.setIgnorePartialResultException(true); // Active 
   Directory doesn’t transparently handle referrals. This fixes that.
 
   filter.and(new EqualsFilter("userPrincipalName", username));
   return ldapTemplate.authenticate("dc=stockmarketindia,dc=trader", 
             filter.toString(), password);

}       

line 2 is very important in this program because I spent the whole day figuring out when my application was repeatedly throwing javax.naming.PartialResultException: Unprocessed Continuation Reference(s)

you can also use sAMAccountName for the searching user, both userPrincipalName and sAMAccountName are unique in the Active Directory. 

What is most important here is that it has to be full name e.g. name@domain like jimmy@stockmarket.com.

The authenticate() method will return true or false based on a result of the bind operation. Btw, if you want to learn more about LdapTempalte class then I suggest you check  Learn Spring Security Masterclass by Eugen Paraschiv, which is a comprehensive course and covers Spring Security 5 as well.

2.2 Active Directory Authentication using LDAP in Spring Security - Simpler Example

The second approach is much simpler and cleaner because it comes out of the box, you just need to configure LDAP server URL and domain name and it will work like cream.

<s:authentication-manager erase-credentials="true">
   <s:authentication-provider ref="ldapActiveDirectoryAuthProvider"/>
</s:authentication-manager>

<bean id="ldapActiveDirectoryAuthProvider" 
class="org.springframework.security.ldap.authentication.ad.
                ActiveDirectoryLdapAuthenticationProvider">
  <constructor-arg value="stockmarket.com" />  //your domain
  <constructor-arg value="ldap://stockmarket.com/" />  //ldap url
</bean>

That's it, done. 

This configuration will both authenticate and load all the granted authorities from LDAP like a group which you are a member of. This is integrated with spring security login element also.

If you are not familiar with GrantetAuthority and Access Control List in Spring Security then I suggest you go through the Learn Spring Security Certification Class course by Eugen Paraschiv, which covers this topic in good detail for both XML and Java Configuration.

2.3 Dependency

This example is based on spring security 3.0 and I was using spring-ldap-1.3.1.RELEASE-all.jar and spring-security-ldap-3.1.0.RC3.jar. 

If you don't know how to download Spring framework JAR files, follow the steps given in this Spring Framework JAR download Guide, which explains how to download Spring framework and other related JAR from Maven Central. 

2.4 Errors during LDAP authentication

you need to be very lucky to complete LDAP authentication against Active directory without any error or exception, here I am listing down some common error which I encountered and their solutions for quick reference.

1) javax.naming.PartialResultException: Unprocessed Continuation Reference(s); remaining name 'dc=company,dc=com'

This error comes because Microsoft Active Directory doesn't handle referrals properly and to fix this set this property

ldapTemplate.setIgnorePartialResultException(true);

2) javax.naming.NameNotFoundException: [LDAP: error code 32 - No Such Object]; remaining name ''

This error solved with some trial and error and mainly came due to an invalid format of username. it solved by providing full name e.g. jemmy@stockmarket.com

2.5 Tools

LDAP Browser: Having some tools to look data inside LDAP directory is best it gives you some visibility as well as means to browse data in LDAP. 

It's called an LDAP browser and there is a lot of open source LDAP browser available in web, like the jexplorer. you can browse and see data inside Active Directory by using LDAP browser.

2.6 LDAP Active directory Authentication over SSL

This works perfectly to implement LDAP authentication against Microsoft active directory. but one thing you might want to put attention is that with LDAP username and password travel to LDAP server as clear text and anyone who has access to LDAP traffic can sniff user credential so it's not safe. 

One solution is to use LDAP( LDAP over SSL) protocol which will encrypt the traffic travels between LDAP client and server.

This is easy to do in spring-security what you need to change is the URL instead of "ldap://stockmarket.com/" you need to use ""ldaps://stockmarket.com/". actually, a port for LDAP is 339 and for LDAPS is 636 but that's been taken care by spring in the second approach, in the first approach you need to provide this information.

What problem you may face is "unable to find valid certification path to requested target"

Exception  as shown below:

javax.net.ssl.SSLHandshakeException:
sun.security.validator.ValidatorException: PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException: 
    unable to find valid certification path to requested target

The reason of this Exception is simple, Certificate returns during SSL handshake are not signed by any trusted Certification Authority(CA) which is configured in you JRE Keystore e.g Verisign, Thawte, GoDaddy or entrust, etc. Instead, Server is sending a certificate which is not known to JRE.

To solve this problem you need to add certificates returned by Server into JRE's keystore. Btw, if you are confused between the key store and trust store then please read my article difference between keystore and trust store in Java to first learn about it. 

2. 7 What I did to solve the problem

Nothing surprising, I use an open-source program called InstallCert.java, just run with your LDAP server and port and it will try to connect LDAP server using SSL and first throw same "PKIX path building failed" and then Certificates returned by LDAP server. 

It will then ask you to add Certificate into keystore just give certificate number as appeared on your screen and it will then add those certificate into "jssecacerts" inside C:\Program Files\Java\jdk1.6.0\jre\lib\security folder. Now re-run the program that error must be disappeared and

It will print:

"Loading KeyStore jssecacerts...

Opening connection to stockmarket.com:636...

Starting SSL handshake...

No errors, the certificate is already trusted

We are done, now if you try authenticating against LDAPS you will succeed.

There are many other approaches to perform LDAP authentication against active directory even without spring security by using Java. but I found spring-security very helpful so consider using it for your security requirement. let me know if you face any issue during LDAP login and I'll try my best to help you.

Further Learning
Spring Framework 5: Beginner to Guru
Spring Security Fundamentals by Bryan Hassen

Hands-On Spring Security 5 for Reactive Apps

Other Java and Spring Resources you may like

• 5 Courses to Learn Spring Security Online
• What is SecurityContext and SecurityContextHolder in Spring?
• How to enable Spring Security in Java Web Application?
• How to enable HTTP Basic Authentication using Spring Security?
• How HttpBasicAutentication works in Spring Security?
• 3 Books and Courses to Learn Spring Security in Depth
• 10 Spring MVC annotations Java developer should learn
• Top 5 Courses to Learn Spring Boot Online
• Top 15 Spring Boot Interview Questions
• How to Crack Spring Core Professional Certification?
• 21+ Spring MVC Interview Questions for Java developers
• 10 Spring Boot Courses to learn Microservices in Java
• 10 Free Courses to learn Spring Boot for Beginners

P.S. - If you are an experienced Java/JEE Program and want to learn Spring Security end-to-end, I recommend the Learn Spring Security course by Eugen Paraschiv, The definitive guide to secure your Java application. It's useful for both junior and experienced Java Web developers.