一、需求分析
在某些敏感操作下，我們需要對已登錄的會話進(jìn)行二次驗(yàn)證。
比如代碼托管平臺的倉庫刪除操作，盡管我們已經(jīng)登錄了賬號，當(dāng)我們點(diǎn)擊 [刪除] 按鈕時(shí)，還是需要再次輸入一遍密碼，這么做主要為了兩點(diǎn)：
- 保證操作者是當(dāng)前賬號本人。
- 增加操作步驟，防止誤刪除重要數(shù)據(jù)。
這就是我們本篇要講的 —— 二級認(rèn)證，即：在已登錄會話的基礎(chǔ)上，進(jìn)行再次驗(yàn)證，提高會話的安全性。
Sa-Token 是一個(gè)輕量級 java 權(quán)限認(rèn)證框架，主要解決登錄認(rèn)證、權(quán)限認(rèn)證、單點(diǎn)登錄、OAuth2、微服務(wù)網(wǎng)關(guān)鑒權(quán) 等一系列權(quán)限相關(guān)問題。
Gitee 開源地址：https://gitee.com/dromara/sa-token
本文將介紹在 SpringBoot 架構(gòu)下，如何使用 Sa-Token 完成二級認(rèn)證操作。
首先在項(xiàng)目中引入 Sa-Token 依賴：
<!-- Sa-Token 權(quán)限認(rèn)證 -->
<dependency>
<groupId>cn.dev33</groupId>
<artifactId>sa-token-spring-boot-starter</artifactId>
<version>1.34.0</version>
</dependency>
注：如果你使用的是 SpringBoot 3.x，只需要將 sa-token-spring-boot-starter 修改為 sa-token-spring-boot3-starter 即可。
二、具體API
在Sa-Token中進(jìn)行二級認(rèn)證非常簡單，只需要使用以下API：
// 在當(dāng)前會話 開啟二級認(rèn)證，時(shí)間為120秒
StpUtil.openSafe(120);
// 獲取：當(dāng)前會話是否處于二級認(rèn)證時(shí)間內(nèi)
StpUtil.isSafe();
// 檢查當(dāng)前會話是否已通過二級認(rèn)證，如未通過則拋出異常
StpUtil.checkSafe();
// 獲取當(dāng)前會話的二級認(rèn)證剩余有效時(shí)間 (單位: 秒, 返回-2代表尚未通過二級認(rèn)證)
StpUtil.getSafeTime();
// 在當(dāng)前會話 結(jié)束二級認(rèn)證
StpUtil.closeSafe();
三、一個(gè)小示例
一個(gè)完整的二級認(rèn)證業(yè)務(wù)流程，應(yīng)該大致如下：
package com.pj.cases.up;
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 二級認(rèn)證示例
*
* @author kong
* @since 2022-10-16
*/
@RestController
@RequestMapping("/safe/")
public class SafeAuthController {
// 刪除倉庫 ---- http://localhost:8081/safe/deleteProject
@RequestMapping("deleteProject")
public SaResult deleteProject(String projectId) {
// 第1步，先檢查當(dāng)前會話是否已完成二級認(rèn)證
// 這個(gè)地方既可以通過 StpUtil.isSafe() 手動判斷，
// 也可以通過 StpUtil.checkSafe() 或者 @SaCheckSafe 來校驗(yàn)（校驗(yàn)不通過時(shí)將拋出 NotSafeException 異常）
if(!StpUtil.isSafe()) {
return SaResult.error("倉庫刪除失敗，請完成二級認(rèn)證后再次訪問接口");
}
// 第2步，如果已完成二級認(rèn)證，則開始執(zhí)行業(yè)務(wù)邏輯
// ...
// 第3步，返回結(jié)果
return SaResult.ok("倉庫刪除成功");
}
// 提供密碼進(jìn)行二級認(rèn)證 ---- http://localhost:8081/safe/openSafe?password=123456
@RequestMapping("openSafe")
public SaResult openSafe(String password) {
// 比對密碼（此處只是舉例，真實(shí)項(xiàng)目時(shí)可拿其它參數(shù)進(jìn)行校驗(yàn)）
if("123456".equals(password)) {
// 比對成功，為當(dāng)前會話打開二級認(rèn)證，有效期為120秒，意為在120秒內(nèi)再調(diào)用 deleteProject 接口都無需提供密碼
StpUtil.openSafe(120);
return SaResult.ok("二級認(rèn)證成功");
}
// 如果密碼校驗(yàn)失敗，則二級認(rèn)證也會失敗
return SaResult.error("二級認(rèn)證失敗");
}
// 手動關(guān)閉二級認(rèn)證 ---- http://localhost:8081/safe/closeSafe
@RequestMapping("closeSafe")
public SaResult closeSafe() {
StpUtil.closeSafe();
return SaResult.ok();
}
}
全局異常攔截器，統(tǒng)一返回給前端的格式，參考：
@RestControllerAdvice
public class GlobalExceptionHandler {
// 全局異常攔截
@ExceptionHandler
public SaResult handlerException(Exception e) {
e.printStackTrace();
return SaResult.error(e.getMessage());
}
}
前提：二級認(rèn)證時(shí)我們必須處于登錄狀態(tài)（可參考之前的登錄認(rèn)證章節(jié)代碼），完成登錄后，調(diào)用接口進(jìn)行二級認(rèn)證校驗(yàn)：
- 前端調(diào)用 deleteProject 接口，嘗試刪除倉庫。 ----
http://localhost:8081/safe/deleteProject - 后端校驗(yàn)會話尚未完成二級認(rèn)證，返回： 倉庫刪除失敗，請完成二級認(rèn)證后再次訪問接口。
- 前端將信息提示給用戶，用戶輸入密碼，調(diào)用 openSafe 接口。 ----
http://localhost:8081/safe/openSafe?password=123456 - 后端比對用戶輸入的密碼，完成二級認(rèn)證，有效期為：120秒。
- 前端在 120 秒內(nèi)再次調(diào)用 deleteProject 接口，嘗試刪除倉庫。 ----
http://localhost:8081/safe/deleteProject - 后端校驗(yàn)會話已完成二級認(rèn)證，返回：倉庫刪除成功。
四、指定業(yè)務(wù)標(biāo)識進(jìn)行二級認(rèn)證
如果項(xiàng)目有多條業(yè)務(wù)線都需要敏感操作驗(yàn)證，則 StpUtil.openSafe() 無法提供細(xì)粒度的認(rèn)證操作，
此時(shí)我們可以指定一個(gè)業(yè)務(wù)標(biāo)識來分辨不同的業(yè)務(wù)線：
// 在當(dāng)前會話 開啟二級認(rèn)證，業(yè)務(wù)標(biāo)識為client，時(shí)間為600秒
StpUtil.openSafe("client", 600);
// 獲取：當(dāng)前會話是否已完成指定業(yè)務(wù)的二級認(rèn)證
StpUtil.isSafe("client");
// 校驗(yàn)：當(dāng)前會話是否已完成指定業(yè)務(wù)的二級認(rèn)證 ，如未認(rèn)證則拋出異常
StpUtil.checkSafe("client");
// 獲取當(dāng)前會話指定業(yè)務(wù)二級認(rèn)證剩余有效時(shí)間 (單位: 秒, 返回-2代表尚未通過二級認(rèn)證)
StpUtil.getSafeTime("client");
// 在當(dāng)前會話 結(jié)束指定業(yè)務(wù)標(biāo)識的二級認(rèn)證
StpUtil.closeSafe("client");
業(yè)務(wù)標(biāo)識可以填寫任意字符串，不同業(yè)務(wù)標(biāo)識之間的認(rèn)證互不影響，比如：
// 打開了業(yè)務(wù)標(biāo)識為 client 的二級認(rèn)證
StpUtil.openSafe("client");
// 判斷是否處于 shop 的二級認(rèn)證，會返回 false
StpUtil.isSafe("shop"); // 返回 false
// 也不會通過校驗(yàn)，會拋出異常
StpUtil.checkSafe("shop");
代碼示例：
package com.pj.cases.up;
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 二級認(rèn)證示例
*
* @author kong
* @since 2022-10-16
*/
@RestController
@RequestMapping("/safe/")
public class SafeAuthController {
// ------------------ 指定業(yè)務(wù)類型進(jìn)行二級認(rèn)證
// 獲取應(yīng)用秘鑰 ---- http://localhost:8081/safe/getClientSecret
@RequestMapping("getClientSecret")
public SaResult getClientSecret() {
// 第1步，先檢查當(dāng)前會話是否已完成 client業(yè)務(wù) 的二級認(rèn)證
StpUtil.checkSafe("client");
// 第2步，如果已完成二級認(rèn)證，則返回?cái)?shù)據(jù)
return SaResult.data("aaaa-bbbb-cccc-dddd-eeee");
}
// 提供手勢密碼進(jìn)行二級認(rèn)證 ---- http://localhost:8081/safe/openClientSafe?gesture=35789
@RequestMapping("openClientSafe")
public SaResult openClientSafe(String gesture) {
// 比對手勢密碼（此處只是舉例，真實(shí)項(xiàng)目時(shí)可拿其它參數(shù)進(jìn)行校驗(yàn)）
if("35789".equals(gesture)) {
// 比對成功，為當(dāng)前會話打開二級認(rèn)證：
// 業(yè)務(wù)類型為：client
// 有效期為600秒==10分鐘，意為在10分鐘內(nèi)，調(diào)用 getClientSecret 時(shí)都無需再提供手勢密碼
StpUtil.openSafe("client", 600);
return SaResult.ok("二級認(rèn)證成功");
}
// 如果密碼校驗(yàn)失敗，則二級認(rèn)證也會失敗
return SaResult.error("二級認(rèn)證失敗");
}
// 查詢當(dāng)前會話是否已完成指定的二級認(rèn)證 ---- http://localhost:8081/safe/isClientSafe
@RequestMapping("isClientSafe")
public SaResult isClientSafe() {
return SaResult.ok("當(dāng)前是否已完成 client 二級認(rèn)證：" + StpUtil.isSafe("client"));
}
}
五、使用注解進(jìn)行二級認(rèn)證
在一個(gè)方法上使用 @SaCheckSafe 注解，可以在代碼進(jìn)入此方法之前進(jìn)行一次二級認(rèn)證校驗(yàn)
// 二級認(rèn)證：必須二級認(rèn)證之后才能進(jìn)入該方法
@SaCheckSafe
@RequestMapping("add")
public String add() {
return "用戶增加";
}
// 指定業(yè)務(wù)類型，進(jìn)行二級認(rèn)證校驗(yàn)
@SaCheckSafe("art")
@RequestMapping("add2")
public String add2() {
return "文章增加";
}
標(biāo)注 @SaCheckSafe 的方法必須在二級認(rèn)證后才能訪問成功，其效果與代碼 StpUtil.checkSafe() 等同。
參考資料
- Sa-Token 文檔：https://sa-token.cc
- Gitee 倉庫地址：https://gitee.com/dromara/sa-token
- GitHub 倉庫地址：https://github.com/dromara/sa-token
