对敏感操作的二次认证 —— 详解 Sa-Token 二级认证

一、需求分析

在某些敏感操作下，我们需要对已登录的会话进行二次验证。
比如代码托管平台的仓库删除操作，尽管我们已经登录了账号，当我们点击 [删除] 按钮时，还是需要再次输入一遍密码，这么做主要为了两点：

• 保证操作者是当前账号本人。
  
• 增加操作步骤，防止误删除重要数据。
  

这就是我们本篇要讲的 —— 二级认证，即：在已登录会话的基础上，进行再次验证，提高会话的安全性。

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

本文将介绍在 SpringBoot 架构下，如何使用 Sa-Token 完成二级认证操作。
首先在项目中引入 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 即可。
二、具体API

在Sa-Token中进行二级认证非常简单，只需要使用以下API：

1. // 在当前会话 开启二级认证，时间为120秒
2. StpUtil.openSafe(120);
4. // 获取：当前会话是否处于二级认证时间内
5. StpUtil.isSafe();
7. // 检查当前会话是否已通过二级认证，如未通过则抛出异常
8. StpUtil.checkSafe();
10. // 获取当前会话的二级认证剩余有效时间 (单位: 秒, 返回-2代表尚未通过二级认证)
11. StpUtil.getSafeTime();
13. // 在当前会话 结束二级认证
14. StpUtil.closeSafe();

复制代码

三、一个小示例

一个完整的二级认证业务流程，应该大致如下：

1. package com.pj.cases.up;
3. import org.springframework.web.bind.annotation.RequestMapping;
4. import org.springframework.web.bind.annotation.RestController;
6. import cn.dev33.satoken.stp.StpUtil;
7. import cn.dev33.satoken.util.SaResult;
9. /**
10. * Sa-Token 二级认证示例
11. *
12. * @author kong
13. * @since 2022-10-16
14. */
15. @RestController
16. @RequestMapping("/safe/")
17. public class SafeAuthController {
18.        
19.         // 删除仓库    ---- http://localhost:8081/safe/deleteProject
20.         @RequestMapping("deleteProject")
21.         public SaResult deleteProject(String projectId) {
22.             // 第1步，先检查当前会话是否已完成二级认证
23.                 //                 这个地方既可以通过 StpUtil.isSafe() 手动判断，
24.                 //                 也可以通过 StpUtil.checkSafe() 或者 @SaCheckSafe 来校验（校验不通过时将抛出 NotSafeException 异常）
25.             if(!StpUtil.isSafe()) {
26.                 return SaResult.error("仓库删除失败，请完成二级认证后再次访问接口");
27.             }
28.        
29.             // 第2步，如果已完成二级认证，则开始执行业务逻辑
30.             // ...
31.        
32.             // 第3步，返回结果
33.             return SaResult.ok("仓库删除成功");
34.         }
35.        
36.         // 提供密码进行二级认证    ---- http://localhost:8081/safe/openSafe?password=123456
37.         @RequestMapping("openSafe")
38.         public SaResult openSafe(String password) {
39.             // 比对密码（此处只是举例，真实项目时可拿其它参数进行校验）
40.             if("123456".equals(password)) {
41.        
42.                 // 比对成功，为当前会话打开二级认证，有效期为120秒，意为在120秒内再调用 deleteProject 接口都无需提供密码
43.                 StpUtil.openSafe(120);
44.                 return SaResult.ok("二级认证成功");
45.             }
46.        
47.             // 如果密码校验失败，则二级认证也会失败
48.             return SaResult.error("二级认证失败");
49.         }
51.         // 手动关闭二级认证    ---- http://localhost:8081/safe/closeSafe
52.         @RequestMapping("closeSafe")
53.         public SaResult closeSafe() {
54.                 StpUtil.closeSafe();
55.             return SaResult.ok();
56.         }
58. }

复制代码

全局异常拦截器，统一返回给前端的格式，参考：

1. @RestControllerAdvice
2. public class GlobalExceptionHandler {
3.     // 全局异常拦截
4.     @ExceptionHandler
5.     public SaResult handlerException(Exception e) {
6.         e.printStackTrace();
7.         return SaResult.error(e.getMessage());
8.     }
9. }

复制代码

前提：二级认证时我们必须处于登录状态（可参考之前的登录认证章节代码），完成登录后，调用接口进行二级认证校验：

• 前端调用 deleteProject 接口，尝试删除仓库。    ---- http://localhost:8081/safe/deleteProject
  
• 后端校验会话尚未完成二级认证，返回： 仓库删除失败，请完成二级认证后再次访问接口。
  
