本指南旨在帮助管理员解决下游业务系统（作为服务提供者 SP）通过飞连（作为身份提供者 IdP）进行 SAML 集成时遇到的各类异常场景（如：登录跳转失败、认证报错、登录后属性缺失等）。借助本文中的排查方法，管理员可快速定位问题方并解决两端配置不一致等核心问题。

适用问题 #

• 链路跳转类：在业务系统点击“SAML 登录”无法跳转至飞连，或跳转地址异常。
• 认证解析类：跳转至飞连后立即报错（如 invalid request、请求被拒绝）。
• 断言校验类：飞连认证成功并回跳业务系统后，业务系统报错、登录失败或提示用户不存在。
• 属性缺失类：登录业务系统后，无法正确获取用户名、工号等关键信息。

相关术语说明 #

背景知识：SAML SSO 登录流程 #

在与企业进行用户 SSO 集成时，飞连作为身份提供者（IdP），企业自有的业务系统则作为服务提供者（SP）。通过 IdP 颁发的 SAML 断言（Token），下游应用提供者能够确定自身用户与飞连用户的对应关系，从而实现免密访问。
标准登录交互过程如下（以 SP 发起的单点登录为例）：

1. 触发登录：企业用户通过浏览器访问业务系统（SP）的登录页面，点击“单点登录”等按钮，向业务系统发起登录请求。
2. 生成认证请求：业务系统接收到请求后，生成一个标准的 SAML 认证请求（SAMLRequest），并将其返回给用户的浏览器，要求浏览器重定向至飞连。
3. 转发认证请求：浏览器根据指引，将 SAMLRequest 转发给身份提供者（IdP，即飞连）。
4. 身份认证与签发响应：飞连接收到请求后，校验请求的合法性，并引导用户完成登录（如输入账号密码、进行多因素认证）。认证成功后，飞连生成包含用户身份信息的 SAML 响应（SAMLResponse） 返回给浏览器。
5. 转发响应：浏览器将接收到的 SAMLResponse 转发给业务系统的 SSO 服务地址（即 ACS URL）。
6. 校验与匹配：业务系统解析 SAMLResponse，通过提前配置好的公钥和互信规则验证断言的真伪，并根据断言中的 NameID 或属性字段匹配到对应的业务系统用户。
7. 完成登录：校验通过后，业务系统向浏览器返回登录成功的页面，用户自动进入业务系统，完成整个免密登录流程。

具体排查步骤 #

第一阶段：链路快速定位 #

通过对比“SP 发起”与“IdP 发起”两种模式，可以快速锁定是请求（Request）阶段还是响应（Response）阶段存在故障。

1. 尝试从飞连侧发起

• 操作：在飞连门户网站或飞连客户端的工作台中，直接点击目标业务系统的应用图标进行跳转。
• 判定结果：
  • 若在飞连自身认证失败（如登录失败、MFA 未通过）：说明流程尚未进入 SAML 阶段，属于飞连身份认证问题，不在本文排查范围内。
  • 若飞连认证成功，但未能进入业务系统（报错或跳转失败）：说明飞连已成功生成 SAMLResponse，但未通过业务系统校验，应重点检查 SAMLResponse。
  • 若能够成功进入业务系统：说明飞连生成的 SAMLResponse 可以被业务系统正常校验，IdP -> SP 链路是可用的。此时，若仅从 SP 发起流程存在问题，则说明故障出在业务系统发起的 SAMLRequest 报文或其构造逻辑上。

2. 尝试从业务系统发起

• 操作：打开业务系统登录页，点击“SAML 登录”或“单点登录”。
• 判定结果：
  • 若无法跳转至飞连，或跳转地址异常：说明请求未正确发出，通常为业务系统配置的 IdP 地址错误或跳转逻辑异常，需检查业务系统侧的 SSO 配置。
  • 若跳转至飞连后立即报错：说明飞连未能正确解析或接受该 SAMLRequest，应重点检查业务系统发出的 SAMLRequest。
  • 若飞连认证成功并回跳业务系统，但业务系统报错或登录失败：说明 SAMLRequest 基本正确，但飞连返回的 SAMLResponse 未通过业务系统校验，应重点检查 SAMLResponse。

第二阶段：报文取证与参数对齐分析 #

大多数 SAML 失败都是因为飞连与业务系统的参数配置不一致导致。请通过排查工具截获报文，按双方的 Metadata 和配置进行严格核对。

• SAMLRequest 的校验主要由 IdP 执行，重点在于“请求是否符合 IdP 的接收规则”。
• SAMLResponse 的校验主要由 SP 执行，重点在于“断言是否符合双方约定”。

1. 准备取证工具

SAML 协议的交互在前端浏览器完成，必须通过抓包查看具体的 XML 内容。

• 推荐方案（外网环境）：在 Chrome/Edge 扩展商店搜索并安装 SAML Chrome Panel 插件。该工具可自动解码 Base64 格式的 SAML 报文，直接呈现可读的 XML 文本。安装后按 F12 开启调试窗口，切换到 SAML 标签页即可使用。
• 备选方案（纯内网环境）：开启浏览器调试（F12） -> 勾选“保留日志（Preserve log）”和“停用缓存（Disable cache）” -> 尝试复现问题 -> 复现后将网络请求列表导出为 .har 文件并手动进行 Base64 解码。

