Sa-Token 是一款开源、免费的轻量级 Java 权限认证框架主要解决登录认证、权限认证、单点登录、OAuth2.0、微服务网关鉴权等一系列权限相关问题。目前最新版本v1.46.0已推送至Maven中央仓库大家可以通过如下方式引入!-- Sa-Token 权限认证 --dependencygroupIdcn.dev33/groupIdartifactIdsa-token-spring-boot4-starter/artifactIdversion1.46.0/version/dependencySpring Boot 3.x 请改用sa-token-spring-boot3-starterSpring Boot 2.x 请改用sa-token-spring-boot-starter。该版本包含大量 ⛏️️️新增特性、⛏️底层重构、⛏️️️代码优化 等下面容我列举几条比较重要的更新内容供大家参阅 更新点1新增sa-token-fory-json插件JSON 方案再添一位这是官方规划里「JSON 模块集成 Apache Fory」的落地把 Fory JSON 接到SaJsonTemplate上。此前 Session / Redis 序列化主要是 JacksonBoot 默认JSON 里会写class和 Fastjson2 / Snack默认不写类型信息。相对 JacksonFory 官方文档给出的吞吐更高且默认不写类型信息避开多态反序列化那条面相对 Fastjson2用法接近适合已经在用 Apache Fory、或不想再绑 Fastjson 栈的项目。引入后 SPI 自动注入不用自己包一层。!-- Sa-Token 整合 Apache Fory JSON --dependencygroupIdcn.dev33/groupIdartifactIdsa-token-fory-json/artifactIdversion1.46.0/version/dependencyJSON 插件全家桶现在是Jackson、Jackson3、Fastjson、Fastjson2、Fory JSON、Snack3、Snack4。Boot 2/3 默认仍是 JacksonBoot 4 默认 Jackson3用得顺不必为了换而换。在线文档JSON 序列化扩展 更新点2新增sa-token-rest-client/sa-token-rest-template插件SSO 模式三的 ticket 校验、单点注销、消息推送都要发 HTTP。此前只有 Forest、OkHttps 两套第三方客户端。Spring 项目本来就有spring-web再为 SSO 拉一套 HTTP 库依赖和 API 都多一层。本版按官方规划补上 Spring 官方客户端sa-token-rest-template、sa-token-rest-client。相对 Forest / OkHttps不引入第三方 HTTP 栈跟 Spring 一条线。RestClient相对RestTemplate它是 Spring Framework 6.1 / Boot 3.2 的官方继任者Boot 4 里RestTemplate已标记 deprecated新项目优先 RestClient。Boot 2 或 Boot 3.0–3.1 没有RestClient继续用 RestTemplate 或 Forest。!-- Spring Boot 3.2 / 4 优先 RestClient --dependencygroupIdcn.dev33/groupIdartifactIdsa-token-rest-client/artifactIdversion1.46.0/version/dependency运行环境推荐插件非 Spring / Solonsa-token-forest或sa-token-okhttpsSpring Boot 2或 Boot 3.0–3.1sa-token-rest-template或sa-token-forestSpring Boot 3.2 / 4优先sa-token-rest-client同一 classpath 只放一个 HTTP 插件。没配任何处理器会报错误码 30010。本版还加了 SSO Client 的 Spring Boot 4 示例。在线文档HTTP 请求扩展 ️ 更新点3新增sa-token-alone-redisson插件权限缓存和业务缓存拆开来自 GitHub #710、Gitee #ICE2V0alone-redis 要能配独立 Redisson。升级有什么用现在redisson集成也可以做到权限缓存和业务缓存分离了会话数据和业务 Redis 不再挤在同一个 Client 上key 冲突、误删、codec 打架都能避开。Boot 4 另有sa-token-alone-redis-by-spring-boot4。dependencygroupIdcn.dev33/groupIdartifactIdsa-token-alone-redisson/artifactIdversion1.46.0/version/dependency引入后不必再引sa-token-redisson/sa-token-redisson-spring-boot-starter。sa-token:alone-redisson:config:singleServerConfig:address:redis://127.0.0.1:6379database:2config与file二选一。示例覆盖单机、集群、Boot 3/4。Boot 4 注意Redisson 3.45 的 starter 仍引用已移除的RedisAutoConfiguration不要引redisson-spring-boot-starter自己注册 Bean。SaTokenDaoForRedisson默认StringCodec并可用setAndKeepTTL原子保留 TTL。fix: #791在线文档独立 Redisson 插件 更新点4RedisTemplate 检索改 SCAN、update 保 TTL、key 可加前缀这几条都是社区老工单searchData用 KEYS 会堵 Redis#702update 后续期 TTL 偏移#I80P5O、#ICWJOQ多项目共用 Redis 要加前缀#956升级有什么用在线用户查询不再KEYS *改 Session 不会把过期时间抹成「再活一整段 timeout」多系统共 Redis 可以wrapKey隔离开。publicclassMySaTokenDaoextendsSaTokenDaoForRedisTemplate{OverridepublicStringwrapKey(Stringkey){returnmy-app:key;}}KEEPTTL 需要 Redis 6.0。 更新点5注销前侦听器会话清掉之前还能读现场来自 sa-token 小助手用户「潮汐」的建议侦听器触发时设备信息往往已经没了审计不好记。升级有什么用踢人、顶人、主动注销前还能读到 Token-Session、设备列表写日志、发通知不用自己抢时序。OverridepublicvoiddoBeforeLogout(StringloginType,ObjectloginId,StringtokenValue,SaLogoutParameterlogoutParameter){SaSessionsessionSaManager.getStpLogic(loginType).getSessionByLoginId(loginId,false);SaTerminalInfoterminalsessionnull?null:session.getTerminal(tokenValue);// 记注销日志}对应钩子doBeforeLogout/doBeforeKickout/doBeforeReplaced。不要用StpUtil读当前请求上下文用参数里的loginId、tokenValue去查。在线文档全局侦听器 更新点6Session 新增getList/getSet/getMap本版主动补齐。以前从 Session 取集合要么get完再强转要么自己处理 Redis 回来的裸 List。现在把元素类型写在参数上主要是为了让代码写得更优雅调用更友善。// 以前SuppressWarnings(unchecked)ListSysUserusers(ListSysUser)session.get(users);// 现在ListSysUseruserssession.getList(users,SysUser.class);SetStringrolessession.getSet(roles,String.class);MapString,LongscoreMapsession.getMap(scoreMap,String.class,Long.class);// 缺 key 时给默认集合session.getList(users,SysUser.class,ArrayList::new);OAuth2 索引、SSO Client 列表、ApiKey 索引也切到这套 API业务侧同一套写法。在线文档Session 会话 更新点7SSO 客户端支持按账号单点注销社区提案子系统删用户时希望一行 API 通知认证中心把该账号全端打下线。升级有什么用后台封号、离职回收不必再自己拼 SSO 推送报文。// sso-serverSaSsoServerUtil.ssoLogout(loginId);// sso-client本地 loginId框架按策略转成认证中心 idSaSsoClientUtil.ssoLogout(loginId);在线文档Sa-Token SSO 单点注销 更新点8SaRequest/SaResponse/SaStorage可策略创建来自 GitHub #841旧版靠继承SaTokenContextForSpring改上下文v1.42 重构后那套父类没了。升级有什么用Nginx 改 URI、自定义 Request 包装改策略函数即可不用再继承已删除的上下文类。SaStrategy新增createSaRequest/createSaResponse/createSaStorage。getSaTokenConfig也可接管配置来源方便从数据库读 Sa-Token 配置。⚠️ 更新点9两处不向下兼容升级先看1allowLoginIdColon默认 false。官方一直强调 loginId 不要带冒号持久化 key 用:分段。本版源码直接拒登。存量项目如果 loginId 里真有冒号sa-token:allow-login-id-colon:true2StpInterface.isDisabled增加loginType参数。自己实现了封禁查询的要改方法签名。另外JWTextraData禁止写入loginType、loginId、deviceType、eff、rnStr等保留字段撞名会直接抛错。️ 更新点10修复 OAuth2 / SSOredirect绕过allow-url漏洞来自社区用户提交的漏洞报告OAuth2 调用/oauth2/doConfirm时redirect_uri校验可被绕过本版审查后确认 SSO 的redirect存在同类问题。触发条件为需同时满足项目搭了SSO 认证中心或OAuth2 授权服务器请求里可以由前端或攻击者传入redirect/redirect_uriallow-url配了不安全通配如http://domain**出现在域名部分前面不是/或:。普通登录鉴权、没用 SSO/OAuth2 的项目与这条无关。allow-url: *等于主动放开白名单也不在本条讨论范围。会造成ticket 或授权码被下发到第三方站点。新版本SSO 与 OAuth2 两侧同时拒绝、%40、%2540*只能出现在最后一位且前一位必须是/或:isUrl支持 IPv6 方括号地址。生产环境请把allow-url配成明确地址。用了 SSO/OAuth2 的建议升到 v1.46.0。sa-token:sso-server:clients:sso-client1:allow-url:http://sa-sso-client1.com:9003/*感谢这位社区用户提交的漏洞报告。 更新点11修复 Jackson 多态反序列化漏洞新增类型白名单这是本版对 JSON 反序列化路径的主动审查使用 Jackson / Jackson3 把SaSession写入 Redis 时JSON 里会带class类型标记旧版本未限制严格限制反序列化类型白名单可能会在反序列化时触发 classpath 上的任意类。触发条件为需同时满足使用SaJsonTemplate去反序列化业务中未严格审查的 json 字符串。fastjson/fastjson2/fory-json/snack3默认不写类型标记一般不走这条面。不去使用SaJsonTemplate去反序列化业务中未严格审查的 json 字符串。本版起sa-token-snack3也不再写入类型信息。会造成攻击者提交恶意 json 字符串可能触发多态反序列化 RCE。新版本增加SaJsonStrategy全局类型白名单只允许白名单内类型参与这类反序列化。JDK 常见值类型、框架已实现SaJsonType的 Model 默认在名单里你的业务实体默认不在。用了 Jackson 且 Session 里存了自定义对象的升级后可能看到无法反序列化的类型com.pj.model.SysUser请先将其注册到 JSON 全局类型白名单推荐让实体实现SaJsonTypepublicclassSysUserimplementsSaJsonType{// ...}也可以在SpringApplication.run之前调用SaJsonStrategy.instance.registerAllowType(SysUser.class)或在META-INF/satoken/sa-json-type.list按行写完整类名。JSON 插件初始化后再注册会失败。不要登记Object.class。用了 Jackson SaJsonTemplate 反序列化业务 json 字符串的建议升到 v1.46.0并先把业务类型登记进白名单。在线文档JSON 序列化扩展 更新点12修复 SSE / Flux 上下文未初始化以及 Boot3 WebFluxsetStatus这两条都是社区报错工单SSE 来自 Gitee #IC4XFE、#ICB9OJsetStatus来自 #IIAW1A、GitHub #916。SSE / Flux在之前的版本中SpringMVC 接口如果返回SseEmitter、Flux等异步、流式结果随后再调StpUtil/SaHolder会报cn.dev33.satoken.exception.SaTokenContextException: SaTokenContext 上下文尚未初始化这是因为 Context Filter 只注册了REQUEST。流式返回会再走一遍ASYNCdispatch过滤器没挂上ThreadLocal 上下文是空的。普通RequestMapping一问一答不受影响。新版本把 Filter 注册为REQUESTASYNC二次 dispatch 也会初始化上下文一般不用再手改 Filter。Boot3 WebFlux / GatewaysetStatus在之前的版本中Boot3 的 WebFlux 或 Gateway 里调用SaHolder.getResponse().setStatus(401);会报java.lang.NoSuchMethodError: org.springframework.http.server.reactive.ServerHttpResponse setStatusCode(org.springframework.http.HttpStatus)这是因为 Boot2 的ServerHttpResponse.setStatusCode吃HttpStatusBoot3 改成了HttpStatusCode旧 Reactor starter 字节码对不上。WebMVC 用户与这条无关。新版本拆了 Boot2 / Boot3 的 Reactor 实现Boot3 走HttpStatusCode.valueOf(sc)不再报错。sa-token-dependencies也不再锁死 Reactor 版本避免跟 Spring Cloud Gateway 打架。fix: #622 更新点13文档站启用 .com 顶级域名博客、多语言、安全策略域名从sa-token.cc迁到 sa-token.com请即使修改书签。独立博客上线文档站暗色主题 5 种 IDE 风格translate.js 多语言README 有英/日/韩/俄/繁中。随机数改用SecureRandom。新增SECURITY.md安全问题走 GitHub Private Vulnerability Reporting 或邮件不要开公开 Issue。文档版本选择器改为动态加载。Solon 插件由 PathAnalyzer 换成 PathMatcher。感谢 Ran 补充SECURITY.mdfix #932、#877感谢 noear 适配 Solon PathMatcherfix #IJTNJK。 完整更新日志除了以上提到的几点以外还有更多更新点无法逐一详细介绍下面是 v1.46.0 版本的完整更新日志core新增侦听器新增注销前钩子doBeforeLogout/doBeforeKickout/doBeforeReplaced。[重要]新增StpInterface.isDisabled补充loginType参数。[不向下兼容]新增新增allowLoginIdColon配置默认禁止 loginId 包含冒号。[不向下兼容]修复Jackson DefaultTyping 多态反序列化 RCE新增SaJsonStrategy全局类型白名单。[重要][漏洞修复]新增getSaTokenConfig策略支持自定义配置来源方便从数据库中读取配置。新增新增SaRequest/SaResponse/SaStorage创建策略。 fix: #841新增Session 新增getList/getSet/getMap类型安全集合读取。修改随机字符串/数字改用 CSPRNGSecureRandom生成。修复isLastingCookie为 null 时getCookieTimeout不再 NPE。修复isUrl支持 IPv6 方括号地址并拒绝裸 IPv6。修复JSON 反序列化容错优化。 fix: #ICOTM8插件新增新增sa-token-fory-jsonJSON 序列化插件。[重要]新增新增 HTTP 请求扩展插件sa-token-rest-client/sa-token-rest-template。[重要]新增新增sa-token-alone-redisson独立连接插件及 Spring Boot 3/4 示例。[重要]fix: #710、#ICE2V0新增新增sa-token-alone-redis-by-spring-boot4插件及示例实现 Spring Boot 4 下权限缓存与业务缓存分离。[重要]新增SaTokenDaoForRedisson支持指定 Codec默认StringCodecupdate 方法改用setAndKeepTTL原子保留原过期时间。[重要]fix: #791修复sa-token-redis-template及 jdk-serializer 在 update key 时 TTL 偏移的问题。[重要]fix: #I80P5O、#ICWJOQ修复redis-templatesearchData由 KEYS 改为 SCAN。[重要]fix: #702新增RedisTemplate Dao 支持重写wrapKey自定义键前缀。 fix: #956修复sa-token-redis-template-jdk-serializerKEEPTTL 泛型编译错误。修复Snack3 序列化不再写入类型信息对齐 fastjson 安全策略。[漏洞修复]修复集成 JWT 时extraData禁止包含保留字段。[不向下兼容]优化升级 fastjson / fastjson2 至 2.0.64。优化sa-token-dependencies不再锁定 Reactor 版本避免与 Spring Cloud Gateway 冲突。 fix: #622starter修复Context Filter 注册 REQUESTASYNC修复 SSE/Flux 流式返回上下文未初始化。[重要]fix: #IC4XFE、#ICB9OJ修复Boot3 WebFlux/GatewaysetStatusNoSuchMethodError。 fix: #IIAW1A、#916、#IHRIBY新增新增 SSO Client Spring Boot 4 示例。新增新增sa-token-demo-first-run首次运行引导示例。修复demo-ssm 适配 v1.42.0 上下文机制。Solon优化sa-token-solon-plugin由 PathAnalyzer 适配改为 PathMatcher优化 Config 示例。 merge: pr 364 fix: #IJTNJK优化升级依赖 noear-redisx 至 1.8.5、noear-snack4 至 4.0.59。SSO修复OAuth2/SSOredirect参数绕过allow-url校验的安全漏洞。[重要][漏洞修复]新增SSO 客户端新增指定账号单点注销 API。补全补全最新版 SSO NoSdk 模式实现新增SsoSignUtil。修复buildServerAuthUrl识别 URL 编码后的 back 参数back 为空时跳过追加并增强重定向编码/解码健壮性。 fix: #842修复getClient统一通过getClients查找以支持子类覆盖。修复NoSdk demo 签名校验补充时间窗与 nonce 防重放。[漏洞修复]修复订正 SSO-Client 接收消息推送地址的路由说明。OAuth2修复redirect参数绕过allow-url校验的安全漏洞。[重要][漏洞修复]修改expiresTime为 -1 时按永久有效存储 Token。重构doConfirm确认授权流程统一校验。重构SaOAuth2Dao改用带 Class 参数的getObject反序列化。 fix: #IK5GYU修复OAuth2 demo 拒绝授权时回传 state。新增OAuth2 章节补充数据互通后的 token 过期策略说明。文档修改全仓库域名 sa-token.cc 统一迁移至 sa-token.com。[重要]新增上线独立博客系统收录原创文章。[重要]新增文档站点多语言切换基于 translate.js。[重要]新增README 多语言版本英文、日文、韩文、俄文、繁体中文与切换入口。[重要]新增新增SECURITY.md安全策略及联系邮箱。[重要]merge: pr 933 fix: #932、#877新增文档站点暗色主题切换支持 5 种 IDE 风格。新增文档版本选择器改为动态加载all-version-common.js。 merge: pr 928 fix: #900新增新增源码运行指南文档。新增新增「Sa-Token 集成 Demos 示例大全下载」文档。新增导航栏增加安全推荐与案例下拉菜单。优化文档站点整体优化侧边栏、首页、捐赠页、导航交互、API 手册等。同步同步公众号文章列表、博客列表、赞助者名单、企业登记案例。补充补充 SSE/Flux 流式返回常见问题补充按配置决定是否启用 Redis 的示例。 fix: #I9I4ZG修复订正 API 手册、SSO/OAuth2/WebFlux/Dubbo 等文档错漏。其它新增新增乐之者java B站视频教程链接。[重要]优化统一日志文案用词「帐号」改为「账号」。优化统一 token 续期相关注释措辞。修复修正 ConcurrentHashMap 的错误 import 路径。 merge: pr 359更新日志在线文档直达链接https://sa-token.com/doc.html#/more/update-log 其它代码仓库地址https://gitee.com/dromara/sa-token框架功能结构图