Sa-Token轻量级 Java 权限认证框架
@[TOC](Sa-Token 最新开发文档)
开始
介绍
Sa-Token 介绍
Sa-Token 是一个轻量级 Java 权限认证框架，主要解决：登录认证、权限认证、Session会话、单点登录、OAuth2.0、微服务网关鉴权 等一系列权限相关问题。
Sa-Token 的 API 设计非常简单，有多简单呢？以登录认证为例，你只需要：
// 在登录时写入当前会话的账号id
StpUtil.login(10001);
// 然后在需要校验登录处调用以下方法：
// 如果当前会话未登录，这句代码会抛出 `NotLoginException` 异常
StpUtil.checkLogin();
至此，我们已经借助 Sa-Token 完成登录认证！
此时的你小脑袋可能飘满了问号，就这么简单？自定义 Realm 呢？全局过滤器呢？我不用写各种配置文件吗？
没错，在 Sa-Token 中，登录认证就是如此简单，不需要任何的复杂前置工作，只需这一行简单的API调用，就可以完成会话登录认证！
当你受够 Shiro、SpringSecurity 等框架的三拜九叩之后，你就会明白，相对于这些传统老牌框架，Sa-Token 的 API 设计是多么的简单、优雅！
权限认证示例（只有具备 user:add 权限的会话才可以进入请求）
@SaCheckPermission("user:add")
@RequestMapping("/user/insert")
public String insert(SysUser user) {
// ...
return "用户增加";
}
将某个账号踢下线（待到对方再次访问系统时会抛出NotLoginException异常）
// 将账号id为 10001 的会话踢下线
StpUtil.kickout(10001);
在 Sa-Token 中，绝大多数功能都可以 一行代码 完成：
StpUtil.login(10001); // 标记当前会话登录的账号id
StpUtil.getLoginId(); // 获取当前会话登录的账号id
StpUtil.isLogin(); // 获取当前会话是否已经登录, 返回true或false
StpUtil.logout(); // 当前会话注销登录
StpUtil.kickout(10001); // 将账号为10001的会话踢下线
StpUtil.hasRole("super-admin"); // 查询当前账号是否含有指定角色标识, 返回true或false
StpUtil.hasPermission("user:add"); // 查询当前账号是否含有指定权限, 返回true或false
StpUtil.getSession(); // 获取当前账号id的Session
StpUtil.getSessionByLoginId(10001); // 获取账号id为10001的Session
StpUtil.getTokenValueByLoginId(10001); // 获取账号id为10001的token令牌值
StpUtil.login(10001, "PC"); // 指定设备标识登录，常用于“同端互斥登录”
StpUtil.kickout(10001, "PC"); // 指定账号指定设备标识踢下线 (不同端不受影响)
StpUtil.openSafe(120); // 在当前会话开启二级认证，有效期为120秒
StpUtil.checkSafe(); // 校验当前会话是否处于二级认证有效期内，校验失败会抛出异常
StpUtil.switchTo(10044); // 将当前会话身份临时切换为其它账号
即使不运行测试，相信您也能意会到绝大多数 API 的用法。
Sa-Token 功能一览
- 登录认证 —— 单端登录、多端登录、同端互斥登录、七天内免登录
- 权限认证 —— 权限认证、角色认证、会话二级认证
- Session会话 —— 全端共享Session、单端独享Session、自定义Session
- 踢人下线 —— 根据账号id踢人下线、根据Token值踢人下线
- 账号封禁 —— 指定天数封禁、永久封禁、设定解封时间
- 持久层扩展 —— 可集成Redis、Memcached等专业缓存中间件，重启数据不丢失
- 分布式会话 —— 提供jwt集成、共享数据中心两种分布式会话方案
- 微服务网关鉴权 —— 适配Gateway、ShenYu、Zuul等常见网关的路由拦截认证
- 单点登录 —— 内置三种单点登录模式：无论是否跨域、是否共享Redis，都可以搞定
- OAuth2.0认证 —— 基于RFC-6749标准编写，OAuth2.0标准流程的授权认证，支持openid模式
- 二级认证 —— 在已登录的基础上再次认证，保证安全性
- Basic认证 —— 一行代码接入 Http Basic 认证
- 独立Redis —— 将权限缓存与业务缓存分离
- 临时Token验证 —— 解决短时间的Token授权问题
- 模拟他人账号 —— 实时操作任意用户状态数据
- 临时身份切换 —— 将会话身份临时切换为其它账号
- 前后台分离 —— APP、小程序等不支持Cookie的终端
- 同端互斥登录 —— 像QQ一样手机电脑同时在线，但是两个手机上互斥登录
- 多账号认证体系 —— 比如一个商城项目的user表和admin表分开鉴权
- 花式token生成 —— 内置六种Token风格，还可：自定义Token生成策略、自定义Token前缀
- 注解式鉴权 —— 优雅的将鉴权与业务代码分离
- 路由拦截式鉴权 —— 根据路由拦截鉴权，可适配restful模式
- 自动续签 —— 提供两种Token过期策略，灵活搭配使用，还可自动续签
- 会话治理 —— 提供方便灵活的会话查询接口
- 记住我模式 —— 适配[记住我]模式，重启浏览器免验证
- 密码加密 —— 提供密码加密模块，可快速MD5、SHA1、SHA256、AES、RSA加密
- 全局侦听器 —— 在用户登陆、注销、被踢下线等关键性操作时进行一些AOP操作
- 开箱即用 —— 提供SpringMVC、WebFlux等常见web框架starter集成包，真正的开箱即用
使用Sa-Token的开源项目
- 一个基于 SpringBoot 架构的快速开发框架，内置代码生成器
- 一个基于 SpringBoot + Sa-Token + Thymeleaf 的博客系统
- 一个基于 SpringBoot + Sa-Token + Mybatis-Plus 的后台管理系统，前端vue-element-admin，并且内置代码生成器
- 基于JDK15 + Spring Boot 2.4 + Sa-Token + Mybatis-Plus的单体Boot版脚手架和微服务Cloud版脚手架，带有配套后台管理前端模板及代码生成器
- Sa-Token第三方插件实现，基于Sa-Token-Core，提供一些与官方不同实现机制的的插件集合，作为Sa-Token开源生态的补充
- 一个基于SpringBoot2 + Sa-Token + Mybatis-Plus + Snakerflow + Layui 的后台管理系统，灵活多变可前后端分离，也可单体，内置代码生成器、权限管理、工作流引擎等
- 基于 RuoYi-Vue 集成 SaToken + Lombok + Mybatis-Plus + Undertow + knife4j + Hutool + Feign 重写所有原生业务 定期与 RuoYi-Vue 同步
引入
Maven依赖
在项目中直接通过 pom.xml 引入 Sa-Token 的依赖即可（四选一）：
- SpringMVC环境（ServletAPI）
如果你使用的框架基于 ServletAPI 构建（ SpringMVC、SpringBoot、Zuul等 ），请引入此包
<!-- Sa-Token 权限认证, 在线文档：http://sa-token.dev33.cn/ -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-spring-boot-starter</artifactId>
<version>1.27.0</version>
</dependency>
- WebFlux环境（Reactor）
注：如果你使用的框架基于 Reactor 模型构建（Netty、WebFlux、ShenYu、SC Gateway等），请引入此包
<!-- Sa-Token 权限认证（Reactor响应式集成）, 在线文档：http://sa-token.dev33.cn/ -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-reactor-spring-boot-starter</artifactId>
<version>1.27.0</version>
</dependency>
- Servlet容器环境
注：如果你的项目没有使用Spring，但是Web框架是基于 ServletAPI 规范的，可以引入此包
<!-- Sa-Token 权限认证（ServletAPI规范）, 在线文档：http://sa-token.dev33.cn/ -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-servlet</artifactId>
<version>1.27.0</version>
</dependency>
引入此依赖需要自定义 SaTokenContext 实现，参考：自定义 SaTokenContext 指南
- 其他
注：如果你的项目既没有使用 SpringMVC、WebFlux，也不是基于 ServletAPI 规范，那么可以引入core核心包
<!-- Sa-Token 权限认证（core核心包）, 在线文档：http://sa-token.dev33.cn/ -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-core</artifactId>
<version>1.27.0</version>
</dependency>
引入此依赖需要自定义 SaTokenContext 实现，参考：自定义 SaTokenContext 指南
Gradle依赖
- SpringMVC环境（ServletAPI）
implementation 'cn.dev33:sa-token-spring-boot-starter:1.27.0'
- WebFlux环境（Reactor）
implementation 'cn.dev33:sa-token-reactor-spring-boot-starter:1.27.0'
- Servlet容器环境
implementation 'cn.dev33:sa-token-servlet:1.27.0'
- 其他
implementation 'cn.dev33:sa-token-core:1.27.0'
注：JDK版本：v1.8+，SpringBoot：建议2.0以上
获取源码
如果你想深入了解Sa-Token，你可以通过Gitee来获取源码 （学习测试请拉取master分支，dev为正在开发的分支，有很多特性并不稳定）
── sa-token
├── sa-token-core // [核心] Sa-Token 核心模块
├── sa-token-starter // [整合] Sa-Token 与其它框架整合
├── sa-token-servlet // [整合] Sa-Token 整合 Servlet容器实现类包
├── sa-token-spring-boot-starter // [整合] Sa-Token 整合 SpringBoot 快速集成
├── sa-token-reactor-spring-boot-starter // [整合] Sa-Token 整合 Reactor响应式编程 快速集成
├── sa-token-solon-plugin // [整合] Sa-Token 整合 Solon 快速集成
├── sa-token-plugin // [插件] Sa-Token 插件合集
├── sa-token-dao-redis // [插件] Sa-Token 整合 Redis (使用jdk默认序列化方式)
├── sa-token-dao-redis-jackson // [插件] Sa-Token 整合 Redis (使用jackson序列化方式)
├── sa-token-spring-aop // [插件] Sa-Token 整合 SpringAOP 注解鉴权
├── sa-token-temp-jwt // [插件] Sa-Token 整合 jwt 临时令牌鉴权
├── sa-token-quick-login // [插件] Sa-Token 快速注入登录页插件
├── sa-token-alone-redis // [插件] Sa-Token 独立Redis插件，实现[权限缓存与业务缓存分离]
├── sa-token-oauth2 // [插件] Sa-Token 实现 OAuth2.0 模块
├── sa-token-dialect-thymeleaf // [插件] Sa-Token 标签方言（Thymeleaf版）
├── sa-token-demo // [示例] Sa-Token 示例合集
├── sa-token-demo-springboot // [示例] Sa-Token 整合 SpringBoot
├── sa-token-demo-webflux // [示例] Sa-Token 整合 WebFlux
├── sa-token-demo-jwt // [示例] Sa-Token 集成 jwt
├── sa-token-demo-solon // [示例] Sa-Token 集成 Solon
├── sa-token-demo-quick-login // [示例] Sa-Token 集成 quick-login 模块
├── sa-token-demo-alone-redis // [示例] Sa-Token 集成 alone-redis 模块
├── sa-token-demo-thymeleaf // [示例] Sa-Token 集成 Thymeleaf 标签方言
├── sa-token-demo-sso-server // [示例] Sa-Token 集成 SSO单点登录-Server认证中心
├── sa-token-demo-sso1-client // [示例] Sa-Token 集成 SSO单点登录-模式一 应用端
├── sa-token-demo-sso2-client // [示例] Sa-Token 集成 SSO单点登录-模式二 应用端
├── sa-token-demo-sso3-client // [示例] Sa-Token 集成 SSO单点登录-模式三 应用端
├── sa-token-demo-sso-server-h5 // [示例] Sa-Token 集成 SSO单点登录-Server认证中心 (前后端分离)
├── sa-token-demo-sso-client-h5 // [示例] Sa-Token 集成 SSO单点登录-client应用端 (前后端分离)
├── sa-token-demo-oauth2-server // [示例] Sa-Token 集成 OAuth2.0 (服务端)
├── sa-token-demo-oauth2-client // [示例] Sa-Token 集成 OAuth2.0 (客户端)
├── sa-token-doc // [文档] Sa-Token 开发文档
├──pom.xml // [依赖] 顶级pom文件
jar包下载
链接：https://pan.baidu.com/s/1HoysOBtYWxbJ1zZASzrYjg
提取码：r6uk
–来自百度网盘超级会员V4的分享
(注意：当前仅提供v1.6.0版本jar包下载，更多版本请前往maven中央仓库获取，直达链接)
SpringBoot 集成 Sa-Token 示例
1、创建项目
在IDE中新建一个SpringBoot项目，例如：sa-token-demo-springboot
2、添加依赖
在 pom.xml 中添加依赖：
<!-- Sa-Token 权限认证, 在线文档：http://sa-token.dev33.cn/ -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-spring-boot-starter</artifactId>
<version>1.27.0</version>
</dependency>
3、设置配置文件
你可以零配置启动项目 ，但同时你也可以在application.yml中增加如下配置，定制性使用框架：
server:
# 端口
port: 8081
# Sa-Token配置
sa-token:
# token名称 (同时也是cookie名称)
token-name: satoken
# token有效期，单位s 默认30天, -1代表永不过期
timeout: 2592000
# token临时有效期 (指定时间内无操作就视为token过期) 单位: 秒
activity-timeout: -1
# 是否允许同一账号并发登录 (为true时允许一起登录, 为false时新登录挤掉旧登录)
is-concurrent: true
# 在多人登录同一账号时，是否共用一个token (为true时所有登录共用一个token, 为false时每次登录新建一个token)
is-share: false
# token风格
token-style: uuid
# 是否输出操作日志
is-log: false
4、创建启动类
在项目中新建包 com.pj ，在此包内新建主类 SaTokenDemoApplication.java，输入以下代码：
@SpringBootApplication
public class SaTokenDemoApplication {
public static void main(String[] args) throws JsonProcessingException {
SpringApplication.run(SaTokenDemoApplication.class, args);
System.out.println("启动成功：Sa-Token配置如下：" + SaManager.getConfig());
}
}
5、创建测试Controller
@RestController
@RequestMapping("/user/")
public class UserController {
// 测试登录，浏览器访问： http://localhost:8081/user/doLogin?username=zhang&password=123456
@RequestMapping("doLogin")
public String doLogin(String username, String password) {
// 此处仅作模拟示例，真实项目需要从数据库中查询数据进行比对
if("zhang".equals(username) && "123456".equals(password)) {
StpUtil.login(10001);
return "登录成功";
}
return "登录失败";
}
// 查询登录状态，浏览器访问： http://localhost:8081/user/isLogin
@RequestMapping("isLogin")
public String isLogin() {
return "当前会话是否登录：" + StpUtil.isLogin();
}
}
6、运行
启动代码，从浏览器依次访问上述测试接口：
Spring WebFlux 集成 Sa-Token 示例
Reactor 是一种非阻塞的响应式模型，本篇将以 WebFlux 为例，展示 Sa-Token 与 Reactor 响应式模型框架相整合的示例， 你可以用同样方式去对接其它Reactor模型框架（Netty、ShenYu、SpringCloud Gateway等）
整合示例在官方仓库的/sa-token-demo/sa-token-demo-webflux文件夹下，如遇到难点可结合源码进行测试学习
1、创建项目
在IDE中新建一个SpringBoot项目，例如：sa-token-demo-webflux
2、添加依赖
在 pom.xml 中添加依赖：
<!-- Sa-Token 权限认证（Reactor响应式集成）, 在线文档：http://sa-token.dev33.cn/ -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-reactor-spring-boot-starter</artifactId>
<version>1.27.0</version>
</dependency>
3、创建启动类
在项目中新建包 com.pj ，在此包内新建主类 SaTokenDemoApplication.java，输入以下代码：
@SpringBootApplication
public class SaTokenDemoApplication {
public static void main(String[] args) throws JsonProcessingException {
SpringApplication.run(SaTokenDemoApplication.class, args);
System.out.println("启动成功：Sa-Token配置如下：" + SaManager.getConfig());
}
}
4、创建全局过滤器
新建SaTokenConfigure.java，注册Sa-Token的全局过滤器
/**
* [Sa-Token 权限认证] 全局配置类
*/
@Configuration
public class SaTokenConfigure {
/**
* 注册 [Sa-Token全局过滤器]
*/
@Bean
public SaReactorFilter getSaReactorFilter() {
return new SaReactorFilter()
// 指定 [拦截路由]
.addInclude("/**")
// 指定 [放行路由]
.addExclude("/favicon.ico")
// 指定[认证函数]: 每次请求执行
.setAuth(obj -> {
System.out.println("---------- sa全局认证");
// SaRouter.match("/test/test", () -> StpUtil.checkLogin());
})
// 指定[异常处理函数]：每次[认证函数]发生异常时执行此函数
.setError(e -> {
System.out.println("---------- sa全局异常 ");
return AjaxJson.getError(e.getMessage());
})
;
}
}
5、创建测试Controller
@RestController
@RequestMapping("/user/")
public class UserController {
// 测试登录，浏览器访问： http://localhost:8081/user/doLogin?username=zhang&password=123456
@RequestMapping("doLogin")
public String doLogin(String username, String password) {
// 此处仅作模拟示例，真实项目需要从数据库中查询数据进行比对
if("zhang".equals(username) && "123456".equals(password)) {
StpUtil.login(10001);
return "登录成功";
}
return "登录失败";
}
// 查询登录状态，浏览器访问： http://localhost:8081/user/isLogin
@RequestMapping("isLogin")
public String isLogin() {
return "当前会话是否登录：" + StpUtil.isLogin();
}
}
6、运行
启动代码，从浏览器依次访问上述测试接口：
欢迎使用Markdown编辑器
你好！ 这是你第一次使用 Markdown编辑器 所展示的欢迎页。如果你想学习如何使用Markdown编辑器, 可以仔细阅读这篇文章，了解一下Markdown的基本语法知识。
新的改变
我们对Markdown编辑器进行了一些功能拓展与语法支持，除了标准的Markdown编辑器功能，我们增加了如下几点新功能，帮助你用它写博客：
- 全新的界面设计 ，将会带来全新的写作体验；
- 在创作中心设置你喜爱的代码高亮样式，Markdown 将代码片显示选择的高亮样式 进行展示；
- 增加了 图片拖拽 功能，你可以将本地的图片直接拖拽到编辑区域直接展示；
- 全新的 KaTeX数学公式 语法；
- 增加了支持甘特图的mermaid语法1 功能；
- 增加了 多屏幕编辑 Markdown文章功能；
- 增加了 焦点写作模式、预览模式、简洁写作模式、左右区域同步滚轮设置 等功能，功能按钮位于编辑区域与预览区域中间；
- 增加了 检查列表 功能。
功能快捷键
撤销：Ctrl/Command + Z
重做：Ctrl/Command + Y
加粗：Ctrl/Command + B
斜体：Ctrl/Command + I
标题：Ctrl/Command + Shift + H
无序列表：Ctrl/Command + Shift + U
有序列表：Ctrl/Command + Shift + O
检查列表：Ctrl/Command + Shift + C
插入代码：Ctrl/Command + Shift + K
插入链接：Ctrl/Command + Shift + L
插入图片：Ctrl/Command + Shift + G
查找：Ctrl/Command + F
替换：Ctrl/Command + G
合理的创建标题，有助于目录的生成
直接输入1次#，并按下space后，将生成1级标题。
输入2次#，并按下space后，将生成2级标题。
以此类推，我们支持6级标题。有助于使用TOC语法后生成一个完美的目录。
如何改变文本的样式
强调文本 强调文本
加粗文本 加粗文本
标记文本
删除文本
引用文本
H2O is是液体。
210 运算结果是 1024.
插入链接与图片
链接: link.
图片: 
带尺寸的图片:
居中的图片: 
居中并且带尺寸的图片:
当然，我们为了让用户更加便捷，我们增加了图片拖拽功能。
如何插入一段漂亮的代码片
去博客设置页面，选择一款你喜欢的代码片高亮样式，下面展示同样高亮的 代码片.
// An highlighted block
var foo = 'bar';
生成一个适合你的列表
- 项目
- 项目
- 项目
- 项目
- 项目1
- 项目2
- 项目3
- 计划任务
- 完成任务
创建一个表格
一个简单的表格是这么创建的：
| 项目 | Value |
|---|---|
| 电脑 | $1600 |
| 手机 | $12 |
| 导管 | $1 |
设定内容居中、居左、居右
使用:---------:居中
使用:----------居左
使用----------:居右
| 第一列 | 第二列 | 第三列 |
|---|---|---|
| 第一列文本居中 | 第二列文本居右 | 第三列文本居左 |
SmartyPants
SmartyPants将ASCII标点字符转换为“智能”印刷标点HTML实体。例如：
| TYPE | ASCII | HTML |
|---|---|---|
| Single backticks | 'Isn't this fun?' |
‘Isn’t this fun?’ |
| Quotes | "Isn't this fun?" |
“Isn’t this fun?” |
| Dashes | -- is en-dash, --- is em-dash |
– is en-dash, — is em-dash |
创建一个自定义列表
-
Markdown
- Text-to- HTML conversion tool Authors
- John
- Luke
如何创建一个注脚
一个具有注脚的文本。2
注释也是必不可少的
Markdown将文本转换为 HTML。
KaTeX数学公式
您可以使用渲染LaTeX数学表达式 KaTeX:
Gamma公式展示 Γ ( n ) = ( n − 1 ) ! ∀ n ∈ N \Gamma(n) = (n-1)!\quad\forall n\in\mathbb N Γ(n)=(n−1)!∀n∈N 是通过欧拉积分
Γ ( z ) = ∫ 0 ∞ t z − 1 e − t d t . \Gamma(z) = \int_0^\infty t^{z-1}e^{-t}dt\,. Γ(z)=∫0∞tz−1e−tdt.
你可以找到更多关于的信息 LaTeX 数学表达式here.
新的甘特图功能，丰富你的文章
- 关于 甘特图 语法，参考 这儿,
UML 图表
可以使用UML图表进行渲染。 Mermaid. 例如下面产生的一个序列图：
这将产生一个流程图。:
- 关于 Mermaid 语法，参考 这儿,
FLowchart流程图
我们依旧会支持flowchart的流程图：
- 关于 Flowchart流程图 语法，参考 这儿.
导出与导入
导出
如果你想尝试使用此编辑器, 你可以在此篇文章任意编辑。当你完成了一篇文章的写作, 在上方工具栏找到 文章导出 ，生成一个.md文件或者.html文件进行本地保存。
导入
如果你想加载一篇你写过的.md文件，在上方工具栏可以选择导入功能进行对应扩展名的文件导入，
继续你的创作。
mermaid语法说明 ↩︎
注脚的解释 ↩︎