Sa-Token v1.42.0 发布，新增 API Key、TOTP 验证码等能力

liuian 2025-09-18 03:45 17 浏览

Sa-Token 是一款免费、开源的轻量级 Java 权限认证框架，主要解决：登录认证、权限认证、单点登录、OAuth2.0、微服务网关鉴权 等一系列权限相关问题。

目前最新版本 v1.42.0 已推送至 Maven 中央仓库 ，大家可以通过如下方式引入：

<!-- Sa-Token 权限认证 -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-boot-starter</artifactId>
    <version>1.42.0</version>
</dependency>

该版本包含大量新增特性、底层重构、代码优化等，下面容我列举几条比较重要的更新内容供大家参阅：

更新点1：新增 API Key 模块

如果你曾经对接过 ChatGPT、DeepSeek 等大模型平台的开放接口，那你一定对 API Key 不陌生。

API Key 是一种接口调用密钥，类似于会话 token ，但比会话 token 具有更灵活的权限控制。

本次更新带来了 API Key 的全流程管理，支持为指定账号签发、校验、禁用、删除 API Key 。
同时每个 API Key 都可以单独设置不同的 scope 权限，以便在不同的场景下使用不同的 API Key，做到秘钥相互隔离，最小化授权。

为了更好的展示此模块的能力，我们专门制作了一个 demo 示例：

sa-api-key

示例仓库地址：sa-token-demo-apikey

在这个示例中，你可以登录测试不同的账号，并为它们签发 API Key，设置 scope 权限，并使用不同的 API Key 测试调用接口，观察响应结果。

框架默认将所有 API Key 信息保存在缓存中，这可以称之为“缓存模式”，在这种模式下，重启缓存库后，数据将会丢失。

框架预留了 SaApiKeyDataLoader 接口，以便你将数据的加载切换为 “数据库模式”，做到数据长久有效保存。

在线文档直达地址：API Key 接口调用秘钥

更新点2：重构 TempToken 模块新增 value 反查机制

在 Sa-Token 文档中有一段这样的示例：

sa-refresh-token

该示例演示了如何通过临时 Token 认证模块，创建 RefreshToken 为登录会话做到双 Token 的效果。

但是有一天我在官网 sa-token 小助手接收到一位用户的咨询：

sa-refresh-token-wnglian-zixun

该用户指出，是否可以为 RefreshToken 提供反查机制，以便获取某个账号历史签发的全部 RefreshToken。

必须安排！

此次版本更新，允许程序在创建 refresh-token 时，指定第三个参数，该参数表示是否允许框架记录 Token 索引信息：

SaTempUtil.createToken("10001", 2592000, true);

指定为 false 代表不记录索引，只生成 token，指定为 true 代表记录索引信息，以便日后可以通过 value 反查历史签发的所有 token。

例如我们可以通过 SaTempUtil.getTempTokenList("xxx") 方法获取指定账号所有历史签发的 RefreshToken 记录：

List<String> refreshTokenList = SaTempUtil.getTempTokenList("10001");

在线文档直达地址：临时 Token 令牌认证

更新点3：新增 TOTP 算法实现

TOTP 是一种动态密码算法，用于生成短暂有效的数字验证码（通常6-8位）。它的核心原理是：结合密钥与当前时间，通过哈希运算生成一次性密码。

TOTP 一般有以下应用场景：

o 1、登录时的双因子认证：用户输入账号密码后还需要再输入 TOTP 验证码才可以登录成功。
o 2、敏感操作的二次认证：用户在进行一些高危敏感操作时，需要输入 TOTP 验证码才可以继续操作。
o 3、替代短信验证码：TOTP 验证码无需网络，可离线计算生成，一定程度上可以替代短信验证码验证身份。

本次版本新增了 TOTP 验证码的生成与校验功能，这将方便大家为自己的系统添加双因子认证能力。

更新点4：重构升级SaTokenContext上下文读写策略

这可能是近几个版本中最底层的一次重构，几乎完全推翻了之前上下文模块的设计。

在之前的版本中，Sa-Token 对接不同的 Web 框架需要利用这些 Web 框架的原生上下文能力来构建 Sa-Token 的上下文。

本次更新 Sa-Token 利用 ThreadLocal 实现了自己的上下文存储机制，这将带来以下好处：

