SpringBoot 使用 Sa-Token 完成注解鉴权功能

注解鉴权 —— 优雅的将鉴权与业务代码分离。本篇我们将介绍在 Sa-Token 中如何通过注解完成权限校验。

Sa-Token 是一个轻量级 java 权限认证框架，主要解决登录认证、权限认证、单点登录、OAuth2、微服务网关鉴权 等一系列权限相关问题。
Gitee 开源地址：https://gitee.com/dromara/sa-token

一、Sa-Token 鉴权注解一览

Sa-Token 为我们提供的鉴权注解包括但不限于以下：

• @SaCheckLogin: 登录校验 —— 只有登录之后才能进入该方法。
  
• @SaCheckRole("admin"): 角色校验 —— 必须具有指定角色标识才能进入该方法。
  
• @SaCheckPermission("user:add"): 权限校验 —— 必须具有指定权限才能进入该方法。
  
• @SaCheckSafe: 二级认证校验 —— 必须二级认证之后才能进入该方法。
  
• @SaCheckBasic: HttpBasic校验 —— 只有通过 Basic 认证后才能进入该方法。
  
• @SaCheckDisable("comment")：账号服务封禁校验 —— 校验当前账号指定服务是否被封禁。
  
• @SaIgnore：忽略校验 —— 表示被修饰的方法或类无需进行注解鉴权和路由拦截器鉴权。
  

首先在项目中引入 Sa-Token 依赖：

1. <dependency>
2.     <groupId>cn.dev33</groupId>
3.     <artifactId>sa-token-spring-boot-starter</artifactId>
4.     <version>1.34.0</version>
5. </dependency>

复制代码

注：如果你使用的是 SpringBoot 3.x，只需要将 sa-token-spring-boot-starter 修改为 sa-token-spring-boot3-starter 即可。
二、登录认证

Sa-Token 使用全局拦截器完成注解鉴权功能，为了不为项目带来不必要的性能负担，拦截器默认处于关闭状态

因此，为了使用注解鉴权，你必须手动将 Sa-Token 的全局拦截器注册到你项目中。
以SpringBoot2.0为例，新建配置类SaTokenConfigure.java

1. @Configuration
2. public class SaTokenConfigure implements WebMvcConfigurer {
3.         // 注册 Sa-Token 拦截器，打开注解式鉴权功能
4.         @Override
5.         public void addInterceptors(InterceptorRegistry registry) {
6.                 // 注册 Sa-Token 拦截器，打开注解式鉴权功能
7.                 registry.addInterceptor(new SaInterceptor()).addPathPatterns("/**");       
8.         }
9. }

复制代码

保证此类被springboot启动类扫描到即可。
新建 LoginController，添加以下代码：

1. /**
2. * 登录认证注解测试
3. */
4. @RestController
5. public class LoginController {
7.     // 访问 home 页，登录后才能访问  ---- http://localhost:8081/home
8.     @SaCheckLogin
9.     @RequestMapping("home")
10.     public SaResult home() {
11.         return SaResult.ok("访问成功，此处为登录后才能看到的信息");
12.     }
14.     // 登录接口  ---- http://localhost:8081/doLogin?name=zhang&pwd=123456
15.     @RequestMapping("doLogin")
16.     public SaResult doLogin(String name, String pwd) {
17.         // 此处仅作模拟示例，真实项目需要从数据库中查询数据进行比对
18.         if("zhang".equals(name) && "123456".equals(pwd)) {
19.             StpUtil.login(10001);
20.             return SaResult.ok("登录成功");
21.         }
22.         return SaResult.error("登录失败");
23.     }
25. }

复制代码

启动项目，首次访问资源接口：

1. http://localhost:8081/home

复制代码

返回如下：

1. {
2.         "code": 500,
3.         "msg": "未能读取到有效Token",
4.         "data": null
5. }

复制代码

会话尚未登录，因此无法访问资源。
现在我们再去访问一下登录接口：

1. http://localhost:8081/doLogin?name=zhang&pwd=123456

复制代码

返回如下：

1. {
2.         "code": 200,
3.         "msg": "登录成功",
4.         "data": null
5. }

复制代码

登录成功，我们再去访问资源接口：

1. http://localhost:8081/home

复制代码

返回如下：

1. {
2.         "code": 200,
3.         "msg": "访问成功，此处为登录后才能看到的信息",
4.         "data": null
5. }

复制代码

