【Agent 身份与安全】细粒度 Scope 与 UMA 2.0 启示

第 02 篇 解决了「Agent 代表用户」的 token 形态——RFC 8693 的 act claim。但 scope=read:mail 对 Agent 仍太粗：用户可能只想让 Agent 读某个文件夹，而非整个邮箱。本文讨论 scope 粒度、UMA 2.0 的 Permission Ticket 模型是否适用于 Agent，以及 Google incremental auth 等工程对照——不展开完整 UMA 教程，只取 Agent 相关机制。

一、Coarse Scope 为何不够

OAuth 2.0 scope 是 字符串集合——无法表达「资源 ID = X」 unless scope 本身编码资源（read:mail:folder:inbox），导致 scope 爆炸。

flowchart TD
  COARSE["scope=read:mail"] --> PROB["无法表达 folder 级边界"]
  FINE["scope + resource_id 策略"] --> SOL["RS / Policy Engine 二次判定"]
  UMA["UMA Permission Ticket"] --> SOL

二、Scope 设计模式

2.1 编码资源的 Scope

read:mail:inbox
read:mail:folder:{folder_id}
read:file:{file_id}

2.2 Scope + 策略引擎（推荐组合）

Token 持 coarse scope（read:mail），OPA/Cedar 在 API 或 Agent Gateway 层检查 resource 属性：

package agent.mail

import rego.v1

default allow := false

allow if {
    input.scope[_] == "read:mail"
    input.resource.folder_id == input.delegation.allowed_folder
}

delegation.allowed_folder 来自用户 consent 记录——存 IdP 或 Gateway DB，不进 JWT（避免 token 过大）。

2.3 Token Exchange 时缩小 Scope

RFC 8693 Exchange 请求显式 scope=read:mail:inbox——AS 验证 ⊆ 用户原 scope。Agent 任务级 token 仅含任务所需 scope（见第 02 篇 §六）。

三、UMA 2.0 核心机制（A 级：Kantara UMA 2.0 Grant）

UMA 2.0 在 OAuth 2.0 之上增加 资源所有者 对 任意资源 的授权——三角色：

3.1 Permission Ticket 流（简化）

sequenceDiagram
  participant Client as Agent / Client
  participant RS as Resource Server
  participant AS as Authorization Server
  participant RO as Resource Owner

  Client->>RS: 请求资源（无 token 或 scope 不足）
  RS->>Client: 401 + permission ticket
  Client->>AS: 提交 ticket + 请求 scope
  AS->>RO: 请求授权（异步或同步）
  RO->>AS: 批准
  AS->>Client: RPT (Requesting Party Token)
  Client->>RS: 请求 + RPT
  RS->>RS: 验证 RPT

RPT（Requesting Party Token）：访问特定资源的 token——粒度细于 coarse scope。

3.2 UMA 与 Agent 的契合点

Agent 首次访问某资源触发 ticket → 用户确认 → RPT——适合 不可预知资源 ID 的探索型 Agent（如「帮我找上周 Paul 发的 PDF」）。

3.3 UMA 与 Agent 的不契合点

工程判断：全 UMA 部署少；取 ticket + 用户确认 思想，用 Gateway 自研轻量 Permission Ticket，不必严格 Kantara 互操作。

四、Google Incremental Authorization（B 级对照）

Google OAuth 文档描述 incremental authorization：应用先请求 minimal scope，后续按需追加 scope——弹出 incremental consent。

Agent Gateway 应镜像：任务类型 → 最小 scope 集——写邮件 Agent 不应预申请 drive.full。

五、动态 Scope 与 RFC 8693 组合

用户 consent: read:mail, read:calendar (stored at IdP)
任务1 (读 inbox):  Exchange scope=read:mail + policy folder=inbox
任务2 (读日历):    Exchange scope=read:calendar + policy date=today
任务3 (某封邮件附件): UMA-like ticket → 用户点批准 → RPT 或 one-time scope

Token Exchange 负责 OAuth scope 边界；Policy Engine 负责 resource 实例边界；UMA-like ticket 负责 首次触达未知资源。

六、Consent 记录模型

Gateway 持久化（示意字段，非特定产品 schema）：

Exchange 前 Gateway 查此表——请求的 scope + resource 约束必须 ⊆ 记录。

七、与 RBAC/ABAC 的关系

授权模型选型 中 ABAC 适合 Agent：subject=用户, actor=Agent, resource=邮件, action=read, env=time。Scope 是 RBAC 层；UMA/ticket 是资源层；ABAC 策略统一判定。

八、反模式

1. 一次 consent 无限资源——read:files 无 folder 限制。
2. scope 字符串伪造资源——read:mail:../../admin 若 RS 解析不严。
3. ticket 无 TTL——RPT 长期有效 = 新泄露面。
4. Agent 绕过 ticket——直接调 RS API 无 Gateway——须 mTLS + token 强制。

九、边界

• 不做法务「明示同意」认定
• UMA 2.0 完整部署指南见 Kantara 规范；本文只取 Agent 机制
• Function Calling 参数级授权 在 scope 之下

十、UMA RPT 与 Agent Gateway

UMA RPT 适合不可预知资源 ID——Gateway 作 Client 向 AS 换 RPT（Kantara UMA 2.0，A 级概念）。

十一、Scope 爆炸与 ABAC

500 文件夹不宜 500 scope——coarse scope + Delegation Store constraints。

十二、Rego delegation 校验

见正文 §十四；与 多租户授权 组合 tenant 前缀。

上一篇：Agent 身份谱系

下一篇：Function Calling 授权

参考资料

1. Kantara Initiative, UMA 2.0 Grant for OAuth 2.0 Authorization
2. IETF RFC 8693, OAuth 2.0 Token Exchange
3. Google Identity, OAuth 2.0 Incremental Authorization（B 级）
4. OPA 策略引擎