• 前端将信息提示给用户，用户输入密码，调用 openSafe 接口。    ---- http://localhost:8081/safe/openSafe?password=123456
  
• 后端比对用户输入的密码，完成二级认证，有效期为：120秒。
  
• 前端在 120 秒内再次调用 deleteProject 接口，尝试删除仓库。    ---- http://localhost:8081/safe/deleteProject
  
• 后端校验会话已完成二级认证，返回：仓库删除成功。
  

四、指定业务标识进行二级认证

如果项目有多条业务线都需要敏感操作验证，则 StpUtil.openSafe() 无法提供细粒度的认证操作，
此时我们可以指定一个业务标识来分辨不同的业务线：

1. // 在当前会话 开启二级认证，业务标识为client，时间为600秒
2. StpUtil.openSafe("client", 600);
4. // 获取：当前会话是否已完成指定业务的二级认证
5. StpUtil.isSafe("client");
7. // 校验：当前会话是否已完成指定业务的二级认证 ，如未认证则抛出异常
8. StpUtil.checkSafe("client");
10. // 获取当前会话指定业务二级认证剩余有效时间 (单位: 秒, 返回-2代表尚未通过二级认证)
11. StpUtil.getSafeTime("client");
13. // 在当前会话 结束指定业务标识的二级认证
14. StpUtil.closeSafe("client");

复制代码

业务标识可以填写任意字符串，不同业务标识之间的认证互不影响，比如：

1. // 打开了业务标识为 client 的二级认证
2. StpUtil.openSafe("client");
4. // 判断是否处于 shop 的二级认证，会返回 false
5. StpUtil.isSafe("shop");  // 返回 false
7. // 也不会通过校验，会抛出异常
8. StpUtil.checkSafe("shop");

复制代码

代码示例：

1. package com.pj.cases.up;
3. import org.springframework.web.bind.annotation.RequestMapping;
4. import org.springframework.web.bind.annotation.RestController;
6. import cn.dev33.satoken.stp.StpUtil;
7. import cn.dev33.satoken.util.SaResult;
9. /**
10. * Sa-Token 二级认证示例
11. *
12. * @author kong
13. * @since 2022-10-16
14. */
15. @RestController
16. @RequestMapping("/safe/")
17. public class SafeAuthController {
19.         // ------------------ 指定业务类型进行二级认证
21.         // 获取应用秘钥    ---- http://localhost:8081/safe/getClientSecret
22.         @RequestMapping("getClientSecret")
23.         public SaResult getClientSecret() {
24.             // 第1步，先检查当前会话是否已完成 client业务 的二级认证
25.                 StpUtil.checkSafe("client");
26.        
27.             // 第2步，如果已完成二级认证，则返回数据
28.             return SaResult.data("aaaa-bbbb-cccc-dddd-eeee");
29.         }
30.        
31.         // 提供手势密码进行二级认证    ---- http://localhost:8081/safe/openClientSafe?gesture=35789
32.         @RequestMapping("openClientSafe")
33.         public SaResult openClientSafe(String gesture) {
34.             // 比对手势密码（此处只是举例，真实项目时可拿其它参数进行校验）
35.             if("35789".equals(gesture)) {
36.        
37.                 // 比对成功，为当前会话打开二级认证：
38.                     // 业务类型为：client
39.                     // 有效期为600秒==10分钟，意为在10分钟内，调用 getClientSecret 时都无需再提供手势密码
40.                 StpUtil.openSafe("client", 600);
41.                 return SaResult.ok("二级认证成功");
42.             }
43.        
44.             // 如果密码校验失败，则二级认证也会失败
45.             return SaResult.error("二级认证失败");
46.         }
48.         // 查询当前会话是否已完成指定的二级认证    ---- http://localhost:8081/safe/isClientSafe
49.         @RequestMapping("isClientSafe")
50.         public SaResult isClientSafe() {
51.             return SaResult.ok("当前是否已完成 client 二级认证：" + StpUtil.isSafe("client"));
52.         }
54. }

复制代码

五、使用注解进行二级认证

在一个方法上使用 @SaCheckSafe 注解，可以在代码进入此方法之前进行一次二级认证校验

1. // 二级认证：必须二级认证之后才能进入该方法
2. @SaCheckSafe      
3. @RequestMapping("add")
4. public String add() {
5.     return "用户增加";
6. }
8. // 指定业务类型，进行二级认证校验
9. @SaCheckSafe("art")
10. @RequestMapping("add2")
11. public String add2() {
12.     return "文章增加";
13. }

复制代码

标注 @SaCheckSafe 的方法必须在二级认证后才能访问成功，其效果与代码 StpUtil.checkSafe() 等同。
参考资料

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

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