通过登录认证校验，成功获取到信息！
三、权限认证 & 角色认证

首先我们需要实现 StpInterface 接口，告诉框架指定账号拥有哪些权限码。

1. /**
2. * 自定义权限认证接口扩展，Sa-Token 将从此实现类获取每个账号拥有的权限码
3. *
4. * @author kong
5. * @since 2022-10-13
6. */
7. @Component        // 打开此注解，保证此类被springboot扫描，即可完成sa-token的自定义权限验证扩展
8. public class StpInterfaceImpl implements StpInterface {
10.         /**
11.          * 返回一个账号所拥有的权限码集合
12.          */
13.         @Override
14.         public List<String> getPermissionList(Object loginId, String loginType) {
15.                 // 本list仅做模拟，实际项目中要根据具体业务逻辑来查询权限
16.                 List<String> list = new ArrayList<String>();       
17.                 list.add("101");
18.                 list.add("user.add");
19.                 list.add("user.update");
20.                 list.add("user.get");
21.                 // list.add("user.delete");
22.                 list.add("art.*");
23.                 return list;
24.         }
26.         /**
27.          * 返回一个账号所拥有的角色标识集合
28.          */
29.         @Override
30.         public List<String> getRoleList(Object loginId, String loginType) {
31.                 // 本list仅做模拟，实际项目中要根据具体业务逻辑来查询角色
32.                 List<String> list = new ArrayList<String>();       
33.                 list.add("admin");
34.                 list.add("super-admin");
35.                 return list;
36.         }
38. }

复制代码

使用以下两个注解完成校验：

• @SaCheckPermission("user.add")：校验当前会话是否具有某个权限。
  
• @SaCheckRole("super-admin")：校验当前会话是否具有某个角色。
  

1. /**
2. * Sa-Token 注解鉴权示例
3. *
4. * @author kong
5. * @since 2022-10-13
6. */
7. @RestController
8. @RequestMapping("/at-check/")
9. public class AtCheckController {
11.         /*
12.          * 前提1：首先调用登录接口进行登录
13.          *                 ---- http://localhost:8081/doLogin?name=zhang&pwd=123456
14.          *
15.          * 前提2：项目在配置类中注册拦截器 SaInterceptor ，此拦截器将打开注解鉴权功能
16.          *
17.          * 前提3：项目实现了 StpInterface 接口，此接口会告诉框架指定账号拥有哪些权限码
18.          *
19.          * 然后我们就可以使用以下示例中的代码进行注解鉴权了
20.          */
21.        
22.         // 权限校验   ---- http://localhost:8081/at-check/checkPermission
23.         //                只有具有 user.add 权限的账号才可以进入方法
24.         @SaCheckPermission("user.add")
25.         @RequestMapping("checkPermission")
26.         public SaResult checkPermission() {
27.                 // ...
28.                 return SaResult.ok();
29.         }
31.         // 角色校验   ---- http://localhost:8081/at-check/checkRole
32.         //                只有具有 super-admin 角色的账号才可以进入方法
33.         @SaCheckRole("super-admin")
34.         @RequestMapping("checkRole")
35.         public SaResult checkRole() {
36.                 // ...
37.                 return SaResult.ok();
38.         }
39.        
40. }

复制代码

可根据代码注释提供的链接进行测试访问。
四、设定校验模式

@SaCheckRole与@SaCheckPermission注解可设置校验模式，例如：

1. // 注解式鉴权：只要具有其中一个权限即可通过校验
2. @RequestMapping("atJurOr")
3. @SaCheckPermission(value = {"user-add", "user-all", "user-delete"}, mode = SaMode.OR)               
4. public SaResult atJurOr() {
5.         return SaResult.data("用户信息");
6. }

复制代码

mode有两种取值：

• SaMode.AND, 标注一组权限，会话必须全部具有才可通过校验。
  
• SaMode.OR, 标注一组权限，会话只要具有其一即可通过校验。
  

五、角色权限双重 “or校验”

假设有以下业务场景：一个接口在具有权限 user.add 或角色 admin 时可以调通。怎么写？

1. // 角色权限双重 “or校验”：具备指定权限或者指定角色即可通过校验
2. @RequestMapping("userAdd")
3. @SaCheckPermission(value = "user.add", orRole = "admin")               
4. public SaResult userAdd() {
5.         return SaResult.data("用户信息");
6. }

复制代码

orRole 字段代表权限认证未通过时的次要选择，两者只要其一认证成功即可通过校验，其有三种写法：

