Shiro Token 核心解析与自定义实战指南

原创于 2026-06-30 11:42:18 发布 · 233 阅读

4 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#Shiro #Token #解析 #核心 #实战

基础专栏收录该内容

30 篇文章

订阅专栏

在实际开发中，我们常常遇到这样的场景：标准的用户名密码登录已经无法满足业务需求，系统需要支持手机验证码、第三方授权、甚至硬件密钥等多种认证方式。Apache Shiro 作为经典的权限框架，其默认的 UsernamePasswordToken 虽然好用，但面对这些非传统凭证时往往显得力不从心。很多开发者在尝试扩展时，容易陷入“强行复用旧逻辑”或“过度修改核心源码”的误区，导致代码耦合度高且难以维护。

其实，Shiro 的设计哲学非常灵活，它早已为自定义认证留好了扩展点。关键在于理解 Token 在认证流程中的真实角色——它不仅仅是一个数据载体，更是连接前端请求与后端 Realm 校验的桥梁。只要我们能定义好自己的 Token 结构，并告诉 Shiro 如何识别和匹配它，就能轻松实现任意形式的身份验证，而无需动摇框架的根基。

本文将深入 Shiro 的认证内核，从 Token 的核心定位出发，一步步带你实现一个完整的自定义认证流程。我们会涵盖从定义新型 Token 类、编写专属匹配逻辑，到配置 Realm 和支持多类型并发处理的全链路实践。无论你是想接入短信登录，还是需要对接内部单点系统，这套方法论都能提供可落地的解决方案，帮助你在保证安全的前提下，构建出优雅且可扩展的认证模块。

① Shiro 认证流程中 Token 的核心定位

在 Shiro 的架构体系中，Token（令牌）处于认证流程的最前端，它是 Subject（主体）向 SecurityManager 提交的身份凭证抽象。当用户发起登录请求时，无论携带的是账号密码、短信验证码还是 OAuth 票据，首先都需要被封装成一个 Token 对象。这个对象随后被传递给 Authenticator（认证器），由它调度相应的 Realm 进行数据比对。

Token 的核心价值在于“解耦”。它将具体的认证数据格式与底层的校验逻辑分离开来。对于 Shiro 内核而言，它只关心 Token 的类型及其提供的信息接口，而不关心这些数据具体来自 HTTP 请求头、表单参数还是 RPC 调用。这种设计使得我们可以自由地定义新的凭证类型，只要遵循 Shiro 的接口规范，就能无缝插入现有的认证链条中。理解这一点，是后续所有自定义操作的基石：Token 不是简单的数据传输对象（DTO），而是驱动整个认证状态机流转的关键钥匙。

② 主流 Token 类型特性与适用场景

Shiro 原生提供了 UsernamePasswordToken，适用于最基础的账户密码场景。它的结构简单，包含 principal（principal 通常指用户名）和 credentials（密码）两个核心字段，且内置了“记住我”功能的支持。然而，在现代微服务架构中，单一的用户名密码模式已显单薄。

针对不同的业务场景，我们需要不同类型的 Token：

短信验证码场景：此时 principal 是手机号，credentials 是动态验证码。由于验证码具有时效性且通常是一次性的，这类 Token 不需要“记住我”功能，且校验逻辑需依赖缓存中间件。
第三方授权场景：例如微信或 GitHub 登录，principal 可能是 OpenID，credentials 则是 Access Token。这类 Token 的校验往往需要发起远程 HTTP 请求换取用户信息。
硬件或证书场景：principal 可能是设备序列号或证书指纹，credentials 是签名数据。

选择何种 Token 类型，取决于凭证的来源形式以及后端 Realm 的数据存储结构。如果强行将手机号塞入 UsernamePasswordToken 的用户名字段，虽然技术上可行，但会导致语义混淆，增加后续维护成本。因此，为特定场景定制专属 Token 类是最佳实践。

③ 自定义 Token 类的结构与代码实现

要支持新的认证方式，第一步是创建一个继承自 AuthenticationToken 接口的类。这个接口非常简单，主要要求实现 getPrincipal() 和 getCredentials() 两个方法。我们以“手机验证码登录”为例，定义一个 SmsCodeToken。

public class SmsCodeToken implements AuthenticationToken {
    
    private final String phoneNumber;
    private final String verificationCode;

    public SmsCodeToken(String phoneNumber, String verificationCode) {
        this.phoneNumber = phoneNumber;
        this.verificationCode = verificationCode;
    }

    @Override
    public Object getPrincipal() {
        // Principal 通常是唯一标识用户的字段，这里是手机号
        return phoneNumber;
    }

