方案转发

请求到达
       │
       ├── 有 X-Signature 头？→ HMAC 方案
       ├── 有 X-API-Key 头？  → API Key 方案
       └── 否则               → JWT Bearer 方案

JWT Bearer（用户调用方）

用于交互式用户认证：

参数	来源	验证
`Jwt:Secret`	配置	必填，≥ 32 字符
`Jwt:Issuer`	配置	必填，验证
`Jwt:Audience`	配置	必填，验证
`ClockSkew`	硬编码	`TimeSpan.Zero`（无容差）

{
  "Jwt": {
    "Secret": "your-secret-at-least-32-characters-long",
    "Issuer": "bitzorcas-api",
    "Audience": "bitzorcas-client"
  }
}

JWT Claims

Claim	描述
`sub` / `user_id`	用户标识符
`tenant_id`	租户标识符
`roles`	分配的角色
`exp`	过期时间（UTC）
`iat`	签发时间（UTC）

HMAC（应用调用方）

用于服务器到服务器认证：

组件	描述
头	`X-Signature`
算法	HMAC-SHA256
凭据	`Hmac:Clients` 配置
Nonce	通过 `INonceStore` 防重放
失败关闭	未注册客户端 → 401

{
  "Hmac": {
    "Clients": {
      "service-a": "shared-secret-here",
      "service-b": "another-secret"
    }
  }
}

HMAC 请求签名

客户端构造规范请求字符串
用共享密钥计算 HMAC-SHA256
发送 X-Signature: {timestamp}.{signature}
服务器验证签名和 nonce（防重放）

API Key（应用调用方）

用于服务集成的简单密钥认证：

组件	描述
头	`X-API-Key`
存储	仅 SHA-256 哈希（永不存储明文）
凭据格式	`prefix_description` → `prefix_identifier`

{
  "ApiKeys": {
    "boa_integration-key": {
      "KeyPrefix": "boa",
      "TenantId": "100",
      "Scopes": ["tickets.read", "tickets.write"]
    }
  }
}

开发测试夹具

仅在 Development 模式下，注入测试凭据：

HMAC：test-client 密钥 test-secret
API Key：boa_test_integration-key 沙箱范围

另见

认证流程图 — 可视化认证流程
Webhook 签名 — HMAC webhook 验证
授权 — 基于策略的访问控制