跳转到主要内容

​
安全与认证

​
6.1 认证机制总览

UCP支持四种认证机制，适用于不同的安全需求层级：
认证方式标准适用场景安全级别
API Keys自定义公开目录浏览、低敏感度操作基础
OAuth 2.0RFC 6749/6750用户身份关联、代表用户操作标准
mTLSRFC 8705服务端到服务端高安全通信高
HTTP Message SignaturesRFC 9421Webhook签名验证、请求完整性高

​
API Keys

适用于无需用户身份的场景（如浏览公开商品目录）： 
GET /ucp/catalog/products?query=鞋
Authorization: Bearer ucp_pk_live_xxxxxxxxxxxx
API Key通常区分测试环境（ucp_pk_test_）和生产环境（ucp_pk_live_）。

​
OAuth 2.0

详见第3章。用于需要代表消费者操作的场景（结账、订单查询等）。UCP强制使用Authorization Code + PKCE流程。

​
mTLS (Mutual TLS)

双向TLS认证，客户端和服务器都需要提供证书。适用于平台与平台之间的高安全通信： 
AI代理 ←──mTLS──→ 商家API
  │                   │
  └─ 客户端证书        └─ 服务器证书
     (证明代理身份)       (证明商家身份)
mTLS遵循 RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication，可以与OAuth 2.0结合使用。

​
HTTP Message Signatures (RFC 9421)

UCP的Webhook通知和关键API调用使用HTTP消息签名确保完整性和真实性。这是UCP安全模型中最重要的机制之一。

​
6.2 JWK签名密钥

商家在 /.well-known/ucp Profile中发布签名公钥，使用JSON Web Key (JWK)格式： 
{
  "signing_keys": [
    {
      "kid": "key-2026-04",
      "kty": "EC",
      "crv": "P-256",
      "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
      "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
      "use": "sig",
      "alg": "ES256"
    }
  ]
}
JWK字段说明:
字段值说明
kid字符串密钥标识符，用于在多个密钥中定位
ktyEC密钥类型：椭圆曲线
crvP-256曲线：NIST P-256
xBase64URL椭圆曲线公钥X坐标
yBase64URL椭圆曲线公钥Y坐标
usesig用途：签名
algES256算法：ECDSA with SHA-256
密钥轮换: 商家可以在 signing_keys 数组中同时发布多个密钥（通过不同的 kid 区分），支持平滑的密钥轮换。旧密钥在过渡期内保留，新签名使用新密钥。

​
6.3 HTTP消息签名 (RFC 9421)

​
签名创建（商家侧）

商家发送Webhook时，按RFC 9421标准创建签名： 步骤1: 计算请求体的Content-Digest（RFC 9530） 
Content-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
步骤2: 定义签名输入（Signature-Input） 
Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-type");created=1712836800;keyid="key-2026-04";alg="ecdsa-p256-sha256"
签名组件说明：
  • @method: HTTP方法（如POST）
  • @target-uri: 完整请求URI
  • content-digest: 请求体摘要
  • content-type: 内容类型
  • created: 签名创建时间戳（Unix时间）
  • keyid: 对应Profile中的JWK kid
  • alg: 签名算法
步骤3: 构造签名基础字符串 
"@method": POST
"@target-uri": https://agent.example.com/webhooks/ucp
"content-digest": sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
"content-type": application/json
"@signature-params": ("@method" "@target-uri" "content-digest" "content-type");created=1712836800;keyid="key-2026-04";alg="ecdsa-p256-sha256"
步骤4: 使用私钥（ES256）对基础字符串签名 
Signature: sig1=:MEUCIQDXsM...base64签名值...=:

​
签名验证（AI代理侧）

验证清单:

1. 解析 Signature-Input 获取 keyid 和签名组件列表
2. 从商家 /.well-known/ucp 获取对应 kid 的 JWK 公钥
3. 验证 Content-Digest:
   - 计算请求体的 SHA-256 哈希
   - 与 Content-Digest 头中的值比较
4. 按 Signature-Input 中的组件顺序重建签名基础字符串
5. 使用 JWK 公钥验证 ES256 签名
6. 检查 created 时间戳（拒绝超过5分钟的签名）
7. 验证通过 → 处理Webhook
   验证失败 → 返回 401，记录安全日志

​
6.4 Content-Digest (RFC 9530)

Content-Digest头提供请求体的完整性校验，防止传输过程中的篡改： 
Content-Digest: sha-256=:base64编码的SHA-256哈希:
计算方式： 
1. 取完整的HTTP请求体（raw bytes）
2. 计算 SHA-256 哈希
3. Base64编码
4. 格式: sha-256=:base64值:
Content-Digest与HTTP消息签名配合使用——签名覆盖Content-Digest头，Content-Digest覆盖请求体，形成完整的安全链条。

​
6.5 传输安全

要求说明
HTTPS必须所有UCP通信必须使用HTTPS，Profile端点不允许重定向
TLS 1.2+最低TLS 1.2，推荐TLS 1.3
证书验证AI代理必须严格验证商家的TLS证书
HSTS建议启用HTTP Strict Transport Security
Certificate Transparency建议使用CT日志中的证书

​
6.6 数据安全与隐私

UCP对数据处理有明确的安全边界：
数据类型AI代理的权限禁止行为
商品目录缓存、展示给用户用于模型训练
买家个人信息传递给商家完成交易存储或共享给第三方
支付凭证通过Payment Handler传递存储、记录或转发
订单数据展示给对应消费者聚合分析或数据挖掘
签名密钥（私钥）不应接触私钥任何形式的获取

​
6.7 安全最佳实践

  1. 密钥轮换: 定期轮换JWK签名密钥，在Profile中同时发布新旧密钥确保平滑过渡
  2. 速率限制: 对所有UCP端点实施合理的速率限制
  3. 审计日志: 记录所有结账和订单操作的完整审计日志
  4. 签名时间窗口: Webhook签名的 created 时间戳应在5分钟以内
  5. 令牌安全: access_token不应出现在URL参数或日志中
  6. CORS: UCP API端点应配置严格的CORS策略
  7. 输入验证: 所有输入参数必须严格验证类型和范围
下一章: 商家集成指南 — /.well-known/ucp Profile部署和能力声明