一烹笔、需求分析
在某些敏感操作下裳扯，我們需要對(duì)已登錄的會(huì)話(huà)進(jìn)行二次驗(yàn)證。
比如代碼托管平臺(tái)的倉(cāng)庫(kù)刪除操作谤职，盡管我們已經(jīng)登錄了賬號(hào)饰豺，當(dāng)我們點(diǎn)擊 [刪除] 按鈕時(shí)，還是需要再次輸入一遍密碼允蜈，這么做主要為了兩點(diǎn)：
- 保證操作者是當(dāng)前賬號(hào)本人冤吨。
- 增加操作步驟，防止誤刪除重要數(shù)據(jù)饶套。
這就是我們本篇要講的 —— 二級(jí)認(rèn)證锅很，即：在已登錄會(huì)話(huà)的基礎(chǔ)上，進(jìn)行再次驗(yàn)證凤跑，提高會(huì)話(huà)的安全性。
Sa-Token 是一個(gè)輕量級(jí) 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)問(wèn)題。
Gitee 開(kāi)源地址：https://gitee.com/dromara/sa-token
本文將介紹在 SpringBoot 架構(gòu)下撬码，如何使用 Sa-Token 完成二級(jí)認(rèn)證操作儿倒。
首先在項(xiàng)目中引入 Sa-Token 依賴(lài)：
<!-- 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)行二級(jí)認(rèn)證非常簡(jiǎn)單，只需要使用以下API：
// 在當(dāng)前會(huì)話(huà) 開(kāi)啟二級(jí)認(rèn)證叫胁，時(shí)間為120秒
StpUtil.openSafe(120);
// 獲然舜取：當(dāng)前會(huì)話(huà)是否處于二級(jí)認(rèn)證時(shí)間內(nèi)
StpUtil.isSafe();
// 檢查當(dāng)前會(huì)話(huà)是否已通過(guò)二級(jí)認(rèn)證，如未通過(guò)則拋出異常
StpUtil.checkSafe();
// 獲取當(dāng)前會(huì)話(huà)的二級(jí)認(rèn)證剩余有效時(shí)間 (單位: 秒, 返回-2代表尚未通過(guò)二級(jí)認(rèn)證)
StpUtil.getSafeTime();
// 在當(dāng)前會(huì)話(huà) 結(jié)束二級(jí)認(rèn)證
StpUtil.closeSafe();
三驼鹅、一個(gè)小示例
一個(gè)完整的二級(jí)認(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 二級(jí)認(rèn)證示例
*
* @author kong
* @since 2022-10-16
*/
@RestController
@RequestMapping("/safe/")
public class SafeAuthController {
// 刪除倉(cāng)庫(kù) ---- http://localhost:8081/safe/deleteProject
@RequestMapping("deleteProject")
public SaResult deleteProject(String projectId) {
// 第1步森篷，先檢查當(dāng)前會(huì)話(huà)是否已完成二級(jí)認(rèn)證
// 這個(gè)地方既可以通過(guò) StpUtil.isSafe() 手動(dòng)判斷，
// 也可以通過(guò) StpUtil.checkSafe() 或者 @SaCheckSafe 來(lái)校驗(yàn)（校驗(yàn)不通過(guò)時(shí)將拋出 NotSafeException 異常）
if(!StpUtil.isSafe()) {
return SaResult.error("倉(cāng)庫(kù)刪除失敗豺型，請(qǐng)完成二級(jí)認(rèn)證后再次訪問(wèn)接口");
}
// 第2步仲智，如果已完成二級(jí)認(rèn)證，則開(kāi)始執(zhí)行業(yè)務(wù)邏輯
// ...
// 第3步姻氨，返回結(jié)果
return SaResult.ok("倉(cāng)庫(kù)刪除成功");
}
// 提供密碼進(jìn)行二級(jí)認(rèn)證 ---- http://localhost:8081/safe/openSafe?password=123456
@RequestMapping("openSafe")
public SaResult openSafe(String password) {
// 比對(duì)密碼（此處只是舉例钓辆，真實(shí)項(xiàng)目時(shí)可拿其它參數(shù)進(jìn)行校驗(yàn)）
if("123456".equals(password)) {
// 比對(duì)成功，為當(dāng)前會(huì)話(huà)打開(kāi)二級(jí)認(rèn)證哼绑，有效期為120秒岩馍，意為在120秒內(nèi)再調(diào)用 deleteProject 接口都無(wú)需提供密碼
StpUtil.openSafe(120);
return SaResult.ok("二級(jí)認(rèn)證成功");
}
// 如果密碼校驗(yàn)失敗，則二級(jí)認(rèn)證也會(huì)失敗
return SaResult.error("二級(jí)認(rèn)證失敗");
}
// 手動(dòng)關(guān)閉二級(jí)認(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());
}
}
前提：二級(jí)認(rèn)證時(shí)我們必須處于登錄狀態(tài)（可參考之前的登錄認(rèn)證章節(jié)代碼），完成登錄后茂浮，調(diào)用接口進(jìn)行二級(jí)認(rèn)證校驗(yàn)：
- 前端調(diào)用 deleteProject 接口双谆，嘗試刪除倉(cāng)庫(kù)。 ----
http://localhost:8081/safe/deleteProject - 后端校驗(yàn)會(huì)話(huà)尚未完成二級(jí)認(rèn)證席揽，返回： 倉(cāng)庫(kù)刪除失敗顽馋，請(qǐng)完成二級(jí)認(rèn)證后再次訪問(wèn)接口。
- 前端將信息提示給用戶(hù)幌羞，用戶(hù)輸入密碼寸谜，調(diào)用 openSafe 接口。 ----
http://localhost:8081/safe/openSafe?password=123456 - 后端比對(duì)用戶(hù)輸入的密碼属桦，完成二級(jí)認(rèn)證熊痴，有效期為：120秒。
- 前端在 120 秒內(nèi)再次調(diào)用 deleteProject 接口聂宾，嘗試刪除倉(cāng)庫(kù)果善。 ----
http://localhost:8081/safe/deleteProject - 后端校驗(yàn)會(huì)話(huà)已完成二級(jí)認(rèn)證，返回：倉(cāng)庫(kù)刪除成功系谐。
四巾陕、指定業(yè)務(wù)標(biāo)識(shí)進(jìn)行二級(jí)認(rèn)證
如果項(xiàng)目有多條業(yè)務(wù)線都需要敏感操作驗(yàn)證，則 StpUtil.openSafe() 無(wú)法提供細(xì)粒度的認(rèn)證操作纪他，
此時(shí)我們可以指定一個(gè)業(yè)務(wù)標(biāo)識(shí)來(lái)分辨不同的業(yè)務(wù)線：
// 在當(dāng)前會(huì)話(huà) 開(kāi)啟二級(jí)認(rèn)證鄙煤，業(yè)務(wù)標(biāo)識(shí)為client，時(shí)間為600秒
StpUtil.openSafe("client", 600);
// 獲炔杼弧：當(dāng)前會(huì)話(huà)是否已完成指定業(yè)務(wù)的二級(jí)認(rèn)證
StpUtil.isSafe("client");
// 校驗(yàn)：當(dāng)前會(huì)話(huà)是否已完成指定業(yè)務(wù)的二級(jí)認(rèn)證 馆类，如未認(rèn)證則拋出異常
StpUtil.checkSafe("client");
// 獲取當(dāng)前會(huì)話(huà)指定業(yè)務(wù)二級(jí)認(rèn)證剩余有效時(shí)間 (單位: 秒, 返回-2代表尚未通過(guò)二級(jí)認(rèn)證)
StpUtil.getSafeTime("client");
// 在當(dāng)前會(huì)話(huà) 結(jié)束指定業(yè)務(wù)標(biāo)識(shí)的二級(jí)認(rèn)證
StpUtil.closeSafe("client");
業(yè)務(wù)標(biāo)識(shí)可以填寫(xiě)任意字符串，不同業(yè)務(wù)標(biāo)識(shí)之間的認(rèn)證互不影響弹谁，比如：
// 打開(kāi)了業(yè)務(wù)標(biāo)識(shí)為 client 的二級(jí)認(rèn)證
StpUtil.openSafe("client");
// 判斷是否處于 shop 的二級(jí)認(rèn)證乾巧，會(huì)返回 false
StpUtil.isSafe("shop"); // 返回 false
// 也不會(huì)通過(guò)校驗(yàn)句喜，會(huì)拋出異常
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 二級(jí)認(rèn)證示例
*
* @author kong
* @since 2022-10-16
*/
@RestController
@RequestMapping("/safe/")
public class SafeAuthController {
// ------------------ 指定業(yè)務(wù)類(lèi)型進(jìn)行二級(jí)認(rèn)證
// 獲取應(yīng)用秘鑰 ---- http://localhost:8081/safe/getClientSecret
@RequestMapping("getClientSecret")
public SaResult getClientSecret() {
// 第1步，先檢查當(dāng)前會(huì)話(huà)是否已完成 client業(yè)務(wù) 的二級(jí)認(rèn)證
StpUtil.checkSafe("client");
// 第2步沟于，如果已完成二級(jí)認(rèn)證咳胃，則返回?cái)?shù)據(jù)
return SaResult.data("aaaa-bbbb-cccc-dddd-eeee");
}
// 提供手勢(shì)密碼進(jìn)行二級(jí)認(rèn)證 ---- http://localhost:8081/safe/openClientSafe?gesture=35789
@RequestMapping("openClientSafe")
public SaResult openClientSafe(String gesture) {
// 比對(duì)手勢(shì)密碼（此處只是舉例，真實(shí)項(xiàng)目時(shí)可拿其它參數(shù)進(jìn)行校驗(yàn)）
if("35789".equals(gesture)) {
// 比對(duì)成功旷太，為當(dāng)前會(huì)話(huà)打開(kāi)二級(jí)認(rèn)證：
// 業(yè)務(wù)類(lèi)型為：client
// 有效期為600秒==10分鐘展懈，意為在10分鐘內(nèi)，調(diào)用 getClientSecret 時(shí)都無(wú)需再提供手勢(shì)密碼
StpUtil.openSafe("client", 600);
return SaResult.ok("二級(jí)認(rèn)證成功");
}
// 如果密碼校驗(yàn)失敗供璧，則二級(jí)認(rèn)證也會(huì)失敗
return SaResult.error("二級(jí)認(rèn)證失敗");
}
// 查詢(xún)當(dāng)前會(huì)話(huà)是否已完成指定的二級(jí)認(rèn)證 ---- http://localhost:8081/safe/isClientSafe
@RequestMapping("isClientSafe")
public SaResult isClientSafe() {
return SaResult.ok("當(dāng)前是否已完成 client 二級(jí)認(rèn)證：" + StpUtil.isSafe("client"));
}
}
五存崖、使用注解進(jìn)行二級(jí)認(rèn)證
在一個(gè)方法上使用 @SaCheckSafe 注解，可以在代碼進(jìn)入此方法之前進(jìn)行一次二級(jí)認(rèn)證校驗(yàn)
// 二級(jí)認(rèn)證：必須二級(jí)認(rèn)證之后才能進(jìn)入該方法
@SaCheckSafe
@RequestMapping("add")
public String add() {
return "用戶(hù)增加";
}
// 指定業(yè)務(wù)類(lèi)型睡毒，進(jìn)行二級(jí)認(rèn)證校驗(yàn)
@SaCheckSafe("art")
@RequestMapping("add2")
public String add2() {
return "文章增加";
}
標(biāo)注 @SaCheckSafe 的方法必須在二級(jí)認(rèn)證后才能訪問(wèn)成功来惧，其效果與代碼 StpUtil.checkSafe() 等同。
參考資料
- Sa-Token 文檔：https://sa-token.cc
- Gitee 倉(cāng)庫(kù)地址：https://gitee.com/dromara/sa-token
- GitHub 倉(cāng)庫(kù)地址：https://github.com/dromara/sa-token
