Shiro 的 LDAP 认证

Shiro 的 LDAP 认证方式详解

Apache Shiro 提供了对 LDAP（轻量级目录访问协议）的集成支持，用于企业级系统的集中式身份认证。以下是 Shiro 中实现 LDAP 认证的完整指南，包括配置、代码示例和关键点说明。

1. LDAP 认证基础

• 作用：通过 LDAP 服务器（如 Active Directory、OpenLDAP）验证用户凭据（用户名/密码）。
• 优势：
  • 集中式用户管理，无需在应用中维护密码。
  • 支持企业级目录服务，便于集成现有系统。

2. Shiro LDAP 认证实现步骤

(1) 添加依赖

确保项目中包含 Shiro 和 LDAP 相关依赖（以 Maven 为例）：

<dependency>
    <groupId>org.apache.shiro</groupId>
    <artifactId>shiro-core</artifactId>
    <version>1.12.0</version> <!-- 使用最新版本 -->
</dependency>
<dependency>
    <groupId>org.apache.shiro</groupId>
    <artifactId>shiro-ldap</artifactId>
    <version>1.12.0</version>
</dependency>

(2) 配置 shiro.ini 文件

通过 shiro.ini 配置 LDAP 认证的核心参数：

[main]
# 配置 LDAP Realm
ldapRealm = org.apache.shiro.realm.ldap.JndiLdapRealm
ldapRealm.contextFactory.url = ldap://ldap.example.com:389  # LDAP 服务器地址
ldapRealm.contextFactory.authenticationMechanism = simple    # 认证机制（simple/DIGEST-MD5）
ldapRealm.userDnTemplate = uid={0},ou=users,dc=example,dc=com # 用户 DN 模板
ldapRealm.searchBase = dc=example,dc=com                     # 搜索基路径
ldapRealm.systemUsername = cn=admin,dc=example,dc=com        # 系统管理员 DN（用于搜索）
ldapRealm.systemPassword = admin123                          # 系统管理员密码

# 可选：启用调试日志
loggerFactory.logLevel = debug

关键参数说明：

• contextFactory.url：LDAP 服务器地址（如 ldap://ldap.example.com:389）。
• userDnTemplate：用户 DN 模板，{0} 会被替换为用户名。
• searchBase：搜索用户的基路径（如 dc=example,dc=com）。
• systemUsername 和 systemPassword：用于搜索用户的系统管理员凭据（可选，取决于 LDAP 配置）。

(3) 编写 Java 代码进行认证

import org.apache.shiro.SecurityUtils;
import org.apache.shiro.authc.UsernamePasswordToken;
import org.apache.shiro.config.IniSecurityManagerFactory;
import org.apache.shiro.mgt.SecurityManager;
import org.apache.shiro.subject.Subject;
import org.apache.shiro.util.Factory;

public class LdapAuthDemo {
    public static void main(String[] args) {
        // 初始化 SecurityManager
        Factory<SecurityManager> factory = new IniSecurityManagerFactory("classpath:shiro.ini");
        SecurityManager securityManager = factory.getInstance();
        SecurityUtils.setSecurityManager(securityManager);

        // 获取当前用户
        Subject currentUser = SecurityUtils.getSubject();

        // 创建用户名/密码 Token
        UsernamePasswordToken token = new UsernamePasswordToken("user1", "password123");

        try {
            // 执行认证
            currentUser.login(token);
            System.out.println("LDAP 认证成功！");
        } catch (Exception e) {
            System.out.println("LDAP 认证失败：" + e.getMessage());
        }
    }
}

3. 高级配置

(1) 自定义 LDAP 搜索

如果用户 DN 不能通过模板直接生成，可以自定义搜索逻辑：

[main]
ldapRealm = org.apache.shiro.realm.ldap.JndiLdapRealm
ldapRealm.contextFactory.url = ldap://ldap.example.com:389
ldapRealm.searchBase = dc=example,dc=com
ldapRealm.systemUsername = cn=admin,dc=example,dc=com
ldapRealm.systemPassword = admin123

# 自定义搜索过滤器
ldapRealm.searchFilter = (uid={0})  # 搜索过滤器（默认是 (uid={0})）

(2) 启用 SSL/TLS

如果 LDAP 服务器使用安全连接：

[main]
ldapRealm = org.apache.shiro.realm.ldap.JndiLdapRealm
ldapRealm.contextFactory.url = ldaps://ldap.example.com:636  # 使用 ldaps
ldapRealm.contextFactory.environment[java.naming.security.protocol] = ssl  # 启用 SSL

(3) 结合 Active Directory

Active Directory 的配置略有不同：

[main]
activeDirectoryRealm = org.apache.shiro.realm.activedirectory.ActiveDirectoryRealm
activeDirectoryRealm.url = ldap://ad.example.com:389
activeDirectoryRealm.systemUsername = CN=admin,CN=Users,DC=example,DC=com
activeDirectoryRealm.systemPassword = admin123
activeDirectoryRealm.searchBase = CN=Users,DC=example,DC=com

4. 常见问题与解决方案

(1) 认证失败：Invalid credentials

• 原因：用户名或密码错误，或 LDAP 服务器配置不正确。
• 解决：
  • 检查 userDnTemplate 或 searchFilter 是否正确。
  • 使用工具（如 Apache Directory Studio）测试 LDAP 连接。

(2) 认证失败：Connection refused

• 原因：LDAP 服务器地址或端口错误。
• 解决：
  • 确认 contextFactory.url 是否正确。
  • 检查防火墙是否放行 LDAP 端口（389 或 636）。

(3) 性能问题

• 原因：频繁的 LDAP 查询导致延迟。
• 解决：
  • 使用缓存（如 Shiro 的 CachingRealm）。
  • 优化搜索过滤器，减少返回的数据量。

5. 总结

Shiro 的 LDAP 认证通过 JndiLdapRealm 或 ActiveDirectoryRealm 实现，核心步骤包括：

1. 配置 shiro.ini 文件，设置 LDAP 服务器地址、用户 DN 模板等。
2. 编写 Java 代码，通过 Subject.login() 执行认证。
3. 根据需求调整高级配置（如 SSL、自定义搜索）。

适用场景：

• 企业级应用需要与现有 LDAP/AD 集成。
• 需要集中式用户管理和单点登录（SSO）。

通过合理配置，Shiro 可以轻松实现安全、可靠的 LDAP 认证。