企业接入向导:从发现到撤销
本页把正式 1.0 的企业侧义务排成一条可核对的路径。每一步给出:要做什么、成功长什么样、失败时用户与个人 Agent 各自看到什么。示例域名均为占位,本文未连接任何真实企业或个人 Agent 实现。
第 1 步:发布 poppy.json
在 https://<company>/.well-known/poppy.json 发布实例元数据:agent.protocols(含能力描述,1.0 必填)、apis、web 与 OAuth 入口。个人 Agent 以固定 URL 抓取它,不猜测路径。
- 成功:Agent 能仅凭域名列出你的执行入口与能力。
- 失败:文件缺失或 JSON 非法时,Agent 视为该企业未参与,不会"降级猜测"。
第 2 步:issuer 互信双向校验
有账号体系的企业在受保护资源元数据(RFC 9728)中声明 issuer;issuer 元数据要反向引用同一 resource。两侧不一致即拒绝。
- 成功:两边声明的 resource/issuer 互相指向,audience 链闭合。
- 负例:只改一端的 issuer 或 resource,校验失败,登录不开始;没有 issuer 时按未登录模式服务,而不是放宽校验。
第 3 步:Direct Sign-In 端点
授权码 + PKCE;issuer 必须同时支持 ES256 与 PS384 签名、refresh_token 授权与撤销端点;PAR 可设为必须。令牌端点要求 DPoP 时,刷新必须沿用取得 refresh token 的同一 DPoP key。
- 成功:标准 OAuth 客户端参数即可完成登录,无私有字段。
- 负例(过期):过期 access token 调 API 返回
invalid_token,重新用 refresh token 换取,而不是重放旧值。
第 4 步:consent 页面列出全部 scope
consent 必须列出本次将授予的每一个 scope,包括用户先前已批准过的;企业自定义 scope 在 auth.scopes 或自身 OpenAPI 描述中定义,可用 scope_hints 标注不可逆性、可逆性与是否涉及个人数据。协议不再预定义 poppy:read / poppy:write。
- 成功:用户看到的清单与令牌实际 scope 一致。
- 负例:consent 漏列 scope 属于实现错误;正确行为是拒绝发放而非补授。
第 5 步:校验会话头
每个请求校验 Poppy-Session(poppy-session+jwt):delegation 链、方法与 URL 绑定(htm/htu)、必要时 access token 哈希(ath)。会话 JWT 由个人 Agent 用 delegated key 每请求自签;jwks_uri 公钥只签 delegation(≤24h)与 client assertion(≤5min)。
- 成功:合法请求通过;
sid稳定、jti唯一。 - 负例(重放):重复
jti应被拒绝为重放。 - 负例(错 aud / 错 htu):令牌发给 A 企业却被 B 使用,或请求 URL 与 htu 不符,返回
invalid_session,而不是静默放行。
第 6 步:执行入口
tasks.endpoint 按会话提供排除任务、技能索引与反馈入口;apis 下的写接口建议支持幂等键。会话状态机用四字段(working/handoff/closed/responder)表达,跨版本字段不混用。
第 7 步:浏览器加入(如启用)
浏览器会话用一次性 code 经 /authorize 加入:__Host- 前缀 Cookie、仅一次性使用。1.0 唯一协议级 scope 是 poppy:browser-sign-in。
- 负例:code 重放或跨会话使用必须失败。
第 8 步:撤销与退出
- 用户登出:个人 Agent 撤销自己为该账号持有的 refresh token;用过的会话进入 signed-out 模式(不带 access token),需要账号的请求收到 challenge。
- 企业侧断开连接:同样撤销该账号 refresh token;Agent 以
invalid_token/ 刷新invalid_grant察觉后继续 signed out。已发 access token 的后效遵循 RFC 7009 §2.1,不无条件"用到过期"。 - 负例(撤销后):revocation 生效后新 access token 不可获得;收到
session_ended(400)时换新sid重发,重发仍得session_ended则停止。
三种动作的精确语义与排障见OAuth 排障页。
检查单
| # | 检查点 | 判定 |
|---|---|---|
| 1 | poppy.json 可发现且字段合法 | 缺失即未参与 |
| 2 | issuer/resource 双向一致 | 单侧不一致拒绝 |
| 3 | Direct Sign-In 全标准字段 | 私有字段即偏离 |
| 4 | consent 全量 scope | 漏列即错误 |
| 5 | 会话头逐项校验 | 错 aud/过期/重放各自可判 |
| 6 | tasks.endpoint 按会话可用 | — |
| 7 | 浏览器 code 一次性 | 重放必败 |
| 8 | 撤销语义分层 | 登出≠断连≠会话终止 |
本向导是静态检查单,未连接真实实现;逐步实施时以1.0 规范源文件的请求、算法与错误定义为准。