我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

此版本的 GitHub Enterprise 将停止服务 此版本的 GitHub Enterprise 已停止服务 2020-05-23. 即使针对重大安全问题,也不会发布补丁。 要获得更好的性能、改进的安全性和新功能,请升级到 GitHub Enterprise 的最新版本。 如需升级方面的帮助,请联系 GitHub Enterprise 支持

文章版本: Enterprise Server 2.17

使用 SAML

SAML 是一种基于 XML 的身份验证和授权标准。 GitHub Enterprise Server 可以作为您的内部 SAML 身份提供程序 (IdP) 的服务提供程序 (SP)。

本文内容

如果要验证用户而不将他们添加到您的身份提供程序中,您可以配置内置身份验证。 更多信息请参阅“允许对身份提供程序覆盖范围以外的用户进行内置身份验证”。

支持的 SAML 服务

我们向执行 SAML 2.0 标准的所有身份提供程序提供有限的支持。 我们正式支持以下经过内部测试的身份提供程序:

  • Active Directory Federation Services (AD FS)
  • Azure Active Directory (Azure AD)
  • Okta
  • OneLogin
  • PingOne
  • Shibboleth

GitHub Enterprise 不支持 SAML 单次注销。 要终止活动的 SAML 会话,用户应该直接在 SAML IdP 上注销。

使用 SAML 时的用户名考量因素

每个 GitHub Enterprise Server 用户名都由 SAML 响应中的以下断言之一决定,这些断言按优先级从高到低排列的顺序为:

  • 自定义用户名属性(如果定义且存在)
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name 断言(如果存在)
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress 断言(如果存在)
  • NameID 元素

即使其他属性存在,也需要 NameID 元素。

将在 NameID 与 GitHub Enterprise Server 用户名之间创建映射,NameID 应持久、唯一,并且在用户生命周期内不会发生变化。

GitHub Enterprise Server 用户名只能包含字母数字和短划线 (-)。 GitHub Enterprise Server 会将帐户用户名中的所有非字母数字字符标准化为短划线。 例如,用户名 gregory.st.john 将标准化为 gregory-st-john。 请注意,标准化的用户名也不能以短划线开头或结尾。 它们还不能包含两个连续的短划线。

创建自电子邮件地址的用户名使用前置 @ 字符的标准化字符创建。

如果多个帐户标准化为同一个 GitHub Enterprise Server 用户名,则只创建第一个用户帐户。 使用相同用户名的后续用户无法登录。

此表格举例说明 GitHub Enterprise Server 中如何标准化用户名:

用户名标准化的用户名结果
Ms.Bubblesms-bubbles此用户名已成功创建。
!Ms.Bubbles-ms-bubbles此用户名无法创建,因其以短划线开头。
Ms.Bubbles!ms-bubbles-此用户名无法创建,因其以短划线结尾。
Ms!!Bubblesms--bubbles此用户名无法创建,因其包含两个连续的短划线。
Ms!Bubblesms-bubbles此用户名无法创建。 虽然标准化的用户名有效,但它已经存在。
Ms.Bubbles@example.comms-bubbles此用户名无法创建。 虽然标准化的用户名有效,但它已经存在。

双重身份验证

使用 SAML 或 CAS 时,双重身份验证在 GitHub Enterprise Server 设备上不受支持或无法管理,但受外部身份验证提供商的支持。 在组织上无法实施双重身份验证。 有关在组织上实施双重身份验证的更多信息,请参阅“您的组织中需要双重身份验证”。

SAML 元数据

您的 GitHub Enterprise Server 实例的服务提供程序元数据位于 http(s)://[hostname]/saml/metadata 下。

要手动配置您的身份提供程序,断言使用者服务 (ACS) URL 为 http(s)://[hostname]/saml/consume。 它使用 urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST 绑定。

SAML 属性

以下属性可用。 您可以在 Management Console 中更改属性名称,但 administrator 属性除外。

默认属性名称类型描述
NameID必选持久用户标识符。 可以使用任意持久名称标识符格式。 除非提供备用断言之一,否则将为 GitHub Enterprise Server 用户名使用 NameID 元素。
administrator可选如果值为“true”,用户将被自动升级为管理员。 任何其他值或不存在的值会将用户降级为普通用户帐户。
用户名可选GitHub Enterprise Server 用户名。
full_name可选用户的个人资料页面上显示的姓名。 用户可以在配置后更改他们的姓名。
emails可选用户的电子邮件地址。 可以指定多个。
public_keys可选用户的 SSH 公钥。 可以指定多个。
gpg_keys可选用户的 GPG 密钥。 可以指定多个。

