How to Integrate LDAP with Spring Boot: A Step‑by‑Step Guide

Many times when we develop company systems or products, we need to create our own user management system. This is not difficult for developers, but when we need to maintain multiple different systems and allow the same user to use across systems, if each system maintains its own user information, synchronizing user information becomes cumbersome, and users may encounter inconsistent passwords and other issues. If we introduce LDAP to centrally store basic user information and provide a unified read/write interface and validation mechanism, these problems become easier to solve. Especially when developing internal management systems, many third‑party products such as OA and finance systems are involved. Developing a custom user management system would require secondary integration, increasing cost. Since LDAP is not new and most mature software supports LDAP, its usage remains common today. Below we will specifically see how to access an LDAP server when using Spring Boot.

LDAP Introduction

LDAP (Lightweight Directory Access Protocol) provides a directory service, a special type of database optimized for read, browse, and search operations. Directories store descriptive, attribute‑based information and support complex filtering, but they do not provide full transactional capabilities for massive updates like traditional databases. They can store various data such as personal details, web links, and images, and are accessed over TCP/IP using the LDAP protocol.

Information in an LDAP directory is organized as a tree. The actual data is stored in entries, each identified by a Distinguished Name (DN) that works like a primary key. An entry consists of attributes, each having a type and one or more values, similar to fields in a relational table, but an attribute type may have multiple values.

The tree usually starts with a country (c=CN) or domain component (dc=com) at the root, followed by organizations (o=Acme) or organizational units (ou=People). Object classes (objectClass) define which attributes an entry must contain; for example, the inetOrgPerson class requires "sn" (surname) and "cn" (common name) attributes, while optional attributes like email or phone can also be included.

o: organization (company)

ou: organizational unit (department)

c: countryName

dc: domainComponent

sn: surname

cn: common name

Getting Started Example

After learning the basics of LDAP, we use a simple example to deepen our understanding.

Create a basic Spring Boot project (see the "Quick Start 1" article if needed).

Add two important dependencies to pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-ldap</artifactId>
</dependency>

<dependency>
    <groupId>com.unboundid</groupId>
    <artifactId>unboundid-ldapsdk</artifactId>
    <scope>test</scope>
</dependency>

The spring-boot-starter-data-ldap dependency provides automatic LDAP configuration based on Spring Data LDAP. The unboundid-ldapsdk dependency supplies an embedded LDAP server for testing; its scope is set to test because in production you would connect to a real, standalone LDAP server.

Create an ldap-server.ldif file under src/test/resources to store the initial LDAP data.

dn: dc=didispace,dc=com
objectClass: top
objectClass: domain
objectclass: extensibleObject
dc: didispace

dn: ou=people,dc=didispace,dc=com
objectclass: top
objectclass: organizationalUnit
ou: people

dn: uid=ben,ou=people,dc=didispace,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: didi
sn: zhaiyongchao
uid: didi
userPassword: {SHA}nFCebWjxfaLbHHG1Qk5UU4trbvQ=

This defines a basic user with full name zhaiyongchao and common name didi, which we will later read in the program.

Add embedded LDAP configuration to application.properties:

spring.ldap.embedded.ldif=classpath:ldap-server.ldif
spring.ldap.embedded.base-dn=dc=didispace,dc=com

Define a Java entity that maps LDAP attributes and a corresponding repository using Spring Data LDAP:

@Data
@Entry(base = "ou=people,dc=didispace,dc=com", objectClasses = "inetOrgPerson")
public class Person {
    @Id
    private Name id;
    @DnAttribute(value = "uid", index = 3)
    private String uid;
    @Attribute(name = "cn")
    private String commonName;
    @Attribute(name = "sn")
    private String userName;
    private String userPassword;
}

public interface PersonRepository extends CrudRepository<Person, Name> {}

With the entity and repository defined, we can use PersonRepository to read and write LDAP entries.

Create a unit test to read all users:

@Slf4j
@SpringBootTest
public class ApplicationTests {
    @Autowired
    private PersonRepository personRepository;

    @Test
    public void findAll() {
        personRepository.findAll().forEach(p -> {
            System.out.println(p);
        });
    }
}

Running the test prints the user defined in ldap-server.ldif:

Person(id=uid=ben,ou=people,dc=didispace,dc=com, uid=ben, commonName=didi, userName=zhaiyongchao, userPassword=123,83,72,65,125,110,70,67,101,98,87,106,120,102,97,76,98,72,72,71,49,81,107,53,85,85,52,116,114,98,118,81,61)

Add User

After completing the introductory example, you can easily add a new user using the same repository:

Person person = new Person();
person.setUid("uid:1");
person.setSuerName("AAA");
person.setCommonName("aaa");
person.setUserPassword("123456");
personRepository.save(person);

For more operations, refer to the Spring Data LDAP documentation.

Connect to an LDAP Server

The example above uses an embedded LDAP server for local testing. In a production environment you would connect to a standalone LDAP server. Configure the following properties to switch to a remote server:

spring.ldap.urls=ldap://localhost:1235
spring.ldap.base=dc=didispace,dc=com
spring.ldap.username=didispace
spring.ldap.password=123456

Stay tuned for the next article on integrating Spring Security with LDAP!