复用现有 OAuth:身份、授权与会话排障

复用现有 OAuth:身份、授权与会话排障

本页是独立的中文排障参考,与英文站无一一对应页。已有 OAuth 与账号体系的企业接入 Poppy 时,最常见的排障错误是把三个不同的问题混成一个"登录坏了"。本页把三层分开,再给官方 Validator 的正确用法与撤销语义。

三层分别验证什么

层验证主体回答的问题失败时长什么样
Agent 身份客户端元数据与公钥、委托密钥签名这台个人 Agent 是它声称的那台吗发现文档校验失败、delegation 链无效、invalid_session(签名层)
用户授权OAuth:issuer、scope、access/refresh token、DPoP这个用户批了企业哪些权限invalid_token、刷新失败、scope 不足被业务层拒绝
会话会话 JWT(Poppy-Session)这一轮请求属于哪个会话、绑定什么方法与 URLinvalid_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。

最后更新于