一、需求分析

在某些敏感操作下，我們需要對(duì)已登錄的會(huì)話進(jìn)行二次驗(yàn)證。

(相關(guān)資料圖)

比如代碼托管平臺(tái)的倉庫刪除操作，盡管我們已經(jīng)登錄了賬號(hào)，當(dāng)我們點(diǎn)擊 [刪除]按鈕時(shí)，還是需要再次輸入一遍密碼，這么做主要為了兩點(diǎn)：

保證操作者是當(dāng)前賬號(hào)本人。增加操作步驟，防止誤刪除重要數(shù)據(jù)。

這就是我們本篇要講的 —— 二級(jí)認(rèn)證，即：在已登錄會(huì)話的基礎(chǔ)上，進(jìn)行再次驗(yàn)證，提高會(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)問題。Gitee 開源地址：https://gitee.com/dromara/sa-token

本文將介紹在 SpringBoot 架構(gòu)下，如何使用 Sa-Token 完成二級(jí)認(rèn)證操作。

首先在項(xiàng)目中引入 Sa-Token 依賴：

    cn.dev33    sa-token-spring-boot-starter    1.34.0

注：如果你使用的是 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ì)話 開啟二級(jí)認(rèn)證，時(shí)間為120秒StpUtil.openSafe(120); // 獲取：當(dāng)前會(huì)話是否處于二級(jí)認(rèn)證時(shí)間內(nèi)StpUtil.isSafe(); // 檢查當(dāng)前會(huì)話是否已通過二級(jí)認(rèn)證，如未通過則拋出異常StpUtil.checkSafe(); // 獲取當(dāng)前會(huì)話的二級(jí)認(rèn)證剩余有效時(shí)間 (單位: 秒, 返回-2代表尚未通過二級(jí)認(rèn)證)StpUtil.getSafeTime(); // 在當(dāng)前會(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 {// 刪除倉庫    ---- http://localhost:8081/safe/deleteProject@RequestMapping("deleteProject")public SaResult deleteProject(String projectId) {    // 第1步，先檢查當(dāng)前會(huì)話是否已完成二級(jí)認(rèn)證 // 這個(gè)地方既可以通過 StpUtil.isSafe() 手動(dòng)判斷，// 也可以通過 StpUtil.checkSafe() 或者 @SaCheckSafe 來校驗(yàn)（校驗(yàn)不通過時(shí)將拋出 NotSafeException 異常）    if(!StpUtil.isSafe()) {        return SaResult.error("倉庫刪除失敗，請(qǐng)完成二級(jí)認(rèn)證后再次訪問接口");    }    // 第2步，如果已完成二級(jí)認(rèn)證，則開始執(zhí)行業(yè)務(wù)邏輯    // ...     // 第3步，返回結(jié)果     return SaResult.ok("倉庫刪除成功"); }// 提供密碼進(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ì)話打開二級(jí)認(rèn)證，有效期為120秒，意為在120秒內(nèi)再調(diào)用 deleteProject 接口都無需提供密碼         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)一返回給前端的格式，參考：

@RestControllerAdvicepublic 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 接口，嘗試刪除倉庫。 ---- http://localhost:8081/safe/deleteProject后端校驗(yàn)會(huì)話尚未完成二級(jí)認(rèn)證，返回： 倉庫刪除失敗，請(qǐng)完成二級(jí)認(rèn)證后再次訪問接口。前端將信息提示給用戶，用戶輸入密碼，調(diào)用 openSafe 接口。 ---- http://localhost:8081/safe/openSafe?password=123456后端比對(duì)用戶輸入的密碼，完成二級(jí)認(rèn)證，有效期為：120秒。前端在 120 秒內(nèi)再次調(diào)用 deleteProject 接口，嘗試刪除倉庫。 ---- http://localhost:8081/safe/deleteProject后端校驗(yàn)會(huì)話已完成二級(jí)認(rèn)證，返回：倉庫刪除成功。四、指定業(yè)務(wù)標(biāo)識(shí)進(jìn)行二級(jí)認(rèn)證

如果項(xiàng)目有多條業(yè)務(wù)線都需要敏感操作驗(yàn)證，則 StpUtil.openSafe()無法提供細(xì)粒度的認(rèn)證操作，此時(shí)我們可以指定一個(gè)業(yè)務(wù)標(biāo)識(shí)來分辨不同的業(yè)務(wù)線：

// 在當(dāng)前會(huì)話 開啟二級(jí)認(rèn)證，業(yè)務(wù)標(biāo)識(shí)為client，時(shí)間為600秒StpUtil.openSafe("client", 600); // 獲取：當(dāng)前會(huì)話是否已完成指定業(yè)務(wù)的二級(jí)認(rèn)證 StpUtil.isSafe("client"); // 校驗(yàn)：當(dāng)前會(huì)話是否已完成指定業(yè)務(wù)的二級(jí)認(rèn)證 ，如未認(rèn)證則拋出異常StpUtil.checkSafe("client"); // 獲取當(dāng)前會(huì)話指定業(yè)務(wù)二級(jí)認(rèn)證剩余有效時(shí)間 (單位: 秒, 返回-2代表尚未通過二級(jí)認(rèn)證)StpUtil.getSafeTime("client"); // 在當(dāng)前會(huì)話 結(jié)束指定業(yè)務(wù)標(biāo)識(shí)的二級(jí)認(rèn)證StpUtil.closeSafe("client"); 

業(yè)務(wù)標(biāo)識(shí)可以填寫任意字符串，不同業(yè)務(wù)標(biāo)識(shí)之間的認(rèn)證互不影響，比如：

// 打開了業(yè)務(wù)標(biāo)識(shí)為 client 的二級(jí)認(rèn)證 StpUtil.openSafe("client"); // 判斷是否處于 shop 的二級(jí)認(rèn)證，會(huì)返回 false StpUtil.isSafe("shop");  // 返回 false // 也不會(huì)通過校驗(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ù)類型進(jìn)行二級(jí)認(rèn)證 // 獲取應(yīng)用秘鑰    ---- http://localhost:8081/safe/getClientSecret@RequestMapping("getClientSecret")public SaResult getClientSecret() {    // 第1步，先檢查當(dāng)前會(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ì)話打開二級(jí)認(rèn)證：    // 業(yè)務(wù)類型為：client     // 有效期為600秒==10分鐘，意為在10分鐘內(nèi)，調(diào)用 getClientSecret 時(shí)都無需再提供手勢(shì)密碼         StpUtil.openSafe("client", 600);        return SaResult.ok("二級(jí)認(rèn)證成功");    }    // 如果密碼校驗(yàn)失敗，則二級(jí)認(rèn)證也會(huì)失敗    return SaResult.error("二級(jí)認(rèn)證失敗"); }// 查詢當(dāng)前會(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 "用戶增加";}// 指定業(yè)務(wù)類型，進(jìn)行二級(jí)認(rèn)證校驗(yàn)@SaCheckSafe("art")@RequestMapping("add2")public String add2() {    return "文章增加";}

標(biāo)注 @SaCheckSafe的方法必須在二級(jí)認(rèn)證后才能訪問成功，其效果與代碼 StpUtil.checkSafe()等同。

參考資料Sa-Token 文檔：https://sa-token.ccGitee 倉庫地址：https://gitee.com/dromara/sa-tokenGitHub 倉庫地址：https://github.com/dromara/sa-token

關(guān)鍵詞：