UCP Identity Linking

中文摘要：通过 UCP 公共能力 dev.ucp.common.identity_linking 确立买家身份——游客结算 vs OAuth 2.0 账号绑定,申请最小 scope,把 bearer token 带进 checkout session。需要账号信息或 商家 profile 声明该能力为必需时用。

When to use / 何时使用

• Checkout needs saved addresses / payment methods / loyalty / order history.
• The merchant profile lists dev.ucp.common.identity_linking (declared in ucp.capabilities).
• The user says "use my account".

Otherwise prefer guest checkout — supply buyer fields inline on the checkout session. 否则用游客结算,直接在 session 上填 buyer。

UCP mapping / UCP 映射

dev.ucp.common.identity_linking lets a platform "obtain authorization to perform actions on a user's behalf via OAuth 2.0" (per the UCP spec). The resulting bearer token is sent on checkout requests as Authorization: Bearer {token}, alongside the required UCP-Agent header.

Two paths:

• Guest — no token; populate buyer: { first_name, last_name, email, phone_number } on the session.
• OAuth 2.0 linking — run the flow, then carry the token into checkout.

Inputs & Outputs / 输入与输出

Inputs: merchant /.well-known/ucp profile (OAuth config), mode (guest|oauth), minimal scopes.

Outputs

{ "identity": {
    "mode": "oauth",
    "access_token": "***",            // sent as: Authorization: Bearer ***
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "profile addresses orders.read"
} }

Guest: { "identity": { "mode": "guest" } } → fill buyer on the session instead.

Workflow / 工作流

1. Decide mode. Default guest; escalate to OAuth only for a concrete need; tell the user why.
2. Read OAuth config from the merchant UCP profile.
3. Request minimal scopes (least privilege; don't ask write to read history).
4. Run OAuth 2.0 (authorization code + PKCE). The user consents in their browser; the

agent never touches raw credentials.

1. Carry the token into checkout as Authorization: Bearer {token} (plus UCP-Agent,

Idempotency-Key, Request-Id). Track expires_in; refresh as needed; never log tokens.

1. Step-up if checkout later needs a scope you didn't request.

Edge cases & failure modes / 边界与失败

• User declines linking → fall back to guest if allowed; else stop and explain.
• Token expiry mid-flow → refresh; if refresh fails, re-prompt consent.
• Scope creep → never silently broaden; request step-up with a reason.
• Per-merchant identity → tokens are merchant-scoped; don't reuse across merchants.
• PII → collect the minimum; never persist tokens/PII in plaintext or logs.

Worked example / 示例

User: "Use my Acme account so addresses autofill."

1. Need = saved addresses → oauth, scopes profile addresses.
2. Read Acme OAuth from profile → auth-code + PKCE; user consents in browser.
3. Token (expires_in:3600) → send Authorization: Bearer … on PUT /checkout-sessions/{id}.

No write scopes requested.

References / 参考

• UCP identity_linking capability: https://ucp.dev/specification/
• OAuth 2.0 / PKCE: RFC 6749, RFC 7636
• Next: ucp-checkout-session