企业内部系统一旦超过三五个，账号管理就容易变成一件头疼的事。每个应用都维护自己的用户表，新员工入职要在所有系统里开账号，离职时又得逐一禁用，漏掉一个就可能留下安全后门。LDAP（轻量级目录访问协议）作为成熟的目录服务标准，天然适合存放组织架构和人员身份信息。Spring Boot通过spring-ldap和Spring Security的LDAP模块，可以很自然地与OpenLDAP、Active Directory等目录服务器对接，完成统一身份认证和组织数据同步。
本文假设你已经有可用的LDAP服务，无论是本地用Docker起的OpenLDAP，还是公司已有的AD域控。认证流程的核心是：用户提交用户名密码后，Spring Security先尝试绑定LDAP目录，验证通过再读取该用户的角色和所属组织信息，用于后续授权。组织同步则是指定期或实时把LDAP中的部门结构、人员变更拉取到业务数据库，保证本地缓存与目录一致。
一、项目依赖与LDAP连接配置
在Spring Boot工程里引入两个核心依赖：spring-boot-starter-data-ldap负责LDAP操作模板和仓库支持，spring-boot-starter-security则用于接入认证流程。如果你使用Maven，pom.xml中增加如下内容。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-ldap</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
application.yml中配置LDAP服务器的地址、认证账号以及搜索基准路径。这里的base必须与你的目录结构对应，例如公司根节点dn为dc=example,dc=com，用户都放在ou=users下面，那么user-dn-patterns可以写成uid={0},ou=users。注意url中的协议要写ldap或ldaps，端口默认389或636。
spring:
ldap:
urls: ldap://192.168.10.20:389
base: dc=example,dc=com
username: cn=admin,dc=example,dc=com
password: admin123
base-environment:
com.sun.jndi.ldap.connect.timeout: 5000
如果公司目录规模较大，建议使用连接池来避免频繁创建LDAP上下文。Spring LDAP默认使用PoolingContextSource，可以通过配置调整池大小。更重要的是设置合理的超时，防止LDAP服务抖动时拖垮应用线程。
二、Spring Security集成LDAP认证
认证部分不需要自己写Controller，直接在Security配置类中声明LDAP认证提供者即可。需要自定义一个LdapUserDetailsMapper，把LDAP属性映射为Spring Security的UserDetails对象，通常包含用户名、显示名、邮箱以及权限列表。这里给出一个基于内存权限映射的简单示例，实际项目建议从LDAP的group属性读取角色。
@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
@Autowired
private LdapContextSource contextSource;
@Override
protected void configure(AuthenticationManagerBuilder auth) throws Exception {
auth.ldapAuthentication()
.userDnPatterns("uid={0},ou=users")
.contextSource(contextSource)
.userDetailsContextMapper(userDetailsContextMapper());
}
@Bean
public UserDetailsContextMapper userDetailsContextMapper() {
return new LdapUserDetailsMapper() {
@Override
public UserDetails mapUserFromContext(DirContextOperations ctx,
String username, Collection<? extends GrantedAuthority> authorities) {
String email = ctx.getStringAttribute("mail");
String displayName = ctx.getStringAttribute("cn");
return new User(username, "", authorities);
}
};
}
@Override
protected void configure(HttpSecurity http) throws Exception {
http.authorizeRequests()
.antMatchers("/login", "/css/**").permitAll()
.anyRequest().authenticated()
.and()
.formLogin().loginPage("/login").permitAll();
}
}
上面示例中只返回了用户名和权限，没有用到密码字段，因为LDAP认证已经在过滤器内部完成了绑定校验。如果你需要把用户的部门编码、工号等信息一并带入Security上下文，可以扩展UserDetails类或使用自定义Principal。userDnPatterns方式适用于所有用户在同一ou下的简单结构；如果用户分布在多个组织单元，则改用userSearchBase和userSearchFilter组合。
另一种常见做法是使用BindAuthenticator手动进行认证，适用于需要自己管理登录流程、而不是完全交给Spring Security过滤器的场景。比如移动端REST接口返回JWT时，可以先调用LdapTemplate的authenticate方法校验账号密码，成功后再签发token。
三、组织架构同步与用户数据拉取
统一认证只是第一步，业务系统往往还需要展示组织树、根据部门过滤数据。LDAP中组织单位（organizationalUnit）和用户（inetOrgPerson）是两类主要对象，我们可以通过LdapTemplate的search方法遍历。以下代码演示了如何递归获取所有部门节点以及某部门下的全部员工。
@Service
public class LdapSyncService {
@Autowired
private LdapTemplate ldapTemplate;
public List<OrgNode> fetchOrgTree(String baseDn) {
List<OrgNode> nodes = new ArrayList<>();
ldapTemplate.search(baseDn, "(objectClass=organizationalUnit)",
new AttributesMapper<OrgNode>() {
public OrgNode mapFromAttributes(Attributes attrs) throws NamingException {
OrgNode node = new OrgNode();
node.setDn(attrs.get("distinguishedName").get().toString());
node.setName(attrs.get("ou").get().toString());
return node;
}
}).forEach(node -> {
nodes.add(node);
// 递归子部门
nodes.addAll(fetchOrgTree(node.getDn()));
});
return nodes;
}
public List<LdapUser> fetchUsersByDept(String deptDn) {
return ldapTemplate.search(deptDn, "(objectClass=inetOrgPerson)",
(Attributes attrs) -> {
LdapUser u = new LdapUser();
u.setUsername(attrs.get("uid").get().toString());
u.setName(attrs.get("cn").get().toString());
u.setEmail(attrs.get("mail") != null ? attrs.get("mail").get().toString() : "");
return u;
});
}
}
全量同步可以直接把上面的方法挂到定时任务里，每次清空本地部门表和用户缓存再重新导入。但组织规模上千人以后，全量同步会加重LDAP服务器负担，推荐使用增量方式：记录上次同步时间，通过LDAP的modifyTimestamp或createTimestamp属性查询变更记录。部分目录服务支持持久搜索控件（Persistent Search Control），可以做到接近实时的变更推送，但OpenLDAP默认未开启，需要额外配置。
同步过程中的一个关键点是数据映射。LDAP中的DN是层级路径，业务表通常用parentId表示上下级。拉取到DN后需要解析出父级DN，例如ou=开发部,ou=技术中心,dc=example,dc=com的父级是ou=技术中心,dc=example,dc=com。解析时注意转义字符的处理，比如逗号、等号出现在组织名称中时，DN中会用反斜杠转义。
四、常见问题与性能优化建议
连接LDAP最常见的报错是“javax.naming.CommunicationException: Connection timed out”。排查顺序：先确认url和端口是否可达，再用ldapsearch命令行测试；如果防火墙放行但仍有超时，检查应用服务器的DNS解析是否正常，以及LDAP服务器是否开启了连接数限制。另一个高频问题是base DN写错，导致搜索返回空结果，建议先在Apache Directory Studio里验证过滤器。
生产环境强烈建议使用ldaps协议并配置证书信任。如果证书是自签名的，需要把LDAP服务器证书导入到JVM的truststore中，或者使用LdapContextSource的TLS配置忽略信任校验（不推荐）。连接池参数也要根据并发量调整，默认最大活跃连接数可能不够，spring.ldap的pool配置项可以覆盖。
对于认证频繁但用户数据变更不频繁的系统，可以在本地增加一层用户信息缓存。认证成功后把LDAP返回的displayName、email、部门编码写入Redis，有效期设成10分钟；后续请求优先读缓存，既能降低LDAP压力，也能在网络抖动时提供降级体验。组织同步任务可以放在凌晨低峰执行，同时结合消息队列通知下游服务刷新权限。
如果公司已经使用AD域，需要注意AD的objectClass与OpenLDAP不同，用户类是user，组织单位是organizationalUnit，搜索过滤器也要改为(&(objectClass=user)(sAMAccountName={0}))。AD的组成员关系存放在memberOf属性中，读取时需要显式请求该属性，否则默认不返回。
