---
title: "联调与排错 - QiSSO"
description: "按配置、协议、浏览器和授权状态定位故障，并完成上线前验收。"
canonical_url: "https://docs.mcent.cn/qisso/troubleshooting"
---
# 联调与排错 - QiSSO

> 按配置、协议、浏览器和授权状态定位故障，并完成上线前验收。

先在独立测试环境完成整个用户流程，再验证失败与撤销场景。浏览器“看起来已登录”不能代替 BFF 的回调、令牌与权限校验。

## 推荐排查顺序

1. 从业务服务端请求 Discovery，确认 HTTP 状态、证书、完整 Issuer 与端点。
2. 对照管理员登记项检查 Client ID、客户端类型、认证方式、回调、scope 和授权流程。
3. 检查本次事务是否具有独立 state、nonce、S256 challenge，以及回调时能否取回原 verifier。
4. 查看换码和 ID Token 验证的错误类别，不打印原始授权码、令牌或 Secret。
5. 登录成功后再检查本地会话、业务角色与实时授权重新核验。

## 常见问题

<table>
<thead>
  <tr>
    <th>
      现象
    </th>
    
    <th>
      优先核对
    </th>
    
    <th>
      修复方向
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Discovery 404 或跳到登录页
    </td>
    
    <td>
      是否包含 <code>
        /realms/mcent
      </code>
      
      ，代理是否转发正确路径
    </td>
    
    <td>
      从完整 Issuer 读取元数据，不手工套用其他服务路径
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        issuer
      </code>
      
       不一致
    </td>
    
    <td>
      外部 HTTPS 地址与服务端配置是否一致
    </td>
    
    <td>
      统一接入环境的 Issuer，拒绝混用测试与生产
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        invalid_client
      </code>
    </td>
    
    <td>
      Client ID、当前 Secret、Basic/Post 认证方式、应用启用状态
    </td>
    
    <td>
      使用本应用配置；密钥轮换后同步 BFF 与服务任务
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        invalid_redirect_uri
      </code>
      
       或回调被拒绝
    </td>
    
    <td>
      协议、域名、端口、路径、尾部斜杠、查询
    </td>
    
    <td>
      按真实完整回调登记，请求和换码使用同一值
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        invalid_grant
      </code>
    </td>
    
    <td>
      code 是否用过或过期，verifier、客户端和回调是否属于同一事务
    </td>
    
    <td>
      重新发起登录；不要重放旧 code
    </td>
  </tr>
  
  <tr>
    <td>
      state 丢失或不匹配
    </td>
    
    <td>
      Cookie 的 Domain、Path、SameSite、HTTPS，是否多次登录覆盖事务
    </td>
    
    <td>
      绑定浏览器并原子消费，保留独立事务，不接受未绑定回调
    </td>
  </tr>
  
  <tr>
    <td>
      nonce、aud 或签名验证失败
    </td>
    
    <td>
      是否使用本次 nonce、本客户端 ID、正确 Issuer 与 JWKS
    </td>
    
    <td>
      拒绝登录，修复配置，不关闭校验
    </td>
  </tr>
  
  <tr>
    <td>
      未返回 Refresh Token
    </td>
    
    <td>
      <code>
        refresh_token
      </code>
      
       授权流程、<code>
        offline_access
      </code>
      
       注册与请求
    </td>
    
    <td>
      同时满足配置与请求条件；按实际响应处理
    </td>
  </tr>
  
  <tr>
    <td>
      登录成功但业务接口 403
    </td>
    
    <td>
      身份已验证是否也满足业务权限、应用授权、租户或资源归属
    </td>
    
    <td>
      检查服务端授权，不能只隐藏前端按钮
    </td>
  </tr>
  
  <tr>
    <td>
      服务令牌可签发但接口 401
    </td>
    
    <td>
      令牌类型、服务调用方允许名单、应用状态与有效期
    </td>
    
    <td>
      同时核对 scope、允许名单和资源接口策略
    </td>
  </tr>
  
  <tr>
    <td>
      服务接口 <code>
        INSUFFICIENT_SCOPE
      </code>
    </td>
    
    <td>
      本次令牌实际获批 scope
    </td>
    
    <td>
      由管理员按最小权限配置，不能只修改前端请求
    </td>
  </tr>
  
  <tr>
    <td>
      应用撤销后业务页面仍可用
    </td>
    
    <td>
      是否仍只使用旧本地会话或 JWT Claims
    </td>
    
    <td>
      按重新核验结果清理本地会话，收紧权限缓存
    </td>
  </tr>
  
  <tr>
    <td>
      用户登出后再次进入自动登录
    </td>
    
    <td>
      本地会话与 QiSSO SSO 会话是否分别结束
    </td>
    
    <td>
      明确本地退出与统一退出的产品含义
    </td>
  </tr>