o 1、可以更方便、更简单的对接更多的 Web 框架。
o 2、可在异步场景中临时 Mock 一个上下文，调用 Sa-Token 框架同步 API。
o 3、彻底删除了二级上下文模块，做到了 Web 请求与 RPC 请求的上下文统一。
o 4、在防火墙 hook 里也可以调用 Sa-Token 同步 API 了。

更新点5：新增CORS跨域策略处理函数，提供不同架构下统一的跨域处理方案

在之前的版本中，跨域处理总是要写在全局鉴权过滤器中，属于“鉴权之下的额外补充操作”。

新版本专门提供了一个 CORS 跨域处理策略组件，以后再也不用仅仅为了跨域就书写一个长长的鉴权过滤器组件了。

/**
 * CORS 跨域处理
 */
@Bean
public SaCorsHandleFunction corsHandle() {
    return (req, res, sto) -> {
        res.
                // 允许指定域访问跨域资源
                setHeader("Access-Control-Allow-Origin", "*")
                // 允许所有请求方式
                .setHeader("Access-Control-Allow-Methods", "POST, GET, OPTIONS, DELETE")
                // 有效时间
                .setHeader("Access-Control-Max-Age", "3600")
                // 允许的header参数
                .setHeader("Access-Control-Allow-Headers", "*");

        // 如果是预检请求，则立即返回到前端
        SaRouter.match(SaHttpMethod.OPTIONS)
                .free(r -> System.out.println("--------OPTIONS预检请求，不做处理"))
                .back();
    };
}

开源仓库示例：sa-token-demo-cross

更新点6：sa-token-quick-login插件支持Http Basic方式通过认证

sa-token-quick-login 可以快速、方便的为项目注入一个登录页面，当我们引入依赖后：

<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-quick-login</artifactId>
    <version>1.42.0</version>
</dependency>

启动类：

@SpringBootApplication
public class SaTokenQuickDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(SaTokenQuickDemoApplication.class, args);
        
        System.out.println("\n------ 启动成功 ------");
        System.out.println("name: " + SaQuickManager.getConfig().getName());
        System.out.println("pwd:  " + SaQuickManager.getConfig().getPwd());
    }
}

测试 Controller

@RestController
public class TestController {
    @RequestMapping({"/", "/index"})
    public String index() {
        String str = "<br />"
                + "<h1 style='text-align: center;'>资源页 （登录后才可进入本页面） </h1>"
                + "<hr/>"
                + "<p style='text-align: center;'> Sa-Token " + SaTokenConsts.VERSION_NO + " </p>";
        return str;
    }
}

启动项目，使用浏览器访问：http://localhost:8081，首次访问时，由于处于未登录状态，会被强制进入登录页面：

使用默认账号：sa / 123456进行登录，会看到资源页面

新版本中更新了通过 Http Basic 的方式直接进行认证的能力：

http://sa:123456@localhost:8081/

这将非常有助于大家在专门的 API 测试工具下进行 quick-login 相关资源接口的测试。

完整更新日志

除了以上提到的几点以外，还有更多更新点无法逐一详细介绍，下面是 v1.42.0 版本的完整更新日志：

o core:

o 新增: 新增 API Key 模块。 [重要]
o 新增: 新增 TOTP 实现。 [重要]
o 重构：重构 TempToken 模块，新增 value 反查 token 机制。 [重要]
o 升级: 重构升级 SaTokenContext 上下文读写策略。 [重要]
o 新增: 新增 Mock 上下文模块。 [重要]
o 删除: 删除二级上下文模块。
o 新增: 新增异步场景使用 demo。 [重要]
o 新增: 新增 Base32 编码工具类。
o 新增：新增 CORS 跨域策略处理函数，提供不同架构下统一的跨域处理方案。
o 新增：renewTimeout 续期方法增加 token 终端信息有效性校验。
o 新增: 全局配置项 cookieAutoFillPrefix：cookie 模式是否自动填充 token 前缀。
o 新增: 全局配置项 rightNowCreateTokenSession：在登录时，是否立即创建对应的 Token-Session。
o 优化：优化 Token-Session 获取算法，减少缓存读取次数。
o 新增：SaLoginParameter 支持配置 SaCookieConfig，以配置 Cookie 相关参数。
o 修改：防火墙校验过滤器的注册顺序修改为 -102。
o 新增：防火墙 hook 注册新增 registerHookToFirst、registerHookToSecond 方法，以便更灵活的控制 hook 顺序。