對敏感操作的二次認證 —— 詳解 Sa-Token 二級認證詳情 - java,springboot,sa-token,權限控制,spring 小風箏博客

一、需求分析

在某些敏感操作下，我們需要對已登錄的會話進行二次驗證。

比如代碼託管平台的倉庫刪除操作，儘管我們已經登錄了賬號，當我們點擊 [刪除] 按鈕時，還是需要再次輸入一遍密碼，這麼做主要為了兩點：

保證操作者是當前賬號本人。
增加操作步驟，防止誤刪除重要數據。

這就是我們本篇要講的 —— 二級認證，即：在已登錄會話的基礎上，進行再次驗證，提高會話的安全性。

Sa-Token 是一個輕量級 java 權限認證框架，主要解決登錄認證、權限認證、單點登錄、OAuth2、微服務網關鑑權等一系列權限相關問題。
Gitee 開源地址：https://gitee.com/dromara/sa-token

本文將介紹在 SpringBoot 架構下，如何使用 Sa-Token 完成二級認證操作。

首先在項目中引入 Sa-Token 依賴：

<!-- Sa-Token 權限認證 -->
<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中進行二級認證非常簡單，只需要使用以下API：

// 在當前會話 開啓二級認證，時間為120秒
StpUtil.openSafe(120); 

// 獲取：當前會話是否處於二級認證時間內
StpUtil.isSafe(); 

// 檢查當前會話是否已通過二級認證，如未通過則拋出異常
StpUtil.checkSafe(); 

// 獲取當前會話的二級認證剩餘有效時間 (單位: 秒, 返回-2代表尚未通過二級認證)
StpUtil.getSafeTime(); 

// 在當前會話 結束二級認證
StpUtil.closeSafe();

三、一個小示例

一個完整的二級認證業務流程，應該大致如下：

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 二級認證示例 
 * 
 * @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步，先檢查當前會話是否已完成二級認證 
        //         這個地方既可以通過 StpUtil.isSafe() 手動判斷，
        //         也可以通過 StpUtil.checkSafe() 或者 @SaCheckSafe 來校驗（校驗不通過時將拋出 NotSafeException 異常）
        if(!StpUtil.isSafe()) {
            return SaResult.error("倉庫刪除失敗，請完成二級認證後再次訪問接口");
        }
    
        // 第2步，如果已完成二級認證，則開始執行業務邏輯
        // ... 
    
        // 第3步，返回結果 
        return SaResult.ok("倉庫刪除成功"); 
    }
    
    // 提供密碼進行二級認證    ---- http://localhost:8081/safe/openSafe?password=123456
    @RequestMapping("openSafe")
    public SaResult openSafe(String password) {
        // 比對密碼（此處只是舉例，真實項目時可拿其它參數進行校驗）
        if("123456".equals(password)) {
    
            // 比對成功，為當前會話打開二級認證，有效期為120秒，意為在120秒內再調用 deleteProject 接口都無需提供密碼 
            StpUtil.openSafe(120);
            return SaResult.ok("二級認證成功");
        }
    
        // 如果密碼校驗失敗，則二級認證也會失敗
        return SaResult.error("二級認證失敗"); 
    }

    // 手動關閉二級認證    ---- http://localhost:8081/safe/closeSafe
    @RequestMapping("closeSafe")
    public SaResult closeSafe() {
        StpUtil.closeSafe();
        return SaResult.ok();
    }

}

全局異常攔截器，統一返回給前端的格式，參考：

@RestControllerAdvice
public class GlobalExceptionHandler {
    // 全局異常攔截 
    @ExceptionHandler
    public SaResult handlerException(Exception e) {
        e.printStackTrace(); 
        return SaResult.error(e.getMessage());
    }
}

前提：二級認證時我們必須處於登錄狀態（可參考之前的登錄認證章節代碼），完成登錄後，調用接口進行二級認證校驗：