• 写法一：orRole = "admin"，代表需要拥有角色 admin 。
  
• 写法二：orRole = {"admin", "manager", "staff"}，代表具有三个角色其一即可。
  
• 写法三：orRole = {"admin, manager, staff"}，代表必须同时具有三个角色。
  

六、二级认证

1. @RestController
2. @RequestMapping("/at/")
3. public class AtController {
5.         // 在当前会话完成二级认证  ---- http://localhost:8081/at/openSafe
6.         @RequestMapping("openSafe")
7.         public SaResult openSafe() {
8.                 StpUtil.openSafe(200); // 打开二级认证，有效期为200秒
9.                 return SaResult.ok();
10.         }
11.        
12.         // 通过二级认证后，才可以进入  ---- http://localhost:8081/at/checkSafe
13.         @SaCheckSafe
14.         @RequestMapping("checkSafe")
15.         public SaResult checkSafe() {
16.                 return SaResult.ok();
17.         }
19. }

复制代码

必须先经过 StpUtil.openSafe(1200) 打开二级认证（参数为指定认证有效期，单位：秒），才可以通过 @SaCheckSafe 的检查。
七、HttpBasic认证：

1. @RestController
2. @RequestMapping("/at/")
3. public class AtController {
5.         // 通过Basic认证后才可以进入  ---- http://localhost:8081/at/checkBasic
6.         @SaCheckBasic(account = "sa:123456")
7.         @RequestMapping("checkBasic")
8.         public SaResult checkBasic() {
9.                 return SaResult.ok();
10.         }
11.        
12. }

复制代码

当我们访问这个接口时，浏览器会强制弹出一个表单：

当我们输入账号密码后 （sa / 123456），才可以继续访问数据：

八、服务禁用性校验

1. @RestController
2. @RequestMapping("/at/")
3. public class AtController {
5.         // 只有当前服务没有禁用 comment 服务时，才能够进入方法  ---- http://localhost:8081/at/comment
6.         @SaCheckDisable("comment")
7.         @RequestMapping("comment")
8.         public SaResult comment() {
9.                 return SaResult.ok();
10.         }
12. }

复制代码

@SaCheckDisable 注解的作用是检测当前账号是否被禁用了指定服务，如果已被禁用则无法进入指定方法，
在之后的章节我们会详细讲述服务禁用的相关代码，此处先稍作了解即可。
九、忽略认证

使用 @SaIgnore 可表示一个接口忽略认证：

1. @SaCheckLogin
2. @RestController
3. public class TestController {
4.        
5.         // ... 其它方法
6.        
7.         // 此接口加上了 @SaIgnore 可以游客访问
8.         @SaIgnore
9.         @RequestMapping("getList")
10.         public SaResult getList() {
11.                 // ...
12.                 return SaResult.ok();
13.         }
14. }

复制代码

如上代码表示：TestController 中的所有方法都需要登录后才可以访问，但是 getList 接口可以匿名游客访问。

• @SaIgnore 修饰方法时代表这个方法可以被游客访问，修饰类时代表这个类中的所有接口都可以游客访问。
  
• @SaIgnore 具有最高优先级，当 @SaIgnore 和其它鉴权注解一起出现时，其它鉴权注解都将被忽略。
  
• @SaIgnore 同样可以忽略掉 Sa-Token 拦截器中的路由鉴权，在下面的 [路由拦截鉴权] 章节中我们会讲到。
  

十、在业务逻辑层使用注解鉴权

疑问：我能否将注解写在其它架构层呢，比如业务逻辑层？
使用拦截器模式，只能在Controller层进行注解鉴权，如需在任意层级使用注解鉴权，可使用 AOP注解鉴权 插件。

1. <dependency>
2.     <groupId>cn.dev33</groupId>
3.     <artifactId>sa-token-spring-aop</artifactId>
4.     <version>1.34.0</version>
5. </dependency>

复制代码

集成此插件后，便可以在任意层使用 Sa-Token 的注解鉴权了（例如业务逻辑层），不过需要注意的是：

• 拦截器模式和AOP模式不可同时集成，否则会在 Controller 层发生一个注解校验两次的bug。
  

参考资料

• Sa-Token 文档：https://sa-token.cc
  
• Gitee 仓库地址：https://gitee.com/dromara/sa-token
  
• GitHub 仓库地址：https://github.com/dromara/sa-token
  

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！