企业接入向导:从发现到撤销

企业接入向导:从发现到撤销

本页把正式 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 排障页。

检查单

#检查点判定
1poppy.json 可发现且字段合法缺失即未参与
2issuer/resource 双向一致单侧不一致拒绝
3Direct Sign-In 全标准字段私有字段即偏离
4consent 全量 scope漏列即错误
5会话头逐项校验错 aud/过期/重放各自可判
6tasks.endpoint 按会话可用—
7浏览器 code 一次性重放必败
8撤销语义分层登出≠断连≠会话终止

本向导是静态检查单,未连接真实实现;逐步实施时以1.0 规范源文件的请求、算法与错误定义为准。

最后更新于