All guides

Authenticating a User with LDAP

This guide walks you through the process of creating an application and securing it with the Spring Security LDAP module.

What You Will Build

You will build a simple web application that is secured by Spring Security’s embedded Java-based LDAP server. You will load the LDAP server with a data file that contains a set of users.

What You Need

How to complete this guide

Like most Spring Getting Started guides, you can start from scratch and complete each step or you can bypass basic setup steps that are already familiar to you. Either way, you end up with working code.

To start from scratch, move on to Starting with Spring Initializr.

To skip the basics, do the following:

When you finish, you can check your results against the code in gs-authenticating-ldap/complete.

Starting with Spring Initializr

Because the point of this guide is to secure an unsecured web application, you will first build an unsecured web application and, later in the guide, add more dependencies for the Spring Security and LDAP features.

You can use this pre-initialized project and click Generate to download a ZIP file. This project is configured to fit the examples in this tutorial.

To manually initialize the project:

  1. Navigate to https://start.spring.io. This service pulls in all the dependencies you need for an application and does most of the setup for you.

  2. Choose either Gradle or Maven and the language you want to use. This guide assumes that you chose Java.

  3. Click Dependencies and select Spring Web.

  4. Click Generate.

  5. Download the resulting ZIP file, which is an archive of a web application that is configured with your choices.

If your IDE has the Spring Initializr integration, you can complete this process from your IDE.
You can also fork the project from GitHub and open it in your IDE or other editor.

Create a Simple Web Controller

In Spring, REST endpoints are Spring MVC controllers. You can add the following Spring MVC controller, which handles a GET / request by returning a simple message:

package com.example.authenticatingldap;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HomeController {

  @GetMapping("/")
  public String index() {
    return "Welcome to the home page!";
  }
}

The entire class is marked up with @RestController so that Spring MVC can autodetect the controller (by using its built-in scanning features) and automatically configure the necessary web routes.

@RestController also tells Spring MVC to write the text directly into the HTTP response body, because there are no views. Instead, when you visit the page, you get a simple message in the browser (because the focus of this guide is securing the page with LDAP).

Build the Unsecured Web Application

Before you secure the web application, you should verify that it works. To do that, you need to define some key beans, which you can do by creating an Application class. The following listing (from src/main/java/com/example/authenticatingldap/AuthenticatingLdapApplication.java) shows that class:

package com.example.authenticatingldap;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class AuthenticatingLdapApplication {

  public static void main(String[] args) {
    SpringApplication.run(AuthenticatingLdapApplication.class, args);
  }

}

@SpringBootApplication is a convenience annotation that adds all of the following:

  • @Configuration: Tags the class as a source of bean definitions for the application context.

  • @EnableAutoConfiguration: Tells Spring Boot to start adding beans based on classpath settings, other beans, and various property settings. For example, if spring-webmvc is on the classpath, this annotation flags the application as a web application and activates key behaviors, such as setting up a DispatcherServlet.

  • @ComponentScan: Tells Spring to look for other components, configurations, and services in the com/example package, letting it find the controllers.

The main() method uses Spring Boot’s SpringApplication.run() method to launch an application. Did you notice that there was not a single line of XML? There is no web.xml file, either. This web application is 100% pure Java and you did not have to deal with configuring any plumbing or infrastructure.

Build an executable JAR

You can run the application from the command line with Gradle or Maven. You can also build a single executable JAR file that contains all the necessary dependencies, classes, and resources and run that. Building an executable jar makes it easy to ship, version, and deploy the service as an application throughout the development lifecycle, across different environments, and so forth.

If you use Gradle, you can run the application by using ./gradlew bootRun. Alternatively, you can build the JAR file by using ./gradlew build and then run the JAR file, as follows:

java -jar build/libs/gs-authenticating-ldap-0.0.1-SNAPSHOT.jar

If you use Maven, you can run the application by using ./mvnw spring-boot:run. Alternatively, you can build the JAR file with ./mvnw clean package and then run the JAR file, as follows:

java -jar target/gs-authenticating-ldap-0.0.1-SNAPSHOT.jar

If you open your browser and visit http://localhost:8080, you should see the following plain text:

Welcome to the home page!

Set up Spring Security

To configure Spring Security, you first need to add some extra dependencies to your build.

For a Gradle-based build, add the following dependencies to the build.gradle file:

