一次任务里的 scope:从查询到修改
任务是最好的 scope 教材:用户对个人 Agent 说"看看我上周的订单,把周三的配送预约改到周五"。这一句话需要 orders:read 和 orders:write 两个 scope,而它们在任务的两个阶段分别登场。本页沿官方 1.0(固定 6561853)逐步走完,每步标注条款号;所有代码为说明性示例,非本站运行过的测试。
第 0 步:发现——scope 从哪里来
企业把支持的 scope 列在 OAuth 服务器元数据、受保护资源元数据或两者的 scopes_supported,并为面向个人 Agent 的每个 scope 给出描述:说清它解锁什么、哪些任务需要它、没有它任务能否完成(§4.7;描述放在 OpenAPI 安全方案的 scope 里或 auth.scopes,两处都有时以 auth.scopes 为准)。
"scopes_supported": ["orders:read", "orders:write", "poppy:browser-sign-in"],
"auth": { "scopes": {
"orders:read": { "description": "查看订单与配送预约" },
"orders:write": { "description": "修改配送预约;没有它只能查询" }
} }企业还可以给 scope_hints(§4.7):orders:write 标 changes: "irreversible"、personal_data: true,个人 Agent 在申请前就能告知用户"这一步会做不可逆的修改、涉及个人数据"。提示是对 scope 的后果标注(对应 MCP 工具注解的 scope 版),不替代描述,也不是用户批准。
第 1 步:只申请任务当前需要的
查询阶段,个人 Agent 申请 orders:read(§4.7:SHOULD 只申请用户任务所需,RFC 9700 §2.3)。用户在 consent 页批准后,token 响应回显实际授予的 scope——必须核对回显:用户可能只批了一部分;一个都没批则整个登录按拒绝结束(§4.7)。
{ "access_token": "…", "refresh_token": "…", "scope": "orders:read" }用这个 token 调订单 API(§7:企业按自己的 scope 定义在 API 上强制执行),查到周三的预约记录。
第 2 步:任务升级——重新登录,申请全部所需
“改到周五"需要 orders:write。关键规则(§4.7):再次登录时申请仍然需要的全部 scope——orders:read orders:write 一起,不是只补缺的 orders:write。原因:新 refresh token 会替换旧的(用户只批准了这次请求里列出的 scope)。替换后,个人 Agent SHOULD 撤销被替换的旧 refresh token(§4.6/§4.7);注意这只是凭据替换,不是登出——登出、会话停用、凭据撤销是三件不同的事(§5.5,详见凭据与撤销)。
consent 页会展示本次申请的全部 scope(包括之前已批过的),用户对"这次到底授权了什么"始终看得见、批得准。
第 3 步:三个入口,同一份 scope
拿到含 orders:write 的 token 后,修改动作可以从三个入口发生,scope 的执行方式各不相同(§4.7):
| 入口 | scope 如何执行 | 条款 |
|---|---|---|
| 业务 API | 企业定义每个动作需要哪个 scope 并在 API 上强制执行;orders:write 缺失时调用被拒(insufficient_scope,RFC 6750 语义) | §4.7、§7 |
| 企业 Agent(对话) | 企业 Agent 执行的动作同样按 scope 强制——不是"Agent 帮忙就能绕过授权” | §4.7 |
| 网页(浏览器登录) | 网站可能无法按 scope 收窄权限:经 poppy:browser-sign-in 登录的浏览器获得该账号的完整访问,由企业与用户通过该 scope 明确接受 | §4.7、§6 |
第三行是最容易被误解的:网页入口不是"第四种 scope 语义",而是网站技术栈限制下的显式豁免——所以 poppy:browser-sign-in 本身是一个需要用户批准的独立 scope,把"网页=完整访问"这件事摆在 consent 页上,而不是藏在实现细节里。
第 4 步:用户只批了 read 怎么办
token 回显 orders:read,orders:write 调用被 API 拒绝。个人 Agent 的两条正路:回到第 2 步重新登录(申请全部所需);或如实告知用户"没有修改权限,任务只能完成查询"。没有第三条路:规范禁止企业授予请求之外的 scope(§4.7:MUST NOT,比 RFC 6749 更严——用户只批准了请求里列出的),Agent 也不应绕到网页入口去规避 API 的 scope 拒绝。
与本站其他页的衔接
发现与元数据细节见发现文档;登录流(PAR、client assertion、DPoP)见OAuth 排障;企业侧全流程向导见企业接入向导。本页只回答一个问题:同一个任务里,scope 如何随着任务升级而变化,并在三个入口一致执行。来源:1.0 规范源文件(§3.2、§4.6、§4.7、§5.5、§6、§7),核对日 2026-11-17。