    @Override
    public Object getCredentials() {
        // Credentials 是用于比对的凭证，这里是验证码
        return verificationCode;
    }
}

在这个实现中，我们并没有引入复杂的继承关系，而是直接实现接口。这样做的好处是灵活性极高，可以根据需要在类中添加额外的上下文信息，比如 IP 地址、设备指纹等，供后续 Realm 校验时使用。注意，getPrincipal() 返回的对象类型应当与 Realm 中查询用户时使用的唯一标识类型保持一致，这是后续匹配成功的关键。

④ 编写专属 Authenticator 匹配逻辑

有了自定义 Token，接下来需要解决“如何校验”的问题。Shiro 默认的 SimpleAuthenticator 会遍历配置的 Realm，但具体的比对逻辑是由 Realm 内部的 CredentialsMatcher 决定的。对于自定义 Token，我们通常需要自定义匹配器。

我们需要实现 CredentialsMatcher 接口，重写 doCredentialsMatch 方法。在这个方法中，我们可以获取到传入的 Token 和 Realm 返回的账户信息（AuthenticationInfo），然后执行特定的比对逻辑。

public class SmsCodeMatcher implements CredentialsMatcher {
    
    @Override
    public boolean doCredentialsMatch(AuthenticationToken token, AuthenticationInfo info) {
        if (!(token instanceof SmsCodeToken)) {
            return false;
        }
        
        SmsCodeToken smsToken = (SmsCodeToken) token;
        String inputCode = (String) smsToken.getCredentials();
        
        // 从 AccountInfo 中获取存储在 Redis 中的正确验证码
        String storedCode = (String) info.getCredentials();
        
        if (storedCode == null || !storedCode.equals(inputCode)) {
            return false;
        }
        
        // 验证成功后，可选操作：立即使验证码失效（防止重放攻击）
        // invalidateCode(smsToken.getPrincipal()); 
        
        return true;
    }
}

这段代码清晰地展示了类型检查、凭证提取和比对过程。值得注意的是，这里的 info.getCredentials() 返回的内容完全由我们在 Realm 的 doGetAuthenticationInfo 方法中决定，它可以是数据库查出的密码，也可以是 Redis 中的验证码，甚至是远程服务返回的状态标记。

⑤ 配置 Realm 以支持新 Token 类型

Realm 是 Shiro 与现实世界安全数据之间的桥梁。为了支持 SmsCodeToken，我们需要自定义一个 Realm，并在其中处理该类型的 Token。重点在于 doGetAuthenticationInfo 方法，该方法负责根据 Token 中的 Principal 加载用户数据。

public class CustomRealm extends AuthorizingRealm {

    @Override
    protected AuthorizationInfo doGetAuthorizationInfo(PrincipalCollection principals) {
        // 授权逻辑，此处省略
        return null;
    }

    @Override
    protected AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token) 
            throws AuthenticationException {
        
        if (!(token instanceof SmsCodeToken)) {
            // 如果不是本 Realm 支持的 Token 类型，返回 null，让 Shiro 尝试其他 Realm
            return null;
        }

        SmsCodeToken smsToken = (SmsCodeToken) token;
        String phone = (String) smsToken.getPrincipal();

        // 1. 根据手机号查询用户是否存在（伪代码）
        User user = userService.findByPhone(phone);
        if (user == null) {
            throw new UnknownAccountException("用户不存在");
        }

        // 2. 从缓存中获取正确的验证码
        String correctCode = redisTemplate.opsForValue().get("sms:" + phone);
        if (correctCode == null) {
            throw new ExpiredCredentialsException("验证码已过期");
        }

        // 3. 构造 AuthenticationInfo
        // 第三个参数传入正确验证码，交由 Matcher 进行比对
        return new SimpleAuthenticationInfo(user, correctCode, getName());
    }
}

在此配置中，我们首先判断 Token 类型，确保当前 Realm 只处理自己负责的凭证。接着，利用 Principal（手机号）去加载必要的用户信息和校验数据。最后返回的 SimpleAuthenticationInfo 中，我们将正确的验证码放入 credentials 位置，这样上一步编写的 SmsCodeMatcher 就能拿到两边数据进行比对了。

⑥ 构建完整登录调用的可运行示例

完成上述组件后，我们需要在 Spring 环境或标准 Java 环境中将它们组装起来。核心是将自定义的 Realm 和 Matcher 注入到 SecurityManager 中。

// 配置 SecurityManager
DefaultSecurityManager securityManager = new DefaultSecurityManager();

// 实例化自定义 Realm
CustomRealm customRealm = new CustomRealm();

// 设置自定义匹配器
customRealm.setCredentialsMatcher(new SmsCodeMatcher());

