SAML SSO 对接失败怎么定位：飞连作 IdP、业务系统作 SP 的排查顺序
下游业务系统接飞连做 SAML 单点登录，常见故障有四类：点击「SAML 登录」跳不过去或跳转地址异常；跳到飞连就报 invalid request、请求被拒绝；飞连认证成功回跳后业务系统登录失败或提示用户不存在；登录成功后拿不到用户名、工号等属性。
先分清问题出在 Request 阶段还是 Response 阶段，再去看配置。两端参数不一致是最常见的原因，但盲目翻配置很容易改错一侧，所以第一步永远是用「谁发起」来缩范围。
术语对齐：metadata 是记录 SAML 各参数的元数据文件；Entity ID 取元数据 EntityDescriptor 的 entityID；ACS URL 取 AssertionConsumerService 的 Location；IdP 是飞连，SP 是业务系统。
登录链路
以 SP 发起为例：
- 用户访问业务系统登录页，点「单点登录」；
- 业务系统生成 SAMLRequest，要求浏览器重定向到飞连；
- 浏览器把 SAMLRequest 转给 IdP；
- 飞连校验请求，引导用户完成账号密码 / MFA 认证，成功后签发带身份信息的 SAMLResponse；
- 浏览器把 SAMLResponse 转发到 ACS URL；
- 业务系统用预置公钥与互信规则验签，并按 NameID 或属性字段匹配本地用户；
- 登录完成。
第一阶段：用两种发起方式切分故障
从飞连侧发起（飞连门户或客户端工作台点应用图标）：
- 飞连自身认证失败（登录失败、MFA 未过）：还没进 SAML 阶段，属飞连身份认证问题；
- 飞连认证成功但进不了业务系统（报错或跳转失败）：飞连已生成 SAMLResponse，但它没过业务系统校验，重点查 Response；
- 能正常进入：IdP → SP 链路可用。此时只有从 SP 发起才出问题，故障就在业务系统构造的 SAMLRequest 上。
从业务系统发起（登录页点「SAML 登录」）：
- 跳不到飞连或跳转地址异常：请求没正确发出，一般是业务系统里配的 IdP 地址错误或跳转逻辑异常；
- 跳到飞连立即报错：飞连解析或拒绝了这个 SAMLRequest，重点查 Request；
- 飞连认证成功回跳后业务系统报错 / 登录失败：Request 基本正确，Response 没通过校验，重点查 Response。
第二阶段：报文取证与参数对齐
SAMLRequest 由 IdP 校验（是否符合飞连接收规则），SAMLResponse 由 SP 校验（断言是否符合双方约定），两侧的对照对象不同。
取证
- 外网环境：Chrome/Edge 扩展商店装 SAML Chrome Panel，自动解码 Base64 报文并渲染成可读 XML；F12 打开调试窗口，切到 SAML 标签页。
- 纯内网环境：F12 勾选「保留日志（Preserve log）」和「停用缓存（Disable cache）」，复现问题后导出 .har 文件，再手动 Base64 解码。
SAMLRequest（SP → IdP）
获取方式：POST binding 看 https://:10443/api/idp/sso 这类请求，payload 里有 SAMLRequest；HTTP-Redirect（GET）binding 看带 sso?SAMLRequest 的请求。
| 检查项 | 对照对象 | 校验规则 | 典型不匹配现象 |
|---|---|---|---|
| Destination | IdP Metadata 的 SingleSignOnService Location | 协议、域名、路径完全一致 | Invalid request / 请求被拒绝 |
| Binding | 飞连声明支持的绑定方式 | 必须为 HTTP-Redirect 或 HTTP-POST | 请求解析失败或无响应 |
| Issuer | 飞连后台单点登录应用详情中的 Entity ID | 完全一致 | 应用不存在或未配置 |
| ACS | 飞连后台配置的「单点登录 URL」 | 完全一致 | 回跳失败或请求被拒 |
| NameIDPolicy | 飞连支持的主键格式 | emailAddress、persistent、transient、unspecified 之一 | 返回异常或无法生成断言 |
SAMLResponse（IdP → SP）
获取方式：看飞连跳回业务系统时最开始的几个请求，Payload 中通常有解码后的 SAMLResponse。
| 检查项 | 对照对象 | 校验规则 | 典型不匹配现象 |
|---|---|---|---|
| Issuer | SP Metadata 记录的飞连 Entity ID | 一致 | 不信任来源或校验失败 |
| Audience | 业务系统自身 Entity ID | 一致 | Audience mismatch |
| ACS | 业务系统 ACS URL（SubjectConfirmationData:Recipient） | 一致 | 登录回跳失败 |
| 回跳地址 | 业务系统 ACS URL（AuthnResponse:Destination） | 一致 | 无法接收响应 |
| NameID | 业务系统主键校验规则（如要求工号） | 飞连传递的主键值与 SP 期望匹配 | 提示用户不存在 |
| Attribute | 业务系统需要的属性列表（姓名、部门等） | 属性名称与值符合 SP 约定 | 登录后用户信息缺失 |
第三阶段：进阶场景与环境
把 NameID 改成本地工号
飞连默认用 Email 作 NameID。下游要求工号等唯一标识时：
- 进入对应单点登录应用配置页，找到「映射关系」模块，添加一行映射；
- 飞连字段选原始字段（如
员工 ID (user_id)），映射规则选「字段映射」，应用字段点下拉框底部的「+ 添加扩展字段」，手动输入保留关键字app_user_id（全小写）并保存。
配置后，飞连签发断言时会将该字段值填入 `` 传给业务系统。
时间不同步
SAML 多处依赖时间校验：SAMLResponse 的 NotBefore / NotOnOrAfter，SAMLRequest 的 IssueInstant。两端时间不一致会让断言被判「已过期」「尚未生效」或「过期请求」。两边都开 NTP，误差控制在 30 秒以内。
HTTPS 证书与 Binding
业务系统为 HTTPS 且证书不合规（自签名、已过期、证书链不完整）时，浏览器可能在底层拦截重定向或 POST，流程静默中断。Binding 侧要确认业务系统实际发起的是 HTTP-POST 还是 HTTP-Redirect，并保证后台配置的接收方式兼容。
仍无法解决时收集
- 故障现象截图（含完整 URL）；
- SAML 报文记录（.har 文件，或完整的 XML Request/Response）；
- 两端配置对照截图；
- SP Metadata 文件；
- 私有化客户日志：
/opt/corplink/log/portal.*.log，或走运维平台「集群管理 > 服务列表 > 用户门户 > 查看详情 > 服务日志」。
信源文档：飞连 SAML 单点登录排障指南