> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# UCP OAuth 2.0身份关联机制

> 全面讲解UCP身份关联机制的技术实现，包括OAuth 2.0 Authorization Code加PKCE完整授权流程、/.well-known授权服务器元数据自动发现、scope权限规范定义、令牌撤销RFC 7009与安全最佳实践，帮助AI代理安全地代表消费者访问商家已有账户信息实现个性化结账体验

# 身份关联

## 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）：

```json theme={null}
{
  "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参数

```text theme={null}
code_verifier = 随机生成的43-128字符字符串
code_challenge = BASE64URL(SHA256(code_verifier))
```

### 步骤2：发起授权请求

```http theme={null}
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
```

**关键参数说明**:

| 参数                      | 说明                                                     |
| ----------------------- | ------------------------------------------------------ |
| `scope`                 | UCP标准scope为 `ucp:scopes:checkout_session`，授权AI代理管理结账会话 |
| `state`                 | CSRF防护令牌，必须是不可预测的随机值                                   |
| `code_challenge`        | PKCE挑战值，防止授权码拦截攻击                                      |
| `code_challenge_method` | 固定为 `S256`（SHA-256哈希）                                  |

### 步骤3：用户授权

商家展示授权页面，明确告知用户：

* 哪个AI代理在请求授权
* 请求了哪些权限
* 用户可以随时撤销

用户确认后，商家将浏览器重定向到 `redirect_uri`，附带授权码：

```text theme={null}
https://agent.example.com/callback?code=auth_code_abc123&state=random_csrf_token_xyz
```

### 步骤4：令牌交换

```http theme={null}
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：获取令牌

```json theme={null}
{
  "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** 标准：

```http theme={null}
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：

```http theme={null}
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必须与注册时完全一致                     |

***

**下一章**: [订单管理](/zh/book-3/ch4-orders) — 行项目状态、履约事件、调整操作和Webhook签名