介绍
Sa-Token 是一个轻量级 Java 权限认证框架，主要解决：登录认证 、权限认证 、单点登录 、OAuth2.0 、分布式Session会话 、微服务网关鉴权 等一系列权限相关问题
认证与授权
颁发令牌
SaToken 框架只会在两种业务场景中用到：登录与访问，在登录场景中，用户登录的时候会经过 Java 项目对登录用户名和密码的核对，允许用户登录系统。这时候需要我们调用 SaToken 的工具类（StpUtil）创建令牌字符串 （Token），SaToken 生成的令牌字符串会被缓存到 Redis 中，接下来 Web 方法会把这个令牌字符串写到 Http 响应返回给客户端
在 SaToken 框架中，颁发令牌非常简单，只需要调用 StpUtil 工具类的方法即可，我们需要向 SaToken 会话对象提供当前用户的 userId，然后 SaToken 才可以生成 Token 令牌。换而言之，如果将来我们拿到用户的令牌，SaTOken可以方向解析出用户的 userId，我们就能知道是哪个用户访问的 Web 方法
java
// 向当前 SaToken 会话对象传递用户 ID, 只有提供了用户 ID 才能生成令牌
StpUtil.login(userId);
// 生成令牌字符串
String token = StpUtil.getTokenValue();验证令牌
用户成功登录系统之后，客户端每次访问 Web 方法的时候，必须要上传 Token 令牌。如果不上传令牌，Java项目可以认定用户没有登录系统，所以拒绝客户端访问 Web 方法。即便客户端提交了令牌，SaToken 还是需要认真检查令牌的真伪。如果无法从令牌中反向解析出用户 ID 和令牌过期时间，那么就可以认定令牌是伪造的，SaToken则拒绝客户端访问Web方法。即时破解了 SaToken 生成令牌的算法，但是有 Redis 在之前保存，破解后生成的令牌就会无效
不是所有的 Web 方法或者 HTML 页面都需要用户登录之后才能访问，比如登录页面和对应的后端 Web 方法。但是有些 Web 方法必须用户登录之后才能访问，我们可以给 Web 方法添加 @SacheckLogin 注解。这个注解就会拦截 Web 方法的请求，让 SaToken 验证客户端提交的 Token 令牌。如果令牌合法就允许调用 Web 方法，反之就拒绝 HTTP 请求，返回 401 状态码
java
@RestController
@RequestMapping("/test")
public class TestController (
@GetMapping("/search")
@SaCheckLogin
public Result search() {
}
)权限验证
登录的用户身份是不同的，有超级管理员、普通管理员、普通用户等等，如果不具备相关的权限，SaToken就会拒绝客户端访问的部分需要权限的方法
设置了 @SacheckPermission注解，可以验证用户是否具有 ROOT 或者 APPOINTENT:SELECT
java
@RestController
@RequestMapping("/test")
public class TestController (
@GetMapping("/search")
@SaCheckPermission(value = {"ROOT", "APPOINTENT:SELECT"}, mode = SaMode.OR)
public Result search() {
}
)写了@SacheckPermission注解就不需要@SacheckLogin 注解，因为 @SacheckPermission注解执行的时候也是需要先验证Token的，并且从Token中解析出userId，所以就不需要再写@SacheckLogin注解
依赖
注：如果你使用的是 SpringBoot 3.x，只需要将 sa-token-spring-boot-starter 修改为 sa-token-spring-boot3-starter 即可。
xml
<!-- Sa-Token 权限认证 -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-spring-boot-starter</artifactId>
<version>1.34.0</version>
</dependency>配置文件
yml 风格：
yaml
server:
# 端口
port: 8081
############## Sa-Token 配置 (文档: https://sa-token.cc) ##############
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: trueproperties 风格：
properties
# 端口
server.port=8081
############## Sa-Token 配置 (文档: https://sa-token.cc) ##############
# token 名称（同时也是 cookie 名称）
sa-token.token-name=satoken
# token 有效期（单位：秒） 默认30天，-1 代表永久有效
sa-token.timeout=2592000
# token 最低活跃频率（单位：秒），如果 token 超过此时间没有访问系统就会被冻结，默认-1 代表不限制，永不冻结
sa-token.active-timeout=-1
# 是否允许同一账号多地同时登录 （为 true 时允许一起登录, 为 false 时新登录挤掉旧登录）
sa-token.is-concurrent=true
# 在多人登录同一账号时，是否共用一个 token （为 true 时所有登录共用一个 token, 为 false 时每次登录新建一个 token）
sa-token.is-share=true
# token 风格（默认可取值：uuid、simple-uuid、random-32、random-64、random-128、tik）
sa-token.token-style=uuid
# 是否输出操作日志
sa-token.is-log=true创建启动类
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());
}
}创建测试Controller
java
@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();
}
}运行测试
启动代码，从浏览器依次访问上述测试接口，如下图代表集成成功
获取当前账号权限集合（鉴权类）
因为每个项目的需求不同，鉴权类是需要我们自己实现的，必须要扩展 StpInterface 接口才可以，一般来说我们不通过角色进行鉴权：权限是固定的，角色是可以动态增减，如果将来角色被删除，不可能重新写代码
创建一个 StpInterfaceImpl 类
java
@Component
public class StpInterFaceImpl implements StpInterface {
@Autowired
private UserMapper usermapper;
/**
* 返回一个用户所拥有的权限集合
*/
@Override
public List<String> getPermissionList(Object loginId, String loginType) {
List<String> list = new ArrayList<>();
// int userId = Integer.parseInt(loginId.toString());
// list = usermapper.searchUserPermissions(userId);
// 模拟
list.add("101");
list.add("user.add");
list.add("user.update");
list.add("user.get");
// list.add("user.delete");
list.add("art.*");
return list;
}
/**
* 返回一个用户所拥有的角色标识集合（根据上述原因返回 null,不需要此功能）
*/
@Override
public List<String> getRoleList(Object loginId, String loginKey) {
ArrayList<String> list = new ArrayList();
return list;
}
}参数解释：
- loginId：账号id，即你在调用
StpUtil.login(id)时写入的标识值。 - loginType：账号体系标识，此处可以暂时忽略，在 [ 多账户认证 ] 章节下会对这个概念做详细的解释。
**注意点：**类上一定要加上 @Component 注解，保证组件被 Springboot 扫描到，成功注入到 Sa-Token 框架内。
权限校验
然后就可以用以下 api 来鉴权了
java
// 获取：当前账号所拥有的权限集合
StpUtil.getPermissionList();
// 判断：当前账号是否含有指定权限, 返回 true 或 false
StpUtil.hasPermission("user.add");
// 校验：当前账号是否含有指定权限, 如果验证未通过，则抛出异常: NotPermissionException
StpUtil.checkPermission("user.add");
// 校验：当前账号是否含有指定权限 [指定多个，必须全部验证通过]
StpUtil.checkPermissionAnd("user.add", "user.delete", "user.get");
// 校验：当前账号是否含有指定权限 [指定多个，只要其一验证通过即可]
StpUtil.checkPermissionOr("user.add", "user.delete", "user.get"); 角色校验
在 Sa-Token 中，角色和权限可以分开独立验证，不过我们一般还是不用角色校验
java
// 获取：当前账号所拥有的角色集合
StpUtil.getRoleList();
// 判断：当前账号是否拥有指定角色, 返回 true 或 false
StpUtil.hasRole("super-admin");
// 校验：当前账号是否含有指定角色标识, 如果验证未通过，则抛出异常: NotRoleException
StpUtil.checkRole("super-admin");
// 校验：当前账号是否含有指定角色标识 [指定多个，必须全部验证通过]
StpUtil.checkRoleAnd("super-admin", "shop-admin");
// 校验：当前账号是否含有指定角色标识 [指定多个，只要其一验证通过即可]
StpUtil.checkRoleOr("super-admin", "shop-admin"); 拦截全局异常
鉴权失败，抛出异常，创建一个全局异常拦截器，统一返回给前端的格式，可以自己定义：
java
@RestControllerAdvice
public class GlobalExceptionHandler {
// 全局异常拦截
@ExceptionHandler
public SaResult handlerException(Exception e) {
e.printStackTrace();
return SaResult.error(e.getMessage());
}
}权限通配符
Sa-Token允许你根据通配符指定泛权限 ，例如当一个账号拥有art.*的权限时，art.add、art.delete、art.update都将匹配通过
java
// 当拥有 art.* 权限时
StpUtil.hasPermission("art.add"); // true
StpUtil.hasPermission("art.update"); // true
StpUtil.hasPermission("goods.add"); // false
// 当拥有 *.delete 权限时
StpUtil.hasPermission("art.delete"); // true
StpUtil.hasPermission("user.delete"); // true
StpUtil.hasPermission("user.update"); // false
// 当拥有 *.js 权限时
StpUtil.hasPermission("index.js"); // true
StpUtil.hasPermission("index.css"); // false
StpUtil.hasPermission("index.html"); // false上帝权限：当一个账号拥有
"*"权限时，他可以验证通过任何权限码 （角色认证同理）
把权限精确到按钮级
权限精确到按钮级的意思就是指：权限范围可以控制到页面上的每一个按钮是否显示。
思路：如此精确的范围控制只依赖后端已经难以完成，此时需要前端进行一定的逻辑判断。
如果是前后端一体项目，可以参考：Thymeleaf 标签方言，如果是前后端分离项目，则：
- 在登录时，把当前账号拥有的所有权限码一次性返回给前端。
- 前端将权限码集合保存在
localStorage或其它全局状态管理对象中。 - 在需要权限控制的按钮上，使用 js 进行逻辑判断，例如在
Vue框架中我们可以使用如下写法：
js
复制代码<button v-if="arr.indexOf('user.delete') > -1">删除按钮</button>其中：arr是当前用户拥有的权限码数组，user.delete是显示按钮需要拥有的权限码，删除按钮是用户拥有权限码才可以看到的内容。
注意：以上写法只为提供一个参考示例，不同框架有不同写法，大家可根据项目技术栈灵活封装进行调用。
前端有了鉴权后端还需要鉴权吗？
需要！
前端的鉴权只是一个辅助功能，对于专业人员这些限制都是可以轻松绕过的， 为保证服务器安全，无论前端是否进行了权限校验，后端接口都需要对会话请求再次进行权限校验！
代码示例
java
package com.pj.cases.use;
import java.util.List;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import cn.dev33.satoken.stp.StpUtil;
import cn.dev33.satoken.util.SaResult;
/**
* Sa-Token 权限认证示例
*
* @author kong
* @since 2022-10-13
*/
@RestController
@RequestMapping("/jur/")
public class JurAuthController {
/*
* 前提1：首先调用登录接口进行登录，代码在 com.pj.cases.use.LoginAuthController 中有详细解释，此处不再赘述
* ---- http://localhost:8081/acc/doLogin?name=zhang&pwd=123456
*
* 前提2：项目实现 StpInterface 接口，代码在 com.pj.satoken.StpInterfaceImpl
* Sa-Token 将从此实现类获取 每个账号拥有哪些权限。
*
* 然后我们就可以使用以下示例中的代码进行鉴权了
*/
// 查询权限 ---- http://localhost:8081/jur/getPermission
@RequestMapping("getPermission")
public SaResult getPermission() {
// 查询权限信息 ，如果当前会话未登录，会返回一个空集合
List<String> permissionList = StpUtil.getPermissionList();
System.out.println("当前登录账号拥有的所有权限：" + permissionList);
// 查询角色信息 ，如果当前会话未登录，会返回一个空集合
List<String> roleList = StpUtil.getRoleList();
System.out.println("当前登录账号拥有的所有角色：" + roleList);
// 返回给前端
return SaResult.ok()
.set("roleList", roleList)
.set("permissionList", permissionList);
}
// 权限校验 ---- http://localhost:8081/jur/checkPermission
@RequestMapping("checkPermission")
public SaResult checkPermission() {
// 判断：当前账号是否拥有一个权限，返回 true 或 false
// 如果当前账号未登录，则永远返回 false
StpUtil.hasPermission("user.add");
StpUtil.hasPermissionAnd("user.add", "user.delete", "user.get"); // 指定多个，必须全部拥有才会返回 true
StpUtil.hasPermissionOr("user.add", "user.delete", "user.get"); // 指定多个，只要拥有一个就会返回 true
// 校验：当前账号是否拥有一个权限，校验不通过时会抛出 `NotPermissionException` 异常
// 如果当前账号未登录，则永远校验失败
StpUtil.checkPermission("user.add");
StpUtil.checkPermissionAnd("user.add", "user.delete", "user.get"); // 指定多个，必须全部拥有才会校验通过
StpUtil.checkPermissionOr("user.add", "user.delete", "user.get"); // 指定多个，只要拥有一个就会校验通过
return SaResult.ok();
}
// 角色校验 ---- http://localhost:8081/jur/checkRole
@RequestMapping("checkRole")
public SaResult checkRole() {
// 判断：当前账号是否拥有一个角色，返回 true 或 false
// 如果当前账号未登录，则永远返回 false
StpUtil.hasRole("admin");
StpUtil.hasRoleAnd("admin", "ceo", "cfo"); // 指定多个，必须全部拥有才会返回 true
StpUtil.hasRoleOr("admin", "ceo", "cfo"); // 指定多个，只要拥有一个就会返回 true
// 校验：当前账号是否拥有一个角色，校验不通过时会抛出 `NotRoleException` 异常
// 如果当前账号未登录，则永远校验失败
StpUtil.checkRole("admin");
StpUtil.checkRoleAnd("admin", "ceo", "cfo"); // 指定多个，必须全部拥有才会校验通过
StpUtil.checkRoleOr("admin", "ceo", "cfo"); // 指定多个，只要拥有一个就会校验通过
return SaResult.ok();
}
// 权限通配符 ---- http://localhost:8081/jur/wildcardPermission
@RequestMapping("wildcardPermission")
public SaResult wildcardPermission() {
// 前提条件：在 StpInterface 实现类中，为账号返回了 "art.*" 泛权限
StpUtil.hasPermission("art.add"); // 返回 true
StpUtil.hasPermission("art.delete"); // 返回 true
StpUtil.hasPermission("goods.add"); // 返回 false，因为前缀不符合
// * 符合可以出现在任意位置，比如权限码的开头，当账号拥有 "*.delete" 时
StpUtil.hasPermission("goods.add"); // false
StpUtil.hasPermission("goods.delete"); // true
StpUtil.hasPermission("art.delete"); // true
// 也可以出现在权限码的中间，比如当账号拥有 "shop.*.user" 时
StpUtil.hasPermission("shop.add.user"); // true
StpUtil.hasPermission("shop.delete.user"); // true
StpUtil.hasPermission("shop.delete.goods"); // false，因为后缀不符合
// 注意点：
// 1、上帝权限：当一个账号拥有 "*" 权限时，他可以验证通过任何权限码
// 2、角色校验也可以加 * ，指定泛角色，例如： "*.admin"，暂不赘述
return SaResult.ok();
}
}参考资料
- Sa-Token 文档：sa-token.cc
- Gitee 仓库地址：gitee.com/dromara/sa-...
- GitHub 仓库地址：github.com/dromara/sa-...