2. 检查 SAMLRequest（SP -> IdP）

• 获取方式

  • 如果 SP 使用 POST binding 的方式发起请求，在 SP 发起的单点登录请求中，关注带有 https://<飞连门户>:10443/api/idp/sso 或类似请求，在请求的 payload 里可以找到 SAMLrequest：
    
  • 如果 SP 使用 HTTP-Redirect (GET) binding 的方式发起请求，在 S P发起的单点登录请求中，关注带有 sso?SAMLRequest 的请求，在请求体或者 Payload 里可以找到 SAMLrequest：
    

• 报文解析

  检查项	SAMLRequest 中的位置	飞连管理后台配置检查点	校验规则	典型不匹配现象
  Destination	AuthnRequest:Destination	IdP Metadata 中的 SingleSignOnService Location	必须完全一致（协议、域名、路径）	提示 Invalid request / 请求被拒绝
  Binding	ProtocolBinding 或实际 HTTP 方法	飞连声明支持的绑定方式	必须为 HTTP-Redirect 或 HTTP-POST	请求解析失败或无响应
  Issuer	<saml:Issuer>	飞连后台单点登录应用详情中的 Entity ID	必须完全一致	提示应用不存在或未配置
  ACS	AssertionConsumerServiceURL	飞连后台单点登录应用配置的 单点登录 URL	必须完全一致	回跳失败或请求被拒
  NameIDPolicy	<NameIDPolicy Format>	飞连支持的主键格式	需为 emailAddress、persistent、transient 或 unspecified	返回异常或无法生成断言

3. 检查 SAMLResponse（IdP -> SP）

• 获取方式
  关注从飞连跳转回业务系统时的最开始的几个请求，通常 Payload 中会包含解码后的 SAMLResponse 字段。
  

• 报文解析

  检查项	SAMLResponse 中的位置	SP 端配置检查点	校验规则	典型不匹配现象
  Issuer	<saml:Issuer>	SP Metadata 记录的飞连 Entity ID	必须完全一致	提示不信任来源或校验失败
  Audience	<saml:Audience>	业务系统自身的 Entity ID	必须完全一致	提示 Audience mismatch
  ACS	SubjectConfirmationData:Recipient	业务系统的 ACS URL	必须完全一致	登录回跳失败
  回跳地址	AuthnResponse:Destination	业务系统的 ACS URL	必须完全一致	无法接收响应
  NameID	<saml:NameID>	业务系统的主键校验规则（如要求工号）	飞连传递的主键值必须与 SP 期望的主键匹配	提示用户不存在
  Attribute	<saml:Attribute>	业务系统需要的属性列表（如姓名、部门）	属性名称和值需符合 SP 约定	登录后用户信息缺失

第三阶段：进阶场景与环境排查 #

1. 如何修改 NameID（自定义用户唯一标识）

飞连默认将用户的 Email 作为 NameID 传递。若下游业务系统要求使用工号或其它字段作为唯一标识，请在飞连管理后台按以下步骤操作：

1. 进入对应的单点登录应用配置页，找到映射关系模块，添加一行映射。
2. 关键参数设置：
   • 飞连字段：选择想要作为主键的原始字段，例如：员工 ID (user_id)。
   • 映射规则：选择 字段映射。
   • 应用字段：点击下拉框底部的 + 添加扩展字段，手动输入系统保留关键字：app_user_id（请确保全小写）并保存。
3. 配置后，飞连在签发断言时，会将该字段的值填入 <saml:NameID> 节点中传递给业务系统。

2. 系统时间不同步导致断言失效

SAML 流程依赖多处时间校验，包括：

• SAMLResponse 中的 NotBefore（生效时间）和 NotOnOrAfter（过期时间）。
• SAMLRequest 中的 IssueInstant（请求生成时间）。

若业务系统与飞连服务器时间不一致，可能导致断言被判定为“已过期”、“尚未生效”或“过期请求”。建议双方服务器均开启 NTP 时间同步，时间误差控制在 30 秒以内。

3. HTTPS 证书与 Binding 方式问题

• 证书合规性：若业务系统地址为 HTTPS 且证书不合规（如自签名证书、证书已过期、证书链不完整），浏览器可能会在底层拦截重定向或 POST 请求，导致 SAML 流程静默中断。
• Binding 方式匹配：需确认业务系统实际发起的 SAML 绑定方式（HTTP-POST 或 HTTP-Redirect），并确保飞连管理后台配置的接收方式与之兼容。

仍无法解决？ #

若通过上述报文分析和配置核对仍无法准确定位问题，请收集以下材料联系飞连技术支持：

1. 故障现象截图：包含浏览器地址栏完整 URL 的报错页面截图。
2. SAML 报文记录：提供导出的 .har 文件，或从抓包插件复制的完整 XML 文本（Request 和 Response）。
3. 配置对照图：飞连管理后台单点登录应用配置页截图 + 业务系统 SAML 配置页截图。
4. SP Metadata 文件（如有请提供）。
5. 底层服务日志（仅限私有化客户）：
   • 登录飞连服务器，获取核心日志：/opt/corplink/log/portal.*.log。
   • 或通过飞连运维平台获取：集群管理 > 服务列表 > 用户门户 > 查看详情 > 服务日志，下载 portal.*.log。