Bitzsoft.Integrations.Captcha.Aliyun 1.0.4

Bitzsoft.Integrations.Captcha.Aliyun

阿里云验证码 2.0 实现包 -- 前端 Captcha.js 自渲染 + 服务端 VerifyIntelligentCaptcha 二次校验。

功能特性

• 无感验证：前端 SDK 自渲染，用户无感验证通过后回传 VerifyToken
• 服务端二次校验：后端调阿里云 VerifyIntelligentCaptcha 接口验证 token 真伪与风险等级
• POP RPC v1 签名：内置 HMAC-SHA1 签名（RFC 3986 URL 编码），无需引入阿里云 SDK
• 零厂商 SDK 依赖：裸 HttpClient 直调 REST API，包体积小
• 请求审计：内置 RequestLogging 管道，记录出站请求
• fail-closed：响应异常或缺字段时一律判失败，绝不静默放行

安装

dotnet add package Bitzsoft.Integrations.Captcha.Aliyun

<PackageReference Include="Bitzsoft.Integrations.Captcha.Aliyun" Version="1.0.0" />

配置

appsettings.json

{
  "Captcha": {
    "Aliyun": {
      "AccessKeyId": "your-access-key-id",
      "AccessKeySecret": "your-access-key-secret",
      "SceneId": "your-scene-id",
      "AppKey": "your-app-key",
      "Region": "cn-hangzhou",
      "Endpoint": "captcha.cn-hangzhou.aliyuncs.com"
    }
  }
}

注册服务

从 IConfiguration 绑定（推荐）

using Microsoft.Extensions.DependencyInjection;

builder.Services.AddBitzsoftAliyunCaptcha(
    builder.Configuration.GetSection("Captcha:Aliyun"));

委托配置

builder.Services.AddBitzsoftAliyunCaptcha(options =>
{
    options.AccessKeyId = "your-access-key-id";
    options.AccessKeySecret = "your-access-key-secret";
    options.SceneId = "your-scene-id";
    options.AppKey = "your-app-key";
});

注册后 ICaptchaProvider 与 ICaptchaProviderFactory 均可用（单厂商包也注册工厂）。

使用示例

生成前端 SDK 凭证

public class CaptchaController(ICaptchaProviderFactory factory) : ControllerBase
{
    [HttpGet("captcha/challenge")]
    public IActionResult Challenge()
    {
        var provider = factory.GetProvider(CaptchaProviderCode.Aliyun);
        var result = provider.GenerateAsync(new CaptchaGenerateRequest
        {
            Type = CaptchaType.Intelligent,
            Scene = "login"
        }).GetAwaiter().GetResult();

        // 将 AppKey / SceneId / ScriptUrl 返回给前端 SDK 初始化
        return Ok(result.Data);
    }
}

前端加载 AliyunCaptcha.js，用返回的 AppKey + SceneId 初始化，完成无感验证后拿到 VerifyToken。

服务端校验 token

[HttpPost("captcha/verify")]
public async Task<IActionResult> Verify([FromBody] VerifyDto dto)
{
    var provider = factory.GetProvider(CaptchaProviderCode.Aliyun);
    var result = await provider.VerifyAsync(new CaptchaVerifyRequest
    {
        Token = dto.VerifyToken,      // 前端回传
        RemoteIp = HttpContext.Connection.RemoteIpAddress?.ToString()
    });

    if (result.IsSuccess && result.Data!.Passed)
        return Ok();                  // 校验通过

    return BadRequest(result.ErrorMessage);  // 失败（含风险等级）
}

错误码

VerifyCode 反映风险等级：100 通过 / 100~900 风险递增 / 900 风险最高。校验失败时 ErrorCode 形如 VERIFY_900。

请求审计

内置 Bitzsoft.Integrations.RequestLogging 出站请求记录。持久化须宿主注册 IRequestLogStore：

services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.SensitiveFields.Add("AccessKeySecret");   // 确保密钥脱敏
});
services.AddBitzsoftAliyunCaptcha(builder.Configuration.GetSection("Captcha:Aliyun"));

安全说明

• AccessKeySecret：通过环境变量 / Secret Manager 注入，禁止硬编码；务必加入 RequestLogging 脱敏字段
• fail-closed：阿里云响应缺 VerifyResult 字段时一律判失败
• token 一次性：VerifyToken 校验后即失效

依赖

相关包

• Bitzsoft.Integrations.Captcha -- 抽象层
• Bitzsoft.Integrations.Captcha.Tencent -- 腾讯天御实现
• Bitzsoft.Integrations.Captcha.Geetest -- 极验 GeeTest 实现
• Bitzsoft.Integrations.Captcha.All -- 聚合包