Skip to main content

SAML 身份验证

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

关于 SAML 身份验证问题

GitHub Enterprise Server 在 /var/log/github/auth.log 的身份验证日志中记录 SAML 身份验证失败的错误消息。 你可以查看此日志文件中的响应,还可以配置更详细的日志记录。

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

配置 SAML 调试

可以配置 GitHub Enterprise Server,以便每次尝试 SAML 身份验证时,向 /var/log/github/auth.log 写入详细的调试日志。 可以使用此额外输出排查身份验证尝试失败的问题。

警告:

  • 仅暂时启用 SAML 调试,并在完成故障排除后立即禁用调试。 如果使调试保持启用状态,日志的大小可能会比平常增加得快得多,这会对 GitHub Enterprise Server 的性能产生负面影响。
  • 在将 your GitHub Enterprise Server instance 的新身份验证设置应用到生产环境之前,请在过渡环境中测试这些设置。 有关详细信息,请参阅“设置暂存实例”。
  1. 在 GitHub Enterprise Server 的右上角,单击你的个人资料照片,然后单击“企业设置”。 GitHub Enterprise Server 上个人资料照片下拉菜单中的“企业设置” 1. 在企业边栏中,单击 “策略”。 企业帐户边栏中的“策略”选项卡 1. 在 “策略” 下,单击“选项” 。 企业帐户设置侧边栏中的“选项”选项卡

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

    用于启用 SAML 调试的下拉列表的屏幕截图

  3. 尝试通过 SAML IdP 登录 your GitHub Enterprise Server instance。

  4. 在 your GitHub Enterprise Server instance 上查看“/var/log/github/auth.log”中的调试输出。

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

    用于禁用 SAML 调试的下拉列表的屏幕截图

在 auth.log 中解码响应

auth.log 中的某些输出可能是 Base64 编码的。 可以访问管理 shell 并使用 your GitHub Enterprise Server instance 上的 base64 实用工具来解码这些响应。 有关详细信息,请参阅“访问管理 shell (SSH)”。

$ base64 --decode ENCODED_OUTPUT

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

当用户首次使用 SAML 身份验证登录 your GitHub Enterprise Server instance 时,GitHub Enterprise Server 会在实例上创建一个用户帐户并将 SAML NameID 映射到该帐户。

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

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

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

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

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

Recipient in the SAML response must not be blank.
Recipient in the SAML response was not valid.

请确保将 IdP 上的 Recipient 的值设置为 your GitHub Enterprise Server instance 的完整 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://<em>YOUR-INSTANCE-URL</em>

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

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

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

为防止此问题,我们建议将设备指向与 IdP 相同的网络时间协议 (NTP) 源(如果可能)。 如果遇到此错误,请确保 设备 上的时间与 NTP 服务器正确同步。

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