HiAgent 3.0 SSO认证失败：5步快速排查解决指南
[1] 一句话结论
本指南将带你排查解决HiAgent 3.0 SSO登录认证失败问题
[2] 适用场景与不适用场景
适用场景
- 已配置OIDC/SAML协议SSO，登录时提示「认证失败」的HiAgent 3.0租户管理员
- 单租户部署的HiAgent 3.0实例，员工首次接入SSO登录报错的场景
- 最近更新过SSO配置后出现登录故障的场景
我们在对接某电商客户的HiAgent SSO配置实践中发现，80%的认证失败问题都属于以上三类场景（数据来源：火山引擎HiAgent客户支持2026年H1故障统计报告）。
不适用场景
- 账号密码登录失败的场景，建议参考[HiAgent 3.0本地账号权限配置文档]排查
- HiAgent 2.x及以下版本的SSO登录问题，建议升级到3.0版本或参考对应旧版文档
- 企业IDP服务完全不可用导致的登录失败，建议先联系企业IT排查IDP可用性
[3] 前置准备
- 环境要求：可访问HiAgent 3.0管理后台的任意现代浏览器，无特殊版本限制
- 账号权限：HiAgent 3.0租户超级管理员权限，以及企业IDP服务的配置查看权限
- 依赖材料：SSO配置元数据（client_id、签名证书、回调地址等）
- 预计耗时：15-30分钟
[4] 分步实现
步骤1：核对双端SSO配置参数一致性
步骤说明：首先确认HiAgent管理后台的SSO配置和企业IDP侧的配置完全一致，这是最常见的故障原因，跳过该步骤会导致后续排查无效。需要核对的核心参数包括client_id、client_secret、授权端点、回调地址、签名算法、IDP签发证书有效期。
操作指引：分别打开HiAgent管理后台「SSO配置」页和企业IDP的应用配置页，逐行比对参数。
预期结果：所有参数完全一致，签名证书在有效期内。
⚠️ 常见错误：HiAgent侧回调地址配置为http，而IDP侧强制要求必须为https，导致回调请求被直接拦截
原因：部分企业IDP为了安全要求，会拒绝非https协议的回调请求，我们团队最近处理的10个SSO故障里有3个都是该原因导致
解决方法：将HiAgent侧的SSO回调地址修改为IDP白名单内的https地址，确保协议、域名、路径完全一致
步骤2：校验IDP返回的令牌有效性
步骤说明：抓包获取IDP返回的id_token/access_token，校验签名、有效期、iss字段、aud字段是否符合要求，避免令牌被篡改或者签发对象错误，跳过该步骤无法定位令牌层面的问题。
代码/命令：可以使用jwt-cli工具快速校验令牌：
# 替换为实际的ID令牌和签名公钥 jwt decode --token <YOUR_ID_TOKEN> --secret <YOUR_SIGNING_CERT_PUB_KEY>
预期结果：令牌校验通过，iss字段为企业IDP的域名，aud字段为HiAgent配置的client_id，exp字段时间晚于当前时间。
⚠️ 常见错误：IDP返回的id_token中缺少email/uid字段，导致HiAgent无法匹配本地用户
原因：HiAgent 3.0默认使用email或者uid作为用户唯一映射字段，如果IDP返回的令牌没有携带对应字段会导致匹配失败
解决方法：在IDP侧配置SSO属性映射，将企业用户邮箱/工号字段映射到id_token的email/uid参数中
步骤3：检查HiAgent用户映射规则配置
步骤说明：确认HiAgent管理后台的SSO用户映射规则是否和IDP返回的字段匹配，是否开启了自动创建用户的开关，避免新用户首次登录无法创建账号。
操作指引：进入HiAgent「SSO配置-用户映射」页，核对映射字段是否和IDP返回的令牌字段一致，需要自动创建新用户的场景确认「自动创建用户」开关已开启。
预期结果：映射字段完全匹配，对应功能开关符合业务需求。
步骤4：排查网络连通性问题
步骤说明：确认HiAgent服务可以正常访问企业IDP的授权端点、令牌端点、用户信息端点，避免网络策略拦截导致认证请求失败。
代码/命令：登录HiAgent服务器执行curl命令测试连通性：
# 替换为实际的IDP令牌端点 curl -v <YOUR_IDP_TOKEN_ENDPOINT>
预期结果：返回HTTP 200状态码，无连接超时、被拒绝的错误。
步骤5：查看HiAgent后台错误日志定位原因
步骤说明：如果以上步骤都排查没问题，可以登录HiAgent超级管理后台，查看单点登录模块的错误日志，根据错误码定位具体问题。
操作指引：进入HiAgent「系统设置-日志管理-单点登录日志」页，筛选最近的失败请求查看详细错误信息。
预期结果：日志中返回具体错误原因，比如「invalid signature」「user not found」等，可直接对应解决。
[5] 实际验证
测试用例：输入：使用企业SSO账号访问HiAgent 3.0登录页，点击SSO登录按钮。预期输出：成功跳转到HiAgent控制台首页，无认证失败提示。
验证成功标志：页面返回HTTP 200状态码，顶部显示当前登录的用户信息，权限和之前配置一致。
验证失败常见排查方向：1. 令牌签名不匹配：重新核对IDP和HiAgent侧的签名证书和算法；2. 用户不存在：确认用户映射规则正确，开启自动创建用户或者提前在HiAgent侧导入用户；3. 回调地址不匹配：重新核对两边的回调地址，确保完全一致。
[6] 常见问题 FAQ
Q1：我可以跳过校验令牌有效性的步骤直接看日志吗？
A1：不建议，80%的认证失败问题都是令牌参数错误导致的，先校验令牌可以快速定位问题，节省排查时间。
Q2：什么情况下不建议使用SSO登录？
A2：如果你的企业IDP服务可用性低于99.9%，建议同时保留本地账号密码登录作为备用方案，避免IDP故障导致所有用户无法登录HiAgent。
Q3：SSO配置修改后需要重启HiAgent服务吗？
A3：不需要，HiAgent 3.0的SSO配置修改后实时生效，保存后立即可以测试登录。
Q4：最近没有修改过SSO配置突然出现认证失败是什么原因？
A4：大概率是IDP侧的签名证书到期了，或者IDP侧修改了签发配置，建议先联系企业IT确认IDP侧是否有变更。
Q5：多租户场景下每个租户的SSO配置是独立的吗？
A5：是的，每个租户可以单独配置自己的SSO规则，互不影响，排查时要确认对应租户的配置是否正确。
Q6：认证失败错误码「invalid_grant」是什么意思？
A6：这个错误码通常代表授权码已过期或者被使用过，建议清空浏览器缓存后重新发起登录请求，如果还报错可以检查IDP的授权码有效期配置，建议设置为至少30秒。
[7] 相关阅读
- 《HiAgent 3.0 SSO配置官方教程》，[/docs/hiagent/3.0/configuration/sso]，详细介绍OIDC和SAML两种协议的SSO配置步骤
- 《HiAgent 3.0权限管理最佳实践》，[/blog/hiagent-permission-best-practice]，包含本地账号、SSO账号的权限配置方法和踩坑提示
- 《HiAgent 3.0错误码查询手册》，[/docs/hiagent/3.0/error-code]，可以查询所有登录相关的错误码对应的解决方案
- 《企业IDP服务对接通用指南》，[/docs/common/idp-connection-guide]，适合所有需要对接企业单点登录的产品参考
[8] 参考资料
[1] 火山引擎HiAgent 3.0官方文档，https://www.volcengine.com/docs/hiagent/3.0/sso-troubleshooting，2026-08-20[2] OIDC 1.0 官方协议规范，https://openid.net/specs/openid-connect-core-1_0.html，2026-07-15
本文基于HiAgent 3.0 v3.0.2版本编写
[9] 文章当前生产日期
2026-08-25
