Identity Linking 能力规范

基本信息

• Capability Name：dev.ucp.common.identity_linking
• Version：2026-01-11
• 官方规范：identity-linking.md

概述

Identity Linking 能力允许平台（如 Google、智能体服务）获得授权，代表用户在商家站点执行操作。

这是商业体验的基础，用于：

• 访问会员权益
• 使用个性化优惠
• 管理愿望清单
• 执行已认证的结账

技术基础

本规范基于 OAuth 2.0 实现安全的账户关联。

平台要求

认证要求

• MUST 使用 client_id 和 client_secret 通过 HTTP Basic Authentication (RFC 7617) 进行令牌交换认证
• MAY 支持 Client Metadata
• MAY 支持动态客户端注册机制

令牌使用

• MUST 在 HTTP Authorization header 中使用 Bearer schema：

  Authorization: Bearer <access_token>

OAuth 流程

• MUST 实现 OAuth 2.0 Authorization Code 流 (RFC 6749 4.1)
• SHOULD 在授权请求中包含唯一、不可猜测的 state 参数以防止 CSRF (RFC 6749 10.12)

撤销和安全事件

• SHOULD 当用户在平台侧发起取消关联时调用商家的撤销端点 (RFC 7009)
• SHOULD 支持 OpenID RISC Profile 1.0 处理异步账户更新、取消关联事件和跨账户保护

商家要求

OAuth 实现

• MUST 实现 OAuth 2.0 (RFC 6749)
• MUST 遵守 RFC 8414 声明 OAuth 2.0 端点位置（/.well-known/oauth-authorization-server）
  • SHOULD 实现 RFC 9728 (HTTP Resource Metadata)
  • SHOULD 填写 scopes_supported
• MUST 在 Token 端点强制客户端认证

账户创建

• MUST 如果用户尚未有账户，提供账户创建流程

Scope 支持

• MUST 支持标准 UCP scopes（见 Scopes 部分），授予令牌对给定资源所有关联操作的权限
• MAY 超出明确请求的范围授予额外权限，前提是至少包含请求的 scopes
• MAY 定义额外的自定义 scopes

撤销和安全事件

• MUST 按 RFC 7009 实现标准令牌撤销
• MUST 撤销指定令牌，SHOULD 递归撤销所有关联令牌（如撤销 refresh_token MUST 同时撤销所有从其颁发的 access_token）
• MUST 支持使用与 token 端点相同的客户端凭据认证的撤销请求
• SHOULD 支持 OpenID RISC Profile 1.0 启用跨账户保护

Scopes

结构设计

scope 复杂性应在向用户展示的同意屏幕中隐藏：用户不应看到每行一个操作，而是通用的描述，如"允许 [平台] 管理结账会话"。

资源-操作-Scope 映射

规则：覆盖一个能力的 scope 必须授予该能力所有关联操作的访问权限。例如，ucp:scopes:checkout_session 必须授予所有：Get、Create、Update、Delete、Cancel、Complete。

授权服务器元数据示例

根据 RFC 8414，元数据应托管在 /.well-known/oauth-authorization-server：

{
  "issuer": "https://merchant.example.com",
  "authorization_endpoint": "https://merchant.example.com/oauth2/authorize",
  "token_endpoint": "https://merchant.example.com/oauth2/token",
  "revocation_endpoint": "https://merchant.example.com/oauth2/revoke",
  "scopes_supported": [
    "ucp:scopes:checkout_session",
  ],
  "response_types_supported": [
    "code"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic"
  ],
  "service_documentation": "https://merchant.example.com/docs/oauth2"
}

实现检查清单

平台实施检查

• 使用 HTTP Basic Authentication 进行令牌交换
• 在 API 请求中使用 Bearer token
• 实现 Authorization Code 流
• 包含唯一 state 参数防 CSRF
• 支持令牌撤销
• 支持 RISC Profile（可选）

商家实施检查

• 实现 OAuth 2.0 服务器
• 提供 /.well-known/oauth-authorization-server 元数据
• 支持 ucp:scopes:checkout_session scope
• 提供账户创建流程
• 实现令牌撤销端点
• 支持递归令牌撤销
• 支持 RISC Profile（可选）

参考链接

• 官方 Identity Linking 规范
• OAuth 2.0 RFC 6749
• RFC 8414 - OAuth 2.0 Authorization Server Metadata
• RFC 7009 - OAuth 2.0 Token Revocation
• OpenID RISC Profile 1.0