Bitzsoft.Integrations.Captcha.Tencent 1.0.4

Bitzsoft.Integrations.Captcha.Tencent

腾讯天御验证码实现包 -- 前端 TCaptcha 自渲染 + 服务端 DescribeCaptchaResult 二次校验。

功能特性

• 无感验证：前端 TCaptcha SDK 自渲染，验证通过后回传 ticket + Randstr
• 服务端二次校验：后端调腾讯 DescribeCaptchaResult 接口验证 ticket 真伪
• TC3-HMAC-SHA256 签名：内置腾讯云 API v3 签名（HMAC 密钥派生链），无需引入腾讯云 SDK
• 签名健壮：Content-Type 签名值从实际请求内容读取，保证签名值与发送值完全一致
• 零厂商 SDK 依赖：裸 HttpClient 直调 REST API
• 请求审计：内置 RequestLogging 管道

安装

dotnet add package Bitzsoft.Integrations.Captcha.Tencent

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

配置

appsettings.json

{
  "Captcha": {
    "Tencent": {
      "SecretId": "your-tencent-secret-id",
      "SecretKey": "your-tencent-secret-key",
      "CaptchaAppId": 1234567,
      "AppSecretKey": "your-captcha-app-secret-key",
      "Region": "ap-guangzhou",
      "Endpoint": "captcha.tencentcloudapi.com"
    }
  }
}

安全提示：腾讯 DescribeCaptchaResult 接口要求 AppSecretKey 作为业务参数明文随请求体传输（系腾讯既定设计，非连接器可改）。务必将该字段加入 RequestLogging 脱敏配置。

注册服务

从 IConfiguration 绑定（推荐）

using Microsoft.Extensions.DependencyInjection;

builder.Services.AddBitzsoftTencentCaptcha(
    builder.Configuration.GetSection("Captcha:Tencent"));

委托配置

builder.Services.AddBitzsoftTencentCaptcha(options =>
{
    options.SecretId = "your-tencent-secret-id";
    options.SecretKey = "your-tencent-secret-key";
    options.CaptchaAppId = 1234567;
    options.AppSecretKey = "your-captcha-app-secret-key";
});

使用示例

生成前端 SDK 凭证

var provider = factory.GetProvider(CaptchaProviderCode.Tencent);
var result = await provider.GenerateAsync(new CaptchaGenerateRequest { Type = CaptchaType.Intelligent });
// result.Data.AppId → CaptchaAppId，前端 TCaptcha 初始化用

前端加载 TCaptcha.js，用 CaptchaAppId 初始化，验证通过后拿到 ticket + Randstr。

服务端校验 ticket

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

    if (result.IsSuccess && result.Data!.Passed)
        return Ok();

    return BadRequest(result.ErrorMessage);
}

错误码

CaptchaCode：0 校验通过，非 0 失败。接口级错误（鉴权失败等）从 Error.Code 透传为 ErrorCode。

请求审计

services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.SensitiveFields.Add("AppSecretKey");   // 关键：腾讯 AppSecretKey 随请求体传输
    opts.SensitiveFields.Add("SecretKey");
});
services.AddBitzsoftTencentCaptcha(builder.Configuration.GetSection("Captcha:Tencent"));

安全说明

• SecretKey / AppSecretKey：通过环境变量注入，禁止硬编码；务必加入 RequestLogging 脱敏字段
• AppSecretKey 传输：随每个校验请求体明文传输，是腾讯接口的既定要求，务必脱敏
• ticket 一次性：校验后即失效

依赖

相关包

• Bitzsoft.Integrations.Captcha -- 抽象层
• Bitzsoft.Integrations.Captcha.Aliyun -- 阿里云验证码 2.0 实现
• Bitzsoft.Integrations.Captcha.Geetest -- 极验 GeeTest 实现
• Bitzsoft.Integrations.Captcha.All -- 聚合包