发现文档与企业身份校验
企业在 HTTPS 地址 https://{domain}/.well-known/poppy.json 公布发现文档。个人 Agent 取得文档后,不能只看到一个 API URL 就开始发送凭据。
校验两个方向
首先,organization.domain 应是重定向后真正提供文档的主机(非 443 端口要带端口)。然后按 RFC 9728 读取该域名的 protected resource metadata(/.well-known/oauth-protected-resource)找到 OAuth issuer,issuer 一侧再通过授权服务器元数据反向确认这个资源域。两个方向都对上,文档才可信;元数据列出多个授权服务器时,poppy.json 的 auth.issuer 指明个人 Agent 使用哪一个。
issuer 也不是必需的:protected resource metadata 返回 404、或授权服务器列表为空,企业就以 https://{organization.domain} 作为自己的标识提供未登录服务。只有超时、无效元数据或 issuer 校验失败不能回退到这种模式——那说明发现本身有问题。
企业自己定义 scope
正式 1.0 不再有协议预置的 poppy:read / poppy:write。每家企业在 auth.scopes 或自己的 OpenAPI 描述里定义 scope,并可用 scope_hints 标注每个 scope 的改动类型(不可逆 / 可逆 / 无改动)与是否涉及个人数据。协议唯一定义的 scope 是 poppy:browser-sign-in,用于让浏览器加入会话。
版本协商
protocol_version 声明文档遵循的版本,supported_versions 列出企业同时服务的其他版本。个人 Agent 选择自己实现的最新兼容版本,并在每个带会话头的请求上用 Poppy-Version 头声明;企业不认识或未服务该版本时返回 version_unsupported,双方各自调整后再试。
个人 Agent 也有身份
个人 Agent 的 client_id 是返回其元数据的 HTTPS URL。元数据中的 jwks_uri 公钥用来签署 client assertion 与密钥委托(delegation),不直接签署会话 JWT;企业从经校验的元数据取公钥和回调地址,不信任请求任意附带的密钥地址。
获取元数据时的限制
这是访问对方控制的 URL:限制超时、响应大小和重定向次数;不要带 Cookie 或授权头;协议禁止双方连接对方给出的回环、私网与链路本地地址,除非显式配置。发现重定向只认最终路径仍为 /.well-known/poppy.json 且无查询串的结果。
来源:1.0 规范源文件 §3和官方指南源文件。下一步:接入路线。