SAML 身份验证故障排除

如果使用 SAML 单一登录（SSO），并且用户无法进行身份验证才能访问 GitHub，则可以解决问题。

在本文中

关于 SAML 身份验证问题

GitHub Enterprise Server 会在 github-unicorn 容器的 systemd 日志中记录 SAML 身份验证失败的错误消息。 你可以查看此日志中的响应，还可以配置更详细的日志记录。

有关 SAML 响应要求的详细信息，请参阅 SAML 配置参考。

配置 SAML 调试

您可以将 GitHub Enterprise Server 配置为对每次 SAML 身份验证尝试都记录详细的调试日志。 可以使用此额外输出排查身份验证尝试失败的问题。

警告

  • 仅暂时启用 SAML 调试，并在完成故障排除后立即禁用调试。 如果始终启用调试，日志大小的增长速度会比平时快得多，这可能会对 GitHub Enterprise Server 的性能产生负面影响。
  • 在将这些设置应用到生产环境之前，先在预发布环境中测试 你的 GitHub Enterprise Server 实例 的新身份验证设置。 有关详细信息，请参阅“设置暂存实例”。

  1. 在 GitHub Enterprise Server 的右上角，单击你的个人资料头像，然后单击“Enterprise settings”****。

  2. 在页面顶部，单击“ 策略”。

  3. 在 “Policies”下，单击“Options”********。

  4. 在“SAML 调试”下，选择下拉列表并单击“启用”

  5. 尝试通过 SAML IdP 登录 你的 GitHub Enterprise Server 实例 。

  6. 查看在 你的 GitHub Enterprise Server 实例 上 github-unicorn 的 systemd 日志中的调试输出。 有关详细信息，请参阅“关于系统日志”。

  7. 完成故障排除后，选择下拉列表并单击“禁用”。

解码响应数据

systemd 的 github-unicorn 日记中的某些输出可能是 Base64 编码的。 可以访问管理程序并使用 base64 实用工具 你的 GitHub Enterprise Server 实例 解码这些响应。 有关详细信息，请参阅“访问管理 shell (SSH)”。

要解码输出，请运行以下命令，将 ENCODED_OUTPUT 替换为日志中的编码输出。

base64 --decode ENCODED_OUTPUT

Error: "Another user already owns the account"（错误：“其他用户已拥有该帐户”）

当用户首次使用 SAML 身份验证登录 你的 GitHub Enterprise Server 实例 时， GitHub 在实例上创建用户帐户，并将 SAML NameID 和 nameid-format 帐户映射到该帐户。

当用户再次登录时，GitHub Enterprise Server 将该账户的 NameID 和 nameid-format 映射与 IdP 的响应进行比较。 如果 IdP 响应中的 NameID 或 nameid-format 不再与 GitHub 为该用户预期的值匹配，则登录将失败。 用户将看到以下消息。

另一个用户已经拥有该帐户。 请让您的管理员检查身份验证日志。

该消息通常表示此人的用户名或电子邮件地址已在 IdP 上更改。 确保 GitHub Enterprise Server 上用户账户的 NameID 和 nameid-format 映射与您的 IdP 上该用户的 NameID 和 nameid-format 相匹配。 有关详细信息，请参阅“更新用户的 SAML NameID”。

Error: Recipient in SAML response was blank or not valid（错误：SAML 响应中的收件人为空或无效）

Recipient如果与 ACS URL 你的 GitHub Enterprise Server 实例不匹配，则当用户尝试进行身份验证时，以下两条错误消息之一将显示在身份验证日志中。

Recipient in the SAML response must not be blank.

Recipient in the SAML response was not valid.

确保在您的 IdP 中将 Recipient 的值设置为 你的 GitHub Enterprise Server 实例 的完整 ACS URL。 例如，https://ghe.corp.example.com/saml/consume。

Error: "SAML Response is not signed or has been modified"（错误：“SAML 响应未签名或已修改”）

如果您的 IdP 未对 SAML 响应进行签名，或者签名与内容不匹配，则身份验证日志中将显示以下错误消息。

SAML Response is not signed or has been modified.

确保在你的 IdP 上为 GitHub 应用程序配置签名断言。

Error: "Audience is invalid" or "No assertion found"（错误：“受众无效”或“未找到断言”）

如果 IdP 的响应中 Audience 的值缺失或不正确，则身份验证日志中将显示以下错误消息。

Audience is invalid. Audience attribute does not match https://YOUR-INSTANCE-URL

确保将 Audience IdP 上的值设置为 EntityId for 你的 GitHub Enterprise Server 实例，这是实例的完整 URL。 例如，https://ghe.corp.example.com。

错误：“当前时间早于 NotBefore 条件”

当 IdP 与 GitHub 之间的时间差太大时可能会发生此错误，这通常发生在自托管 IdP 中。

为防止此问题，我们建议将设备指向与 IdP 相同的网络时间协议 (NTP) 源（如果可能）。 如果遇到此错误，请确保 设备 上的时间与 NTP 服务器正确同步。 可以使用管理 shell 上的 chronyc 命令立即同步时间。 有关详细信息，请参阅“配置时间同步”。

如果使用 ADFS 作为 IdP，则对于 GitHub，也将 ADFS 中的 NotBeforeSkew 设置为 1 分钟。 如果 NotBeforeSkew 设置为 0，即使非常小的时间差（包括几毫秒）也会导致身份验证问题。

错误：“失败 - 更新的 SAML 验证返回了无效结果”

此错误可能会出现在 你的 GitHub Enterprise Server 实例 3.17.0 或更高版本中。 它表示 GitHub 无法正确处理从标识提供者收到的 SAML 响应。 请开具 GitHub 支持票证，以便 GitHub 支持和工程团队可以调查并解决问题。

错误：摘要不匹配

“摘要不匹配”错误指示 SAML IdP 使用的 SAML 签名证书不同于已上传的GitHub证书，或者所配置的****签名方法或GitHub与 IdP 所使用的不同。

从您的 IdP 重新下载此 SAML 证书，并使用在线工具对其进行验证，例如 OneLogin 的 X.509 证书格式化 工具。 然后在管理控制台的 GitHub Enterprise Server “身份验证”部分中再次上传 SAML 证书。 请参阅 从 Web UI 管理实例。