配置 SAML 设置

  1. 在任何页面的右上角,单击

    用于访问站点管理员设置的火箭图标

  2. 在左侧边栏中,单击 管理控制台

    左侧边栏中的 管理控制台 选项卡

  3. 在左侧边栏中,单击 Authentication(身份验证)

    设置侧边栏中的身份验证选项卡

  4. 选择 SAML

    SAML 身份验证

  5. (可选)选择 Allow built-in authentication(允许内置身份验证)以邀请用户使用内置身份验证(如果他们不属于 您的 GitHub Enterprise Server 实例 的身份提供程序)。

    选中 SAML 内置身份验证复选框

  6. 或者,要启用非请求响应 SSO,请选择 IdP initiated SSO。 默认情况下,GitHub Enterprise Server 将向 IdP 发回 AuthnRequest,回复非请求身份提供程序 (IdP) 发起的请求。

    SAML idP SSO

    :我们建议保留此值处于未选择状态。 您应在罕见的情况下启用此功能,即您的 SAML 实现不支持服务提供程序发起的 SSO,并且 GitHub Enterprise 支持 建议执行此操作。

  7. 如果您希望 SAML 提供程序为 您的 GitHub Enterprise Server 实例 上的用户确定管理员权限,请选择 Disable administrator demotion/promotion(禁用管理员降级/升级)

    SAML 禁用管理员配置

  8. Single sign-on URL 字段中,为单点登录请求输入您的 IdP 上的 HTTP 或 HTTPS 端点。 此值由您的 IdP 配置提供。 如果主机只能在您的内部网络中使用,您需要先将 您的 GitHub Enterprise Server 实例 配置为使用内部域名服务器

    SAML 身份验证

  9. (可选)在 Issuer(签发者) 字段中,输入您的 SAML 签发者的姓名。 这将验证发送到 您的 GitHub Enterprise Server 实例 的消息的真实性。

    SAML 颁发者

  10. Signature Method(签名方法)Digest Method(摘要方法) 下拉菜单中,选择您的 SAML 颁发者用于验证 您的 GitHub Enterprise Server 实例 请求完整性的哈希算法。 使用 Name Identifier Format 下拉菜单指定格式。

    SAML 方法

  11. Verification certificate(验证证书)下,单击 Choose File(选择文件)并选择用于验证 IdP 的 SAML 响应的证书。

    SAML 身份验证

  12. 如果需要,请修改 SAML 属性名称以匹配您的 IdP,或者接受默认名称。

    SAML 属性名称

撤销 您的 GitHub Enterprise Server 实例 的权限

如果您将某个用户从您的身份提供程序中移除,还必须手动挂起他们。 否则,他们仍可以继续使用访问令牌或 SSH 密钥进行身份验证。 更多信息请参阅“挂起和取消挂起用户”。

响应消息的要求

响应消息必须满足以下要求:

  • The <Destination> element must be provided on the root response document and match the ACS URL only when the root response document is signed. 如果断言已签名,此元素将遭到忽略)。
  • The <Audience> element must always be provided as part of the <AudienceRestriction> element. It must match the GitHub Enterprise Server Entity Id. This is the URL to the GitHub Enterprise Server instance, such as https://ghe.corp.example.com.
  • 响应中的每一个断言都必须由数字签名加以保护。 签署各个 <Assertion> 元素或签署 <Response> 元素可以实现此操作。
  • <NameID> 元素必须作为 <Subject> 元素的一部分提供。 可以使用任意持久名称标识符格式。
  • Recipient 属性必须存在并设为 ACS URL。 例如:
<samlp:Response ...>
  <saml:Assertion ...>
    <saml:Subject>
      <saml:NameID ...>...</saml:NameID>
      <saml:SubjectConfirmation ...>
        <saml:SubjectConfirmationData Recipient="https://ghe.corp.example.com/saml/consume" .../>
      </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:AttributeStatement>
      <saml:Attribute FriendlyName="USERNAME-ATTRIBUTE" ...>
        <saml:AttributeValue>monalisa</saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

错误消息

如果 Recipient 与 ACS URL 不匹配,身份验证日志中将显示以下错误消息:

Recipient in the SAML response was not valid.

如果 Recipient 不是响应消息的一部分,身份验证日志中将显示以下错误消息:

Recipient in the SAML response must not be blank.

如果 SAML 响应未签名,或者签名与内容不匹配,身份验证日志中将显示以下错误消息:

SAML Response is not signed or has been modified.

如果 Audience 缺失或者与 GitHub Enterprise Server 实体 Id 不匹配,身份验证日志中将显示以下错误消息:

Audience is invalid. Audience attribute does not match your_instance_url

问问别人

找不到要找的内容?

联系我们