一文带你理解和使用轻量级权限框架 Sa-Token

介绍

Sa-Token 是一个轻量级 Java 权限认证框架，主要解决：登录认证 、权限认证 、单点登录 、OAuth2.0 、分布式Session会话 、微服务网关鉴权 等一系列权限相关问题

官方文档：sa-token.cc/doc.html#/

认证与授权

颁发令牌

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: true

properties 风格：

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-...