Sa-Token v1.42.0 发布 [特殊字符]，新增 API Key、TOTP 验证码、RefreshToken 反查等能力

半瓶榴莲奶

于 2025-05-08 09:08:34 发布

阅读量66

点赞数

合集 - sa-token 专栏(3)

1.Sa-Token 多账号认证：同时为系统的 Admin 账号和 User 账号提供鉴权操作2023-07-24 2.Sa-Token v1.40.0 发布 🚀，来看看有没有令你心动的功能！02-06

3. Sa-Token v1.42.0 发布 🚀，新增 API Key、TOTP 验证码、RefreshToken 反查等能力 04-12

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 一般有以下应用场景：

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

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

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

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

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

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

1、可以更方便、更简单的对接更多的 Web 框架。
2、可在异步场景中临时 Mock 一个上下文，调用 Sa-Token 框架同步 API。
3、彻底删除了二级上下文模块，做到了 Web 请求与 RPC 请求的上下文统一。
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 版本的完整更新日志：

core:
- 新增: 新增 API Key 模块。 [重要]
- 新增: 新增 TOTP 实现。 [重要]
- 重构：重构 TempToken 模块，新增 value 反查 token 机制。 [重要]
- 升级: 重构升级 SaTokenContext 上下文读写策略。 [重要]
- 新增: 新增 Mock 上下文模块。 [重要]
- 删除: 删除二级上下文模块。
- 新增: 新增异步场景使用 demo。 [重要]
- 新增: 新增 Base32 编码工具类。
- 新增：新增 CORS 跨域策略处理函数，提供不同架构下统一的跨域处理方案。
- 新增：renewTimeout 续期方法增加 token 终端信息有效性校验。
- 新增: 全局配置项 cookieAutoFillPrefix：cookie 模式是否自动填充 token 前缀。
- 新增: 全局配置项 rightNowCreateTokenSession：在登录时，是否立即创建对应的 Token-Session。
- 优化：优化 Token-Session 获取算法，减少缓存读取次数。
- 新增：SaLoginParameter 支持配置 SaCookieConfig，以配置 Cookie 相关参数。
- 修改：防火墙校验过滤器的注册顺序修改为 -102。
- 新增：防火墙 hook 注册新增 registerHookToFirst、registerHookToSecond 方法，以便更灵活的控制 hook 顺序。
插件：
- 新增: sa-token-quick-login 插件支持 Http Basic 方式通过认证。
单元测试：
- 补全：补全 Temp Token 模块单元测试。
文档：
- 补全：补全赞助者名单。
- 修复：修复 Thymeleaf 集成文档不正确的依赖示例说明。
- 修复：修复 unionid 章节错误描述。
- 优化：采用更细致的描述优化SSO模式三单点注销步骤。
- 新增：登录认证文档添加 Cookie 查看步骤演示图。
- 新增：多账号模式新增注意点：运行时不可更改 LoginType。
- 新增: 多账号模式QA：在一个接口里获取是哪个体系的账号正在登录。
- 新增：新增QA：解决低版本 SpringBoot (<2.2.0) 引入 Sa-Token 报错的问题。
- 新增：新增QA：前后端一体项目下，在拦截未登录进入登录页面时，如何登录完成后原路返回？
- 新增：新增QA：Sa-Token 集成 Redis 如何集群？
- 新增：新增QA：如何自定义框架读取 token 的方式？
- 新增：新增QA：修改 hosts 文件无效可能原因排查。
- 新增：新增QA：如何防止 CSRF 攻击。
- 新增: “异步 & Mock 上下文” 章节。
- 升级：升级“自定义 SaTokenContext 指南”章节文档。