1. 框架介绍
前言:
最新开发文档永远在:https://sa-token.cc
SaToken介绍
Sa-Token 是一个轻量级 Java 权限认证框架,主要解决:登录认证、权限认证、单点登录、OAuth2.0、分布式Session会话、微服务网关鉴权 等一系列权限相关问题。
优点:
- 功能相对Shiro和SpringSecurity更加全面和完整
- 更加独立,整合项目过程中只需要引入依赖添加配置即可简化了部署的操作
- API设计简单不冗余复杂。
登录认证体验
// 在登录时写入当前会话的账号id
StpUtil.login(10001);
// 然后在需要校验登录处调用以下方法:
// 如果当前会话未登录,这句代码会抛出 `NotLoginException` 异常
StpUtil.checkLogin();
就上面短短的两句话,我们已经完成了登录认证。
再举两个例子
例如:
权限认证:
(只有具备 user:add 权限的会话才可以进入请求)
@SaCheckPermission("user:add")
@RequestMapping("/user/insert")
public String insert(SysUser user) {
// ...
return "用户增加";
}
又例如
账号登出:
将某个账号踢下线(待到对方再次访问系统时会抛出NotLoginException异常)
// 使账号id为 10001 的会话强制注销登录
StpUtil.logoutByLoginId(10001);
不止以上这些功能,其实在Sa-Token里,绝大多数功能都可以只用一行代码完成,听着很神奇是吧?但事实就是这样:
StpUtil.login(10001); // 标记当前会话登录的账号id
StpUtil.getLoginId(); // 获取当前会话登录的账号id
StpUtil.isLogin(); // 获取当前会话是否已经登录, 返回true或false
StpUtil.logout(); // 当前会话注销登录
StpUtil.logoutByLoginId(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.logoutByLoginId(10001, "PC"); // 指定设备标识进行强制注销 (不同端不受影响)
StpUtil.openSafe(120); // 在当前会话开启二级认证,有效期为120秒
StpUtil.checkSafe(); // 校验当前会话是否处于二级认证有效期内,校验失败会抛出异常
StpUtil.switchTo(10044); // 将当前会话身份临时切换为其它账号
功能一览
-
登录认证 —— 单端登录、多端登录、同端互斥登录、七天内免登录
-
权限认证 —— 权限认证、角色认证、会话二级认证
-
Session会话 —— 全端共享Session、单端独享Session、自定义Session
-
踢人下线 —— 根据账号id踢人下线、根据Token值踢人下线
-
账号封禁 —— 登录封禁、按照业务分类封禁、按照处罚阶梯封禁
-
持久层扩展 —— 可集成Redis、Memcached等专业缓存中间件,重启数据不丢失
-
分布式会话 —— 提供jwt集成、共享数据中心两种分布式会话方案
-
微服务网关鉴权 —— 适配Gateway、ShenYu、Zuul等常见网关的路由拦截认证
-
单点登录 —— 内置三种单点登录模式:无论是否跨域、是否共享Redis,都可以搞定
-
OAuth2.0认证 —— 轻松搭建 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集成包,真正的开箱即用
功能结构图:
框架认证流程:
2. 在SpringBoot环境集成
2.1 添加依赖
注:如果你使用的是 SpringBoot 3.x,只需要将 sa-token-spring-boot-starter
修改为 sa-token-spring-boot3-starter
即可。
<!-- Sa-Token 权限认证,在线文档:https://sa-token.cc -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-spring-boot-starter</artifactId>
<version>1.37.0</version>
</dependency>
2.2 设置配置文件
application.yml 风格
############## Sa-Token 配置 ##############
sa-token:
# token 名称(同时也是 cookie 名称)
token-name: satoken
# token 有效期(单位:秒) 默认30天,-1 代表永久有效
timeout: 2592000
# token 最低活跃频率(单位:秒),如果 token 超过此时间没有访问系统就会被冻结,默认-1 代表不限制,永不冻结
active-timeout: -1
# 是否允许同一账号多地同时登录 (为 true 时允许一起登录, 为 false 时新登录挤掉旧登录)
is-concurrent: true
# 在多人登录同一账号时,是否共用一个 token (为 true 时所有登录共用一个 token, 为 false 时每次登录新建一个 token)
is-share: true
# token 风格(默认可取值:uuid、simple-uuid、random-32、random-64、random-128、tik)
token-style: uuid
# 是否输出操作日志
is-log: true
2.3 创建启动类
新建主类 SaTokenDemoApplication.java
,复制以下代码:
@SpringBootApplication
public class SaTokenDemoApplication {
public static void main(String[] args) throws JsonProcessingException {
SpringApplication.run(SaTokenDemoApplication.class, args);
}
}
2.4 注册拦截器
以SpringBoot2.0
为例,新建配置类SaTokenConfigure.java
@Configuration
public class SaTokenConfigure implements WebMvcConfigurer {
// 注册 Sa-Token 拦截器,打开注解式鉴权功能
@Override
public void addInterceptors(InterceptorRegistry registry) {
// 注册 Sa-Token 拦截器,打开AOPm注解式鉴权功能
registry.addInterceptor(new SaInterceptor()).addPathPatterns("/**");
}
}
2.5 全局异常拦截
新建配置类GlobalExceptionHandler.java
@RestControllerAdvice
public class GlobalExceptionHandler {
// 全局异常拦截
@ExceptionHandler
public SaResult handlerException(Exception e) {
return SaResult.error(e.getMessage());
}
}
2.6 集成Redis
Sa-Token 提供了扩展接口,你可以轻松将会话数据存储在一些专业的缓存中间件上(比如 Redis), 做到重启数据不丢失。
2.6.1 引入依赖
<!-- Sa-Token 整合 Redis (使用 jackson 序列化方式) -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-redis-jackson</artifactId>
<version>1.37.0</version>
</dependency>
2.6.2 提供一个 Redis 实例化方案
<!-- 提供Redis连接池 -->
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-pool2</artifactId>
</dependency>
2.6.3 配置文件
spring:
# redis配置
redis:
# Redis数据库索引(默认为0)
database: 1
# Redis服务器地址
host: 127.0.0.1
# Redis服务器连接端口
port: 6379
# Redis服务器连接密码(默认为空)
# password:
# 连接超时时间
timeout: 10s
lettuce:
pool:
# 连接池最大连接数
max-active: 200
# 连接池最大阻塞等待时间(使用负值表示没有限制)
max-wait: -1ms
# 连接池中的最大空闲连接
max-idle: 10
# 连接池中的最小空闲连接
min-idle: 0
集成Redis后,框架自动保存数据
2.7 权限认证
你需要做的就是新建一个类,实现 StpInterface
接口,例如以下代码:
/**
* 自定义权限加载接口实现类
*/
@Component // 保证此类被 SpringBoot 扫描,完成 Sa-Token 的自定义权限验证扩展
public class StpInterfaceImpl implements StpInterface {
/**
* 返回一个账号所拥有的权限码集合
*/
@Override
public List<String> getPermissionList(Object loginId, String loginType) {
// 本 list 仅做模拟,实际项目中要根据具体业务逻辑来查询权限
List<String> list = new ArrayList<String>();
list.add("101");
list.add("user.add");
list.add("user.update");
list.add("user.get");
// list.add("user.delete");
list.add("art.*");
return list;
}
/**
* 返回一个账号所拥有的角色标识集合 (权限与角色可分开校验)
*/
@Override
public List<String> getRoleList(Object loginId, String loginType) {
// 本 list 仅做模拟,实际项目中要根据具体业务逻辑来查询角色
List<String> list = new ArrayList<String>();
list.add("admin");
list.add("super-admin");
return list;
}
}
参数解释:
- loginId:账号id,即你在调用
StpUtil.login(id)
时写入的标识值。 - loginType:账号体系标识。
2.8 创建一个测试类
@RestController
@RequestMapping("/user/")
public class UserController {
// 登录接口
@RequestMapping("doLogin")
public SaResult doLogin() {
// 第1步,先登录上
StpUtil.login(10001);
// 第2步,获取 Token 相关参数
SaTokenInfo tokenInfo = StpUtil.getTokenInfo();
// 第3步,返回给前端
return SaResult.data(tokenInfo);
}
// 登录校验:只有登录之后才能进入该方法
@SaCheckLogin
@RequestMapping("isLogin")
public String isLogin() {
return "当前会话是否登录:" + StpUtil.isLogin();
}
// 角色校验:必须具有指定角色才能进入该方法
@SaCheckRole("super-admin")
@RequestMapping("add")
public String add() {
return "用户增加";
}
// 权限校验:必须具有指定权限才能进入该方法
@SaCheckPermission("user-delete")
@RequestMapping("delete")
public String delete() {
return "用户删除";
}
// 二级认证校验:必须二级认证之后才能进入该方法
@SaCheckSafe()
@RequestMapping("remove")
public String remove() {
return "用户注销";
}
// Http Basic 校验:只有通过 Basic 认证后才能进入该方法
@SaCheckBasic(account = "sa:123456")
@RequestMapping("inf")
public String inf() {
return "用户信息";
}
// 校验当前账号是否被封禁 comment 服务,如果已被封禁会抛出异常,无法进入方法
@SaCheckDisable("comment")
@RequestMapping("send")
public String send() {
return "查询用户信息";
}
// 注解式鉴权:只要具有其中一个权限即可通过校验
@RequestMapping("atJurOr")
@SaCheckPermission(value = {"user-add", "user-all", "user-delete"}, mode = SaMode.OR)
public SaResult atJurOr() {
return SaResult.data("用户信息");
}
// mode有两种取值:
// SaMode.AND,标注一组权限,会话必须全部具有才可通过校验。
// SaMode.OR,标注一组权限,会话只要具有其一即可通过校验。
}
注:以上注解都可以加在类上,代表为这个类所有方法进行鉴权;(携带登录Token)
3. 在SpringCloud环境集成
3.1 配置网关服务
3.1.1 引入依赖
请引入此包
<!-- Sa-Token 权限认证(Reactor响应式集成), 在线文档:https://sa-token.cc -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-reactor-spring-boot-starter</artifactId>
<version>1.37.0</version>
</dependency>
<!-- Sa-Token 整合 Redis (使用 jackson 序列化方式) -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-redis-jackson</artifactId>
<version>1.37.0</version>
</dependency>
<!-- 提供Redis连接池 -->
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-pool2</artifactId>
</dependency>
注:如果你使用的 SpringBoot 3.x
,只需要将 sa-token-reactor-spring-boot-starter
修改为 sa-token-reactor-spring-boot3-starter
即可。
3.1.2 设置配置文件
# Sa-Token配置
sa-token:
# token名称 (同时也是cookie名称)
token-name: satoken
# token有效期,单位秒,-1代表永不过期
timeout: 2592000
# token临时有效期 (指定时间内无操作就视为token过期),单位秒
activity-timeout: -1
# 是否允许同一账号并发登录 (为false时新登录挤掉旧登录)
is-concurrent: true
# 在多人登录同一账号时,是否共用一个token (为false时每次登录新建一个token)
is-share: false
# token风格
token-style: uuid
# 是否输出操作日志
is-log: false
# 是否从cookie中读取token
is-read-cookie: false
# 是否从head中读取token
is-read-head: true
3.1.3 注册全局过滤器
同拦截器一样,为了避免不必要的性能浪费,Sa-Token全局过滤器默认处于关闭状态,若要使用过滤器组件,首先你需要注册它到项目中:
/**
* [Sa-Token 权限认证] 配置类
*/
@Configuration
public class SaTokenConfigure {
/**
* 注册 [Sa-Token全局过滤器]
*/
@Bean
public SaReactorFilter getSaServletFilter() {
return new SaReactorFilter()
// 指定 拦截路由 与 放行路由
.addInclude("/**").addExclude("/favicon.ico") /* 排除掉 /favicon.ico */
// 认证函数: 每次请求执行
.setAuth(obj -> {
System.out.println("---------- 进入Sa-Token全局认证 -----------");
// 登录认证 -- 拦截所有路由,并排除/user/doLogin 用于开放登录
SaRouter.match("/**", "/user/doLogin", r -> StpUtil.checkLogin());
// 角色认证 -- 拦截 /user/delete 的路由,必须具备[admin]角色角色才可以通过认证
SaRouter.match("/user/delete").check(r -> StpUtil.checkRole("admin"));
// 权限认证 -- 不同模块, 校验不同权限
SaRouter.match("/user/add", r -> StpUtil.checkPermission("user.add"));
})
// 异常处理函数:每次认证函数发生异常时执行此函数
.setError(e -> {
System.out.println("---------- 进入Sa-Token异常处理 -----------");
return SaResult.error(e.getMessage());
})
// 前置函数:在每次认证函数之前执行(BeforeAuth 不受 includeList 与 excludeList 的限制,所有请求都会进入)
.setBeforeAuth(obj -> {
// ---------- 设置跨域响应头 ----------
SaHolder.getResponse()
// 允许指定域访问跨域资源
.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();
});
}
}
注意事项:
- 在
[认证函数]
里,你可以写和拦截器里一致的代码,进行路由匹配鉴权,参考:路由拦截鉴权。
3.1.4 全局异常拦截
新建配置类GlobalExceptionHandler.java
@RestControllerAdvice
public class GlobalExceptionHandler {
// 全局异常拦截
@ExceptionHandler
public SaResult handlerException(Exception e) {
return SaResult.error(e.getMessage());
}
}
3.1.5 权限认证
你需要做的就是新建一个类,实现 StpInterface
接口,例如以下代码:
/**
* 自定义权限加载接口实现类
*/
@Component // 保证此类被 SpringBoot 扫描,完成 Sa-Token 的自定义权限验证扩展
public class StpInterfaceImpl implements StpInterface {
/**
* 返回一个账号所拥有的权限码集合
*/
@Override
public List<String> getPermissionList(Object loginId, String loginType) {
// 本 list 仅做模拟,实际项目中要根据具体业务逻辑来查询权限
List<String> list = new ArrayList<>();
list.add("101");
list.add("user.add");
list.add("user.update");
list.add("user.get");
list.add("art.*");
return list;
}
/**
* 返回一个账号所拥有的角色标识集合 (权限与角色可分开校验)
*/
@Override
public List<String> getRoleList(Object loginId, String loginType) {
// 本 list 仅做模拟,实际项目中要根据具体业务逻辑来查询角色
List<String> list = new ArrayList<Strin>();
list.add("super-admin");
return list;
}
}
参数解释:
- loginId:账号id,即你在调用
StpUtil.login(id)
时写入的标识值。 - loginType:账号体系标识。
3.2 业务模块
3.2.1 引入依赖
<!-- Sa-Token 权限认证,在线文档:https://sa-token.cc -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-spring-boot-starter</artifactId>
<version>1.37.0</version>
</dependency>
<!-- Sa-Token 整合 Redis (使用 jackson 序列化方式) -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-redis-jackson</artifactId>
<version>1.37.0</version>
</dependency>
<!-- 提供Redis连接池 -->
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-pool2</artifactId>
</dependency>
3.2.2 设置配置文件
application.yml 风格
############## Sa-Token 配置 ##############
sa-token:
# token 名称(同时也是 cookie 名称)
token-name: satoken
# token 有效期(单位:秒) 默认30天,-1 代表永久有效
timeout: 2592000
# token 最低活跃频率(单位:秒),如果 token 超过此时间没有访问系统就会被冻结,默认-1 代表不限制,永不冻结
active-timeout: -1
# 是否允许同一账号多地同时登录 (为 true 时允许一起登录, 为 false 时新登录挤掉旧登录)
is-concurrent: true
# 在多人登录同一账号时,是否共用一个 token (为 true 时所有登录共用一个 token, 为 false 时每次登录新建一个 token)
is-share: true
# token 风格(默认可取值:uuid、simple-uuid、random-32、random-64、random-128、tik)
token-style: uuid
# 是否输出操作日志
is-log: true
3.2.3 创建测试类
@RestController
@RequestMapping("/user/")
public class UserController {
// 登录接口
@RequestMapping("doLogin")
public SaResult doLogin() {
// 第1步,先登录上
StpUtil.login(10001);
// 第2步,获取 Token 相关参数
SaTokenInfo tokenInfo = StpUtil.getTokenInfo();
// 第3步,返回给前端
return SaResult.data(tokenInfo);
}
@RequestMapping("isLogin")
public SaResult isLogin() {
return SaResult.ok("当前会话是否登录:" + StpUtil.isLogin());
}
@RequestMapping("add")
public SaResult add() {
return SaResult.ok("用户注册");
}
@RequestMapping("delete")
public SaResult delete() {
return SaResult.ok("用户删除");
}
}