测试与故障排查
使用明确的流程结果定位登录问题，避免把服务可访问误判为 OAuth 全链路正常。
使用 OAuth 测试应用
打开 /authtest，按页面配置的客户端发起完整授权。它应帮助检查 Discovery、回调、PKCE 兑换和令牌校验。测试页面的能力以实际界面为准；尚未执行的步骤不能记为通过。
选择与控制台登记一致的客户端类型，两种模式均使用 https://auth.kai.com/authtest/callback：
- 公共 PKCE：对应「SPA 或原生公共应用」，只填写 Client ID，浏览器使用 PKCE 兑换令牌。
- 私密 Web：对应「服务端 Web 应用」，填写 Client ID 和当前有效的客户端密钥。密钥只提交给本站服务端，由服务端执行密钥认证、PKCE 兑换、令牌校验和撤销；不会写入报告或浏览器存储。
私密 Web 测试的密钥及事务在服务端内存中等待授权最多五分钟，回调仅使用一次。流程结束或超时后会尝试撤销本次令牌，并在有时限的清理结束后丢弃密钥。请在同一浏览器完成流程并保持 Cookie 开启。服务重启或发布会结束待处理测试，此时应重新开始；不要重放旧回调。测试报告只短期保留，刷新后可能需要重新测试。
如果回调通过，但兑换阶段提示「客户端认证被拒绝」，优先核对所选类型和当前密钥。PKCE 不替代私密 Web 客户端的密钥认证。
测试客户端必须和其他应用一样登记 redirect URI、scope 与资源权限。不能绕过 consent、关闭 PKCE 或使用生产账号密码作为自动化脚本配置。
常见错误
| 现象 | 优先检查 |
|---|---|
invalid_target |
resource 是否准确、已注册启用，客户端是否获准；纯登录可以省略 resource |
invalid_scope |
请求 scope 是否被客户端允许，且与资源 scope 有交集 |
invalid_client |
client ID、类型、secret 和 token endpoint 认证方式是否一致 |
| 回调被拒绝 | redirect URI 的协议、主机、端口和路径是否与登记一致 |
invalid_grant |
授权码是否重复使用或过期，PKCE verifier 是否匹配，授权是否已撤销 |
| JWT audience 不匹配 | ID token 检查 client ID，业务 access token 检查该 API 的 resource identifier |
| 解析组织角色失败 | organization_role 允许 null，access_version 是 number |
/mobile/callback 返回 400 |
旧端点需要有效 OAuth 响应，裸访问不是登录流程 |
| Device Code 长期等待 | 用户是否核对并批准，是否遵守 interval 和 slow_down |
不要在错误处理里自动删除 resource 后重试业务 API 请求，这会改变授权目标。若仅测试身份登录，应从开始就明确选择不含 resource 的流程。
验收清单
- 正确用户、客户端、回调与 scope 完成登录，ID token 和 UserInfo 的 sub 一致。
- 错误 state、nonce、issuer、audience 或 PKCE 被拒绝；重复授权码不可使用。
- 未登记回调、未授权资源、越权 scope 和被禁用应用不能取得访问权。
- 请求并获准 offline_access 后刷新成功，轮换与撤销行为符合客户端实现。
- 退出回跳、Auth 会话结束与接入方本地会话失效分别验证。
对线上测试只保留时间、环境、步骤状态和脱敏错误。不要保存完整 code、token、Cookie 或真实个人信息。本文不宣称任何生产测试已经执行。