在企业内部，往往同时运行着OA、Wiki、邮件、CRM等多套系统，如果每个系统各自维护一套账号，管理员要重复建号、员工要记多套密码，离职删号漏掉一个就是安全隐患。LDAP（Lightweight Directory Access Protocol，轻量级目录访问协议）正是为解决这类问题而生，它把用户和组织信息集中存储在目录树中，Active Directory、OpenLDAP都是常见的LDAP服务器实现。本文将演示如何在Spring Boot项目中整合Spring LDAP，完成连接配置、用户查询、密码认证以及与Spring Security的整合。
一、准备工作与依赖引入
在动手写代码之前，先要明确目标LDAP服务器的信息：主机地址、端口（默认389，加密连接用636）、Base DN（例如dc=example,dc=ipipp,dc=com）、管理账号DN以及密码。如果你本地没有LDAP服务器，可以用Docker快速启动一个OpenLDAP用于测试，几分钟就能搭好环境。
在Spring Boot项目中整合LDAP非常简单，引入spring-boot-starter-data-ldap即可，它会自动带上Spring LDAP核心包和嵌入式LDAP测试支持。Maven依赖如下：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-ldap</artifactId>
</dependency>如果需要与Spring Security整合做登录认证，还需要额外引入spring-boot-starter-security。这里要注意版本兼容问题，Spring Boot 2.x和3.x对应的Spring LDAP API有差异，主要体现在javax包换成了jakarta包，写代码时要与项目版本匹配，否则编译会报找不到类的错误。
二、配置LDAP连接与目录结构
连接信息统一放在application.yml中管理，Spring Boot会自动根据这些配置创建LdapContextSource并注入容器。配置示例如下：
spring:
ldap:
urls: ldap://127.0.0.1:389
base: dc=example,dc=ipipp,dc=com
username: cn=admin,dc=example,dc=ipipp,dc=com
password: your-password这里有两个容易踩坑的地方。第一，base配置之后，后续所有查询的DN都会自动拼上这个前缀，查询时传入的相对路径不要重复携带base，否则会抛出PartialResultException或查不到数据。第二，如果目标是Active Directory，用户名通常写user@domain.com形式的UPN，而不是DN，这点与OpenLDAP不同。
了解LDAP的目录结构对后续查询至关重要。典型结构是用户放在ou=people下，分组放在ou=group下，用户的DN形如uid=zhangsan,ou=people,dc=example,dc=ipipp,dc=com。用户的唯一标识属性常见有uid、sAMAccountName（AD专用）、cn等，认证前要先确认服务器用的是哪一种属性，可以通过ldapsearch命令或Apache Directory Studio工具查看真实数据。
三、使用LdapTemplate查询和认证用户
Spring LDAP提供了LdapTemplate这个核心工具类，封装了查询、绑定、修改等操作，可以直接注入使用。下面演示根据用户名查询用户信息并映射为实体类：
@Data
@Entry(base = "ou=people", objectClasses = {"inetOrgPerson", "top"})
public class Person {
@Id
private Name dn;
@Attribute(name = "uid")
private String uid;
@Attribute(name = "cn")
private String cn;
@Attribute(name = "sn")
private String sn;
@Attribute(name = "mail")
private String mail;
}
@Service
public class LdapUserService {
@Autowired
private LdapTemplate ldapTemplate;
public Person findByUid(String uid) {
return ldapTemplate.findOne(
LdapQueryBuilder.query()
.where("uid").is(uid),
Person.class);
}
}上面的@Entry注解声明了实体与LDAP节点的映射关系，LdapQueryBuilder负责拼装过滤条件，整体用法类似JPA，学习成本很低。如果不想定义实体类，也可以用ldapTemplate.search()配合AttributesMapper手动提取属性，灵活度更高。
认证的本质是拿着用户的DN和明文密码去LDAP服务器做一次绑定操作，绑定成功即密码正确。Spring LDAP提供了封装好的方法：
@Service
public class LdapAuthService {
@Autowired
private LdapContextSource contextSource;
public boolean authenticate(String uid, String password) {
// 先查出用户的完整DN，再用DN加密码做绑定验证
AndFilter filter = new AndFilter();
filter.and(new EqualsFilter("uid", uid));
return contextSource.getContext(
"uid=" + uid + ",ou=people,dc=example,dc=ipipp,dc=com",
password) != null;
}
}更简洁的做法是使用LdapTemplate.authenticate(String base, String filter, String password)方法，它内部会先根据filter搜索用户，找到DN后再尝试绑定，一步完成认证。需要强调的是，LDAP的密码校验必须走绑定流程，服务器存储的是不可逆散列，应用端拿不到明文，也无法在应用侧自行比对，这一点与数据库存密码的方式完全不同。
四、与Spring Security整合实现统一登录
实际项目中很少手写认证逻辑，更常见的做法是把LDAP接入Spring Security，让整个登录体系交给安全框架托管。Spring Security内置了LdapAuthenticationProvider，配置方式如下：
@Configuration
public class LdapSecurityConfig {
@Bean
AuthenticationProvider ldapAuthProvider(BaseLdapPathContextSource contextSource) {
BindAuthenticator bindAuth = new BindAuthenticator(contextSource);
bindAuth.setUserSearch(new FilterBasedLdapUserSearch(
"ou=people", "(uid={0})", contextSource));
LdapAuthenticationProvider provider =
new LdapAuthenticationProvider(bindAuth);
return provider;
}
@Bean
SecurityFilterChain filterChain(HttpSecurity http,
AuthenticationProvider ldapAuthProvider) throws Exception {
http.authorizeHttpRequests(auth -> auth
.anyRequest().authenticated())
.formLogin(Customizer.withDefaults())
.authenticationProvider(ldapAuthProvider);
return http.build();
}
}这套配置完成后，应用的用户名密码就完全由LDAP服务器统一管理了。员工入职只需在目录里建一个账号，即可登录所有接入LDAP的系统；离职删除账号后所有系统同时失效，安全性大幅提升。
如果还需要基于分组控制权限，可以再加一个DefaultLdapAuthoritiesPopulator，指定分组所在的OU和成员属性（OpenLDAP通常是member，AD常用memberOf），登录成功后用户的分组会被自动映射为ROLE_前缀的角色，配合hasRole即可做细粒度授权。
五、常见问题排查思路
整合LDAP时最常见的问题有三类。第一类是连接失败，报CommunicationException，此时要检查地址端口是否可达、防火墙是否放行，必要时用telnet host 389验证端口连通性。第二类是认证报错InvalidNameException或PartialResultException，多半是base DN配置重复或AD跨域引用问题，可以在连接串后加ldap://host:389/dc=example,dc=ipipp,dc=com形式明确指定，并设置referral属性为follow。
第三类是查得到用户但认证始终失败，这时要确认目标服务器的密码策略和加密方式。有些OpenLDAP默认禁用匿名绑定，也有些服务器对简单认证做了限制，需要启用simple认证模式或改用SSL的636端口。建议开启logging.level.org.springframework.ldap=DEBUG，日志里会打印实际的搜索和绑定过程，定位问题效率会高很多。
总的来说，Spring Boot整合LDAP的门槛不高，核心就是连接配置、LdapTemplate操作和认证绑定这三块。掌握之后，无论是做内部统一登录平台，还是对接企业已有的Active Directory，都可以按这套思路快速落地。
Spring BootLDAP统一认证修改时间：2026-09-09 12:15:11