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

一、需求分析

在某些敏感操作下,我们需要对已登录的会话进行二次验证。

比如代码托管平台的仓库删除操作,尽管我们已经登录了账号,当我们点击 [删除] 按钮时,还是需要再次输入一遍密码,这么做主要为了两点:

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

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

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());
    }
}

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

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

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

如果项目有多条业务线都需要敏感操作验证,则 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() 等同。


参考资料

热门相关:洪荒二郎传   民国之文豪崛起   重生野性时代   半仙   道君