复用现有 OAuth:身份、授权与会话排障
本页是独立的中文排障参考,与英文站无一一对应页。已有 OAuth 与账号体系的企业接入 Poppy 时,最常见的排障错误是把三个不同的问题混成一个"登录坏了"。本页把三层分开,再给官方 Validator 的正确用法与撤销语义。
三层分别验证什么
| 层 | 验证主体 | 回答的问题 | 失败时长什么样 |
|---|---|---|---|
| Agent 身份 | 客户端元数据与公钥、委托密钥签名 | 这台个人 Agent 是它声称的那台吗 | 发现文档校验失败、delegation 链无效、invalid_session(签名层) |
| 用户授权 | OAuth:issuer、scope、access/refresh token、DPoP | 这个用户批了企业哪些权限 | invalid_token、刷新失败、scope 不足被业务层拒绝 |
| 会话 | 会话 JWT(Poppy-Session) | 这一轮请求属于哪个会话、绑定什么方法与 URL | invalid_session(过期/错 aud/错 htu/重放 jti) |
一个请求可以同时携带三层凭据,但它们由不同代码验证、在不同时机失败。排障先定位层:身份层问题在握手与每次签名都复现;授权层问题只在需要账号能力的请求出现;会话层问题通常伴随特定方法或 URL。
官方 Validator:三种模式,副作用不同
官方仓 kit/company/validate 提供三种用法,先分清再运行:
| 模式 | 做什么 | 副作用 |
|---|---|---|
survey <域名> | 仅 GET 抓取发现文档并报告 | 无状态,可对任意公开站点运行 |
check --file <文件> | 离线检查本地发现文件 | 无 |
check <部署> | 作为测试 Personal Agent 真实访问部署 | 可能建立 Session 与 Conversation;先核对目标与授权,不在不了解的生产部署上运行 |
自动检查覆盖:发现、元数据、Session、client assertion 与多类接口。仍需手工核对的真实项:sign-in 全流程、DPoP 密钥行为、signed-in 请求。自动检查局部通过不能推导完整 OAuth 或企业权限可用——报告要定位到具体接入层再读。
本站覆盖:官方 Validator 的测试套件与 survey 已在本地 fixture 上运行(英文站版本矩阵页记录);真实登录、拒绝与撤销流程本站未执行,下表按官方 1.0 行为整理,未经本站实测。
撤销的三种语义不互相替代
以下按官方 1.0 正文 §5.5(Ending Sessions and signing out)逐项对齐:
| 动作 | 官方行为 |
|---|---|
| 用户登出(sign-out) | 个人 Agent 撤销自己为该账号持有的全部 refresh token;该 client_id 在该账号下没有仍有效的 refresh token 即视为已登出。用过的会话继续的是 signed-out 模式:会话头照发但不带 access token,需要账号的请求收到 challenge |
| 企业侧断开连接(disconnect) | 企业在账号设置中断开该 Agent,同样撤销其该账号的 refresh token;个人 Agent 在请求返回 invalid_token 或刷新返回 invalid_grant 时察觉,之后继续 signed out,且不该在用户未要求时自动重新登录 |
| 结束单个 Session | 个人 Agent 停止使用该 sid;refresh token 不受影响。企业**可以(MAY)**记忆已结束的 sid:其请求返回 session_ended(HTTP 400),Agent 换新 sid 重发;旧会话的状态(如购物车)不延续,对话延续。企业也可以忘记旧 sid,此时同一 sid 的请求可能直接开始新会话 |
两个容易写错的细节:已发 access token 在 refresh token 被撤销后的后效遵循 RFC 7009 §2.1,由资源服务器决定,不能无条件写成"到期前仍有效";signed-out 会话里不需要账号的能力(如购物车、未用账号的对话)继续可用,用过的账号性操作保持原状但无 token 请求收到 challenge——这是"继续会话"的准确含义,不是"带着有效 token 服务到过期"。
排障清单:撤销 refresh token 后应无法换取新 access token;过期的 access token 返回 invalid_token 而非静默放行;收到 session_ended 时按官方要求换新 sid 重发,重发仍得 session_ended 则停止发送。
症状到层的快速定位
| 症状 | 先查 |
|---|---|
| 全部请求都失败,包括公开能力 | 身份层:发现文档、issuer/resource 双向、委托链 |
| 只有带 access token 的请求失败 | 授权层:token 过期、DPoP 密钥是否沿用取得 refresh token 的那一把、scope 是否覆盖动作 |
| 特定方法或 URL 失败,其他正常 | 会话层:htu/htm 绑定、aud、jti 重放 |
| 撤销后仍能访问 | 区分上面三种撤销:sign-out 后 access token 后效按 RFC 7009 §2.1;会话继续的是 signed-out 模式(无 token、需账号的请求收 challenge),不是带 token 服务到过期 |
具体字段与错误码以1.0 规范源文件为准。企业接入的完整八步路径见企业接入向导。来源含官方 Validator 说明,核对日 2026-11-16。