前端調用 deleteProject 接口，嘗試刪除倉庫。 ---- http://localhost:8081/safe/deleteProject
後端校驗會話尚未完成二級認證，返回：倉庫刪除失敗，請完成二級認證後再次訪問接口。
前端將信息提示給用户，用户輸入密碼，調用 openSafe 接口。 ---- http://localhost:8081/safe/openSafe?password=123456
後端比對用户輸入的密碼，完成二級認證，有效期為：120秒。
前端在 120 秒內再次調用 deleteProject 接口，嘗試刪除倉庫。 ---- http://localhost:8081/safe/deleteProject
後端校驗會話已完成二級認證，返回：倉庫刪除成功。

四、指定業務標識進行二級認證

如果項目有多條業務線都需要敏感操作驗證，則 StpUtil.openSafe() 無法提供細粒度的認證操作，
此時我們可以指定一個業務標識來分辨不同的業務線：

// 在當前會話 開啓二級認證，業務標識為client，時間為600秒
StpUtil.openSafe("client", 600); 

// 獲取：當前會話是否已完成指定業務的二級認證 
StpUtil.isSafe("client"); 

// 校驗：當前會話是否已完成指定業務的二級認證 ，如未認證則拋出異常
StpUtil.checkSafe("client"); 

// 獲取當前會話指定業務二級認證剩餘有效時間 (單位: 秒, 返回-2代表尚未通過二級認證)
StpUtil.getSafeTime("client"); 

// 在當前會話 結束指定業務標識的二級認證
StpUtil.closeSafe("client");

業務標識可以填寫任意字符串，不同業務標識之間的認證互不影響，比如：

// 打開了業務標識為 client 的二級認證 
StpUtil.openSafe("client"); 

// 判斷是否處於 shop 的二級認證，會返回 false 
StpUtil.isSafe("shop");  // 返回 false 

// 也不會通過校驗，會拋出異常 
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 二級認證示例 
 * 
 * @author kong
 * @since 2022-10-16 
 */
@RestController
@RequestMapping("/safe/")
public class SafeAuthController {

    // ------------------ 指定業務類型進行二級認證 

    // 獲取應用秘鑰    ---- http://localhost:8081/safe/getClientSecret
    @RequestMapping("getClientSecret")
    public SaResult getClientSecret() {
        // 第1步，先檢查當前會話是否已完成 client業務 的二級認證 
        StpUtil.checkSafe("client");
    
        // 第2步，如果已完成二級認證，則返回數據 
        return SaResult.data("aaaa-bbbb-cccc-dddd-eeee");
    }
    
    // 提供手勢密碼進行二級認證    ---- http://localhost:8081/safe/openClientSafe?gesture=35789
    @RequestMapping("openClientSafe")
    public SaResult openClientSafe(String gesture) {
        // 比對手勢密碼（此處只是舉例，真實項目時可拿其它參數進行校驗）
        if("35789".equals(gesture)) {
    
            // 比對成功，為當前會話打開二級認證：
            // 業務類型為：client 
            // 有效期為600秒==10分鐘，意為在10分鐘內，調用 getClientSecret 時都無需再提供手勢密碼 
            StpUtil.openSafe("client", 600);
            return SaResult.ok("二級認證成功");
        }
    
        // 如果密碼校驗失敗，則二級認證也會失敗
        return SaResult.error("二級認證失敗"); 
    }

    // 查詢當前會話是否已完成指定的二級認證    ---- http://localhost:8081/safe/isClientSafe
    @RequestMapping("isClientSafe")
    public SaResult isClientSafe() {
        return SaResult.ok("當前是否已完成 client 二級認證：" + StpUtil.isSafe("client")); 
    }

}

五、使用註解進行二級認證

在一個方法上使用 @SaCheckSafe 註解，可以在代碼進入此方法之前進行一次二級認證校驗

// 二級認證：必須二級認證之後才能進入該方法 
@SaCheckSafe      
@RequestMapping("add")
public String add() {
    return "用户增加";
}

// 指定業務類型，進行二級認證校驗
@SaCheckSafe("art")
@RequestMapping("add2")
public String add2() {
    return "文章增加";
}

標註 @SaCheckSafe 的方法必須在二級認證後才能訪問成功，其效果與代碼 StpUtil.checkSafe() 等同。