OAuth / SSO 登录失败分层排查

适用

登录页能打开、第三方授权也完成了，但最终回到登录页或报错。典型链路：

登录页 → 身份提供方授权 → 回调域带 code/JWT → 应用换证接口 → 建立会话

任何一段成功都不等于登录成功；必须逐段取证。

1. 先分「页面打不开」与「能打开但登录失败」

• 页面打不开：先按通用网络排查（DNS、代理、TLS、hosts），不要进入 OAuth 链路。
• 能打开但登录失败：继续下面步骤，重点看换证接口与人机验证。

2. 测三段可达性

分别测：身份提供方端点、应用登录页、回调域。每段都做「直连 / 走代理」对照；只有一段失败就是出口/分流问题，不是账号问题。

3. 在真实浏览器复现并抓换证结果

• 打开开发者工具或网络记录，完成一次授权，按顺序记录：
  1. 回调 URL 是否带 code / JWT；
  2. 换证接口（如 /api/v4/login）的状态码与响应体；
  3. 换证后是否立刻请求 captcha / Turnstile 挑战。
• 授权成功、JWT 已签发 ≠ 登录成功；换证 400/403 才是失败点。
• 区分「换证 400」与「账号不存在/未关联」：看响应体错误码，不要只看状态码。

4. 换证 400 后紧跟人机验证：按挑战链路查

• 检查挑战脚本是否加载、是否处于 pending、页面是否可见。
• 隐藏视口 / 无头环境里 Turnstile 永远不会完成：这类复现只能定性，不能判红；要得到可失败结论，必须在真实可见窗口完成一次。
• 若挑战脚本被第三方统计/资源拖慢，先量资源耗时，再判断是否超时门槛。

5. 跨出口分流

登录页、身份提供方、回调域若走了不同出口（直连 + 代理混用），会触发风控并表现为换证失败。核对三段的出口 IP/代理规则是否一致；统一出口或统一直连后再复现。

6. 修复三类

1. 统一出口：登录页、身份提供方、回调域走同一代理/直连策略。
2. 换节点/换出口：当前节点被风控时，换一个出口并重新走完整链路。
3. 邮箱密码登录：OAuth 被风控阻断时的可用替代路径；确认账号已绑定邮箱。

7. 证据表（交付时逐项写）

边界

• 不在隐藏/无头环境宣称“登录链路通过”；只能写“授权段通过，换证段未验证”。
• 不把面板登录令牌当 API Key 填进模型配置；凭据只报掩码。
• Qoder 网页登录的接口与判读见 references/qoder-web-login.md；其他产品按同一结构补充。

相关

• 浏览器网页打不开：edge-net-check（命令）。
• 客户端网络层异常：agent-client-network-triage。
• 凭据形态鉴定：byok-model-retry。