</tbody>
</table>

## 嵌入式登录专项

<table>
<thead>
  <tr>
    <th>
      现象
    </th>
    
    <th>
      检查点
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      OPTIONS 预检失败
    </td>
    
    <td>
      请求 Origin 是否与已启用应用的 Web 来源精确一致；代理是否保留预检与允许头
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        invalid_origin
      </code>
    </td>
    
    <td>
      Origin 只含协议、域名与端口；当前应用已启用嵌入式；回调 Origin 与页面一致
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        invalid_csrf
      </code>
    </td>
    
    <td>
      header 是否来自当前 init，是否混用了另一标签页或重启前的事务
    </td>
  </tr>
  
  <tr>
    <td>
      缺字段导致 <code>
        invalid_request
      </code>
    </td>
    
    <td>
      init 是否包含 <code>
        nonce
      </code>
      
      、<code>
        response_type=code
      </code>
      
       和 <code>
        code_challenge_method=S256
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      密码通过但 MFA 总失败
    </td>
    
    <td>
      <code>
        credentials: include
      </code>
      
      、临时 Cookie、MFA 方法和事务状态是否正确
    </td>
  </tr>
  
  <tr>
    <td>
      跨站浏览器中无法继续
    </td>
    
    <td>
      实测第三方 Cookie 策略，必要时改用标准跳转登录
    </td>
  </tr>
  
  <tr>
    <td>
      事务已使用或状态冲突
    </td>
    
    <td>
      是否双击、并发提交、旧请求迟到；重启后取消旧事务 UI 更新
    </td>
  </tr>
  
  <tr>
    <td>
      429
    </td>
    
    <td>
      读取 <code>
        Retry-After
      </code>
      
      ，停止自动重试，不通过切换标识规避限流
    </td>
  </tr>
</tbody>
</table>

## 上线前验收

<table>
<thead>
  <tr>
    <th>
      范围
    </th>
    
    <th>
      必须覆盖的行为
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      基础登录
    </td>
    
    <td>
      首次登录、已有 QiSSO 会话再次登录、需授权确认的应用
    </td>
  </tr>
  
  <tr>
    <td>
      用户取消
    </td>
    
    <td>
      授权取消、关闭流程、登录中返回业务页；不创建半完成会话
    </td>
  </tr>
  
  <tr>
    <td>
      回调安全
    </td>
    
    <td>
      缺失/错误/重复 state、重复 code、过期事务、错误 nonce、非预期 Issuer
    </td>
  </tr>
  
  <tr>
    <td>
      Cookie
    </td>
    
    <td>
      直接进入回调、刷新、多个标签页、生产 HTTPS、所选 response mode
    </td>
  </tr>
  
  <tr>
    <td>
      授权变化
    </td>
    
    <td>
      撤销应用、禁用账号、角色或权限变更，本地会话按策略及时失效
    </td>
  </tr>
  
  <tr>
    <td>
      令牌
    </td>
    
    <td>
      过期、刷新失败、密钥轮换，令牌始终保留在服务端
    </td>
  </tr>
  
  <tr>
    <td>
      嵌入式
    </td>
    
    <td>
      密码错误、TOTP、备用码、Cookie 被阻止、CSRF 失败、事务超时与并发
    </td>
  </tr>
  
  <tr>
    <td>
      页面反馈
    </td>
    
    <td>
      按钮有明确动作；只有发起动作的控件显示 loading，取消与失败可恢复
    </td>
  </tr>
  
  <tr>
    <td>
      日志
    </td>
    
    <td>
      不记录凭据、验证码、完整回调、授权码、令牌或用户敏感资料
    </td>
  </tr>
</tbody>
</table>

验收记录写明实际环境、客户端类型、检查日期和通过/失败项。Discovery 或 HTTP 探针通过，只说明对应请求成功，不能写成真实用户登录、手机浏览器或权限撤销已经验证。

## 反馈问题需要什么

提供接入阶段、请求方法与路径、HTTP 状态、稳定错误码、发生时间，以及是否标准跳转或嵌入式流程。可以提供脱敏的客户端配置和参数名称；不要提交 Secret、Cookie、Authorization 头、授权码、密码或 MFA 码。


## Sitemap

See the full [sitemap](https://docs.mcent.cn/sitemap.md) for all pages.