二次验证拦截器 🔐

功能介绍 💡

WARNING

二次验证拦截器就像一道额外的安全门，在访问重要接口之前，需要通过额外的验证（如动态口令、权限校验等）才能继续操作。这样的设计可以有效防止未经授权的访问和误操作。

应用场景 🎯

1. 操作二次验证

   • 修改重要配置时需要动态口令验证
   • 大额交易时需要短信验证码确认
   • 敏感操作需要生物识别认证

2. 数据权限验证

   • 验证用户是否有权限访问特定数据
   • 检查用户是否具备操作权限
   • 控制数据访问范围

详细配置说明 ⚙️

核心参数说明

参数名	类型	必填	默认值	说明
enabled	boolean	否	false	是否启用拦截器
items	array	是	-	验证规则配置列表

验证规则配置详解 (items)

参数名	类型	必填	默认值	说明
urls	array	是	-	需要二次验证的接口地址
parameter-type	string	是	-	参数获取类型：header/query/body
verify-uri	string	是	-	验证接口地址
verify-timeout	string	否	PT1M	验证超时时间
verify-params	object	否	-	验证参数映射配置
business-key	string	否	bearer	业务隔离标识（v1.5.0+）
lock-enabled	boolean	否	false	是否启用锁定机制（v1.5.0+）
lock-interval	string	否	PT30M	锁定计数时间窗口
lock-count	number	否	5	触发锁定的错误次数
lock-expire	string	否	PT30M	锁定持续时间

配置示例 📋

基础配置

wueasy:
  gateway:
    filter:
      secondary-verify:
        enabled: true  # 启用二次验证
        items:
        - urls: 
          - /demo/login #需要验证图片验证码接口地址
          parameter-type: body #验证码取值参数类型
          verify-uri: lb://web1/verifyCaptcha #负载均衡方式调用自定义接口
          #verify-uri: http://127.0.0.1:8081/verifyCaptcha #指定接口地址方式调用自定义接口
          verify-params: #需要验证传输的参数
            code : code
            captcha : captcha

高级配置（带锁定机制）

wueasy:
  gateway:
    filter:
      secondary-verify:
        enabled: true
        items:
        - urls: ["/api/finance/**"]
          parameter-type: body
          verify-uri: lb://auth-service/verify/sms
          business-key: finance  # 财务业务标识
          lock-enabled: true  # 启用锁定
          lock-interval: PT10M  # 10分钟内
          lock-count: 3  # 错误3次
          lock-expire: PT1H  # 锁定1小时
          verify-params:
            mobile: userMobile
            code: smsCode

验证接口开发指南 📝

接口要求

1. 必须使用 POST 方法
2. 必须接收 body 参数
3. 返回统一的结果格式

示例代码

• 登录接口/demo/login传入验证
• 自定义验证验证码接口，必须使用body接收参数，并且是post请求
• 验证验证码代码（自定义逻辑处理）

	@PostMapping(value= "/verifyCaptcha",produces = MediaType.APPLICATION_JSON_VALUE)
	public Mono<ResultVo<Void>> verifyCaptcha(@RequestBody @Valid DataMap map)
	{
    //TODO 自定义处理
		System.err.println("接收到参数："+JsonHelper.toJsonString(map));
		System.err.println("接收到用户信息："+JsonHelper.toJsonString(UserHelper.getSystemParameter()));
		return Mono.just(ResultVo.ok());
	}

• 登录接口http://127.0.0.1:8080/demo/login传入附加验证码参数
• 登录接口传入数据

{
    "accountNo":"admin",
    "password":"123456",
    "code":"88e8d3552ed0d2b8467bc5e497614e69", //验证码临时code
    "captcha":"4myn" //验证码值
}

最佳实践 💡

1. 安全建议

   • 设置合理的验证超时时间
   • 启用锁定机制防止暴力破解
   • 对不同业务使用不同的 business-key
   • 验证接口使用 HTTPS

2. 性能优化

   • 合理设置验证缓存
   • 避免过于频繁的验证
   • 优化验证接口响应时间

3. 用户体验

   • 清晰提示验证失败原因
   • 显示剩余验证次数
   • 提供验证码重发机制

常见问题 ❓

1. 验证失败

   • 检查验证码是否过期
   • 确认参数映射是否正确
   • 验证业务标识是否匹配

2. 账户被锁定

   • 查看错误次数是否达到上限
   • 确认锁定时间配置
   • 检查解锁机制是否正常

3. 验证超时

   • 检查 verify-timeout 配置
   • 确认网络连接状态
   • 优化验证接口性能

安全提示 ⚠️

CAUTION

1. 验证接口必须有访问控制
2. 验证信息应该加密传输
3. 避免在日志中打印验证码
4. 定期清理过期的验证信息
5. 监控异常的验证请求

相关文档 📚

• URL匹配规则说明
• 时间间隔配置说明