跳转到主要内容

​
身份关联

​
3.1 能力标识

身份关联的命名空间为 dev.ucp.common.identity_linking。它是UCP中跨领域的通用能力（common 而非 shopping），因为身份关联不仅限于购物场景。

​
3.2 为什么需要身份关联

消费者在商家处可能已有账户（会员等级、积分、收货地址、历史订单、支付方式）。身份关联让AI代理可以安全地代表消费者使用这些已有信息，实现个性化购物体验——而不需要消费者重新输入任何信息或共享密码。 无身份关联的结账: AI代理只能创建访客结账（Guest Checkout），消费者需要手动填写所有信息。 有身份关联的结账: AI代理可以直接获取消费者保存的地址、支付方式和会员优惠，一步完成结账。

​
3.3 授权服务器发现

UCP要求商家通过标准的 /.well-known/oauth-authorization-server 端点发布授权服务器元数据（符合RFC 8414）： 
{
  "issuer": "https://store.example.com",
  "authorization_endpoint": "https://store.example.com/oauth/authorize",
  "token_endpoint": "https://store.example.com/oauth/token",
  "revocation_endpoint": "https://store.example.com/oauth/revoke",
  "scopes_supported": [
    "ucp:scopes:checkout_session",
    "openid",
    "profile"
  ],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"]
}
AI代理通过GET请求此端点，即可自动发现商家的OAuth配置，无需硬编码任何授权URL。

​
3.4 OAuth 2.0 Authorization Code流程

UCP使用标准的 OAuth 2.0 Authorization Code 流程，并强制使用PKCE（Proof Key for Code Exchange）增强安全性：

​
步骤1：生成PKCE参数

code_verifier = 随机生成的43-128字符字符串
code_challenge = BASE64URL(SHA256(code_verifier))

​
步骤2：发起授权请求

GET https://store.example.com/oauth/authorize?
  response_type=code&
  client_id=agent_shopping_001&
  redirect_uri=https://agent.example.com/callback&
  scope=ucp:scopes:checkout_session&
  state=random_csrf_token_xyz&
  code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
  code_challenge_method=S256
关键参数说明:
参数说明
scopeUCP标准scope为 ucp:scopes:checkout_session，授权AI代理管理结账会话
stateCSRF防护令牌，必须是不可预测的随机值
code_challengePKCE挑战值，防止授权码拦截攻击
code_challenge_method固定为 S256（SHA-256哈希）

​
步骤3：用户授权

商家展示授权页面，明确告知用户：
  • 哪个AI代理在请求授权
  • 请求了哪些权限
  • 用户可以随时撤销
用户确认后，商家将浏览器重定向到 redirect_uri，附带授权码： 
https://agent.example.com/callback?code=auth_code_abc123&state=random_csrf_token_xyz

​
步骤4：令牌交换

POST https://store.example.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=auth_code_abc123&
redirect_uri=https://agent.example.com/callback&
client_id=agent_shopping_001&
client_secret=secret_xxx&
code_verifier=原始的code_verifier值

​
步骤5：获取令牌

{
  "access_token": "at_ucp_xxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_ucp_xxxxxxxxxxxxx",
  "scope": "ucp:scopes:checkout_session"
}

​
3.5 UCP Scope规范

UCP定义了标准化的scope命名，使用 ucp:scopes: 前缀：
Scope允许的操作
ucp:scopes:checkout_session创建和管理结账会话（核心scope）
商家可以在UCP标准scope基础上扩展自定义scope。但AI代理应始终遵循最小权限原则——只请求实际需要的scope。

​
3.6 令牌撤销 (RFC 7009)

UCP要求商家实现令牌撤销端点，遵循 RFC 7009 OAuth 2.0 Token Revocation 标准： 
POST https://store.example.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=at_ucp_xxxxxxxxxxxxx&
token_type_hint=access_token&
client_id=agent_shopping_001&
client_secret=secret_xxx
撤销场景包括：
  • 用户主动撤销: 用户在商家网站的账户设置中取消AI代理授权
  • AI代理主动撤销: AI代理不再需要访问权限时主动撤销令牌
  • 安全事件: 检测到异常活动时紧急撤销所有令牌
撤销access_token时，关联的refresh_token也应同时失效。

​
3.7 令牌刷新

access_token过期后，使用refresh_token获取新的access_token： 
POST https://store.example.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=rt_ucp_xxxxxxxxxxxxx&
client_id=agent_shopping_001&
client_secret=secret_xxx
响应包含新的access_token和可能的新refresh_token（令牌轮转）。

​
3.8 安全要点

要求说明
PKCE必须所有Authorization Code流程必须使用PKCE (S256)
HTTPS必须所有OAuth端点必须通过HTTPS提供
state参数必须使用不可预测的随机值防止CSRF
最小权限AI代理只请求实际需要的scope
令牌安全存储access_token和refresh_token必须安全存储，不能明文记录日志
重定向URI严格匹配redirect_uri必须与注册时完全一致
下一章: 订单管理 — 行项目状态、履约事件、调整操作和Webhook签名