SAML 身份验证

如果使用 SAML 单一登录 (SSO)，并且用户无法通过身份验证来访问 GitHub，可以排查问题。

本文内容

关于 SAML 身份验证问题

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

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

配置 SAML 调试

可以将 GitHub Enterprise Server 配置为写入每个 SAML 身份验证请求的详细调试日志。 可以使用此额外输出排查身份验证尝试失败的问题。

Warning

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

  1. 在 GitHub Enterprise Server 的右上角，单击你的个人资料照片，然后单击“企业设置”****。

    单击 GitHub Enterprise Server 上的个人资料照片时显示的下拉菜单的屏幕截图。 “企业设置”选项以深橙色边框突出显示。

  2. 在页面左侧的企业帐户边栏中，单击 “策略”。

  3. 在 “策略”下，单击“选项”。

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

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

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

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

响应解码

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

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

base64 --decode ENCODED_OUTPUT

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

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

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

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

该消息通常表示此人的用户名或电子邮件地址已在 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 与 你的 GitHub Enterprise Server 实例 的 ACS URL 不匹配，当用户尝试进行身份验证时，身份验证日志中将显示以下两条错误消息之一。

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 Enterprise Server 应用程序配置签名的断言。

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

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

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

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

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

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

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

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