// 将 Realm 注册到 Manager
securityManager.setRealms(Collections.singletonList(customRealm));

// 绑定到当前线程（Web 环境通常由 ShiroFilter 自动完成）
SecurityUtils.setSecurityManager(securityManager);

// --- 模拟登录调用 ---
try {
    Subject subject = SecurityUtils.getSubject();
    // 构建自定义 Token
    AuthenticationToken token = new SmsCodeToken("13800138000", "123456");
    
    // 执行登录
    subject.login(token);
    
    System.out.println("登录成功，用户 ID: " + subject.getPrincipal());
} catch (UnknownAccountException e) {
    System.out.println("用户不存在");
} catch (ExpiredCredentialsException e) {
    System.out.println("验证码过期");
} catch (IncorrectCredentialsException e) {
    System.out.println("验证码错误");
}

这段示例展示了从环境搭建到实际调用的全过程。关键点在于 subject.login(token) 这一行，它触发了整个认证链。一旦验证通过，Subject 对象就会进入“已认证”状态，后续即可通过 subject.isAuthenticated() 判断登录状态。

⑦ 验证自定义 Token 的认证结果

登录完成后，验证结果是至关重要的环节。除了检查 subject.isAuthenticated() 布尔值外，我们还应关注异常捕获机制。Shiro 会在认证失败时抛出特定的子类异常，如 UnknownAccountException（账号未知）、IncorrectCredentialsException（凭证错误）、LockedAccountException（账号锁定）等。

在自定义场景下，我们可以在 doGetAuthenticationInfo 或 doCredentialsMatch 中主动抛出这些异常，或者抛出自定义的运行时异常，以便前端精确提示用户。例如，当 Redis 中找不到验证码时，抛出 ExpiredCredentialsException 比通用的认证失败更能指导用户重新发送验证码。此外，可以通过监听 Shiro 的事件机制，记录登录成功的审计日志，包括登录时间、IP 以及使用的 Token 类型，为安全分析提供数据支撑。

⑧ 常见实例化错误与类型转换排查

在实施自定义 Token 过程中，最容易遇到的问题是 ClassCastException 或认证始终失败。这通常源于类型判断的疏漏。

首先，在 Realm 的 doGetAuthenticationInfo 方法中，务必先执行 instanceof 检查。如果一个应用中配置了多个 Realm（例如一个处理用户名密码，一个处理短信），当用户名密码 Token 流经短信 Realm 时，如果不做类型判断直接强转，程序就会崩溃。正确的做法是：发现类型不匹配直接返回 null，让 Shiro 继续尝试下一个 Realm。

其次，检查 getPrincipal() 返回的类型一致性。如果在 Token 中返回的是 String 类型的手机号，而在 Realm 查询数据库时也期望 String，这没问题；但如果一方是 Long 类型 ID，另一方是 String，可能导致查询失败或匹配器逻辑错误。保持 Principal 在整个链路中的类型统一，能减少大量隐蔽的 Bug。

⑨ 多 Token 并发处理的进阶技巧

随着业务发展，系统可能需要同时支持多种登录方式。Shiro 天然支持多 Realm 策略。我们可以配置一个 ModularRealmAuthenticator，并设置适当的认证策略（如 AtLeastOneSuccessfulStrategy，即只要有一个 Realm 成功即可）。

在这种架构下，每个 Realm 专注于一种 Token 类型。例如，PasswordRealm 只处理 UsernamePasswordToken，SmsRealm 只处理 SmsCodeToken。当用户发起登录时，Authenticator 会依次调用各个 Realm。为了提高性能，可以在每个 Realm 的入口处快速失败：一旦发现 Token 类型不属于自己，立即返回 null，避免不必要的数据库查询或网络请求。这种“各司其职”的设计模式，使得系统能够灵活扩展新的认证方式，而无需修改现有代码，符合开闭原则。

⑩ 生产环境下的 Token 安全最佳实践

在生产环境中，自定义 Token 的安全性不容忽视。首先是凭证的传输安全，无论 Token 内部结构如何，都必须通过 HTTPS 传输，防止中间人窃听。其次是防重放攻击，特别是对于短信验证码或一次性票据，校验成功后应立即销毁服务端存储的凭证，确保同一凭证只能使用一次。

另外，建议在 Token 中加入随机盐值或时间戳签名，增加伪造难度。对于敏感操作，不要仅依赖 Token 中的信息，应在 Realm 中二次确认用户状态（如是否被冻结、密码是否强制重置）。最后，严格控制日志输出，严禁将 Token 中的 credentials（如密码、验证码）打印到日志文件中，以免泄露敏感信息。通过层层防御，才能确保自定义认证机制既灵活又坚固。