【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 为何不够

Coarse scope	Agent 实际行为	gap
`read:mail`	读 inbox + sent + drafts	用户只想 summary inbox
`read:files`	遍历整个 Drive	用户指定单个项目目录
`read:orders`	`SELECT * FROM orders`	应限 customer_id = 当前用户

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}

优点	缺点
token 自包含	scope 字符串过长；folder 动态变化需 re-consent
RS 验证简单	IdP consent UI 难展示

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 之上增加 资源所有者 对 任意资源 的授权——三角色：

角色	缩写	职责
Resource Owner	RO	用户，拥有资源
Resource Server	RS	托管资源
Authorization Server	AS	发 ticket、token

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 的契合点

UMA 概念	Agent 映射
Requesting Party	Agent（或 Agent Gateway）
Permission Ticket	「Agent 想读 file-123 但无权」时 RS 返回
RO 授权	用户 popup / 异步批准
RPT	短期、资源绑定 token

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

3.3 UMA 与 Agent 的不契合点

问题	说明
延迟	每次新资源可能打断用户——需 batch consent
实现复杂度	完整 UMA RS + AS 改造大
生态	主流 IdP 非原生 UMA 2.0——多自研 ticket 层

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

四、Google Incremental Authorization（B 级对照）

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

机制	Agent 启示
分阶段 scope	Agent 启动只要 `profile`；读 Drive 前再 consent `drive.readonly`
`include_granted_scopes`	新 token 包含旧 scope + 新 scope
用户可见性	每次扩大权限必须 UI 确认

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

字段	用途
`user_sub`	资源所有者
`agent_id`	被委托 Agent
`scopes`	OAuth scope 集合
`resource_constraints`	JSON：allowed folders, max rows 等
`granted_at` / `expires_at`	时间边界
`revoked`	用户撤销

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

七、与 RBAC/ABAC 的关系

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

八、反模式

一次 consent 无限资源——read:files 无 folder 限制。
scope 字符串伪造资源——read:mail:../../admin 若 RS 解析不严。
ticket 无 TTL——RPT 长期有效 = 新泄露面。
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。