implementation 'org.springframework.boot:spring-boot-starter-ldap'
implementation 'org.springframework.boot:spring-boot-starter-security'
implementation 'org.springframework.security:spring-security-ldap'
implementation 'com.unboundid:unboundid-ldapsdk'

For a Maven-based build, add the following dependencies to the pom.xml file:

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-ldap</artifactId>
</dependency>
<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
	<groupId>org.springframework.security</groupId>
	<artifactId>spring-security-ldap</artifactId>
</dependency>
<dependency>
	<groupId>com.unboundid</groupId>
	<artifactId>unboundid-ldapsdk</artifactId>
</dependency>

These dependencies add Spring Security and UnboundId, an open source LDAP server. With those dependencies in place, you can then use pure Java to configure your security policy, as the following example (from src/main/java/com/example/authenticatingldap/WebSecurityConfig.java) shows:

package com.example.authenticatingldap;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.ldap.core.support.BaseLdapPathContextSource;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.config.ldap.LdapPasswordComparisonAuthenticationManagerFactory;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;

@Configuration
public class WebSecurityConfig {

  @Bean
  public AuthenticationManager authenticationManager(
      BaseLdapPathContextSource contextSource) {
    LdapPasswordComparisonAuthenticationManagerFactory factory =
        new LdapPasswordComparisonAuthenticationManagerFactory(
            contextSource, new BCryptPasswordEncoder());
    factory.setUserDnPatterns("uid={0},ou=people");
    return factory.createAuthenticationManager();
  }

}

You also need an LDAP server. Spring Boot provides auto-configuration for an embedded server written in pure Java, which is being used for this guide. The AuthenticationManager`bean uses `LdapPasswordComparisonAuthenticationManagerFactory to authenticate users by comparing passwords against entries found using the pattern uid={0},ou=people. Spring Boot’s auto-configured BaseLdapPathContextSource is injected automatically, pointed at the embedded server.

Add Application Properties

Spring LDAP requires three properties in application.properties. spring.ldap.base sets the base DN on the client-side LdapContextSource. spring.ldap.embedded.base-dn sets the base DN of the embedded server itself and references spring.ldap.base to avoid duplication. spring.ldap.embedded.port sets the port the embedded server listens on.

spring.ldap.base=dc=springframework,dc=org
spring.ldap.embedded.base-dn=${spring.ldap.base}
spring.ldap.embedded.port=8389

Set up User Data

LDAP servers can use LDIF (LDAP Data Interchange Format) files to exchange user data. Spring Boot’s embedded LDAP server automatically loads src/main/resources/schema.ldif by default, making it easy to pre-load demonstration data without any explicit configuration. The following listing shows an LDIF file that works with this example:

dn: dc=springframework,dc=org
objectclass: top
objectclass: domain
objectclass: extensibleObject
dc: springframework

dn: ou=groups,dc=springframework,dc=org
objectclass: top
objectclass: organizationalUnit
ou: groups

dn: ou=people,dc=springframework,dc=org
objectclass: top
objectclass: organizationalUnit
ou: people

dn: uid=ben,ou=people,dc=springframework,dc=org
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Ben Alex
sn: Alex
uid: ben
userPassword: $2a$10$c6bSeWPhg06xB1lvmaWNNe4NROmZiSpYhlocU/98HNr2MhIOiSt36

dn: uid=bob,ou=people,dc=springframework,dc=org
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Bob Hamilton
sn: Hamilton
uid: bob
userPassword: $2a$10$X/Lsg42oQwUVvusQW6Rb7uNXD3uwCQZRX7qnnEfZHCak8T82HhY8G

dn: cn=developers,ou=groups,dc=springframework,dc=org
objectclass: top
objectclass: groupOfUniqueNames
cn: developers
uniqueMember: uid=ben,ou=people,dc=springframework,dc=org
uniqueMember: uid=bob,ou=people,dc=springframework,dc=org
Using an LDIF file is not standard configuration for a production system. However, it is useful for testing purposes or guides.

If you visit the site at http://localhost:8080, you should be redirected to a login page provided by Spring Security.

Enter a user name of ben and a password of benspassword. You should see the following message in your browser:

Welcome to the home page!

Summary

Congratulations! You have written a web application and secured it with Spring Security. In this case, you used an LDAP-based user store.

See Also

The following guide may also be helpful:

Want to write a new guide or contribute to an existing one? Check out our contribution guidelines.

All guides are released with an ASLv2 license for the code, and an Attribution, NoDerivatives creative commons license for the writing.

Get the Code

Go To Repo