使用 SAML

About SAML for GitHub Enterprise Server

SAML SSO allows people to authenticate and access your GitHub Enterprise Server instance through an external system for identity management.

SAML 是一种基于 XML 的身份验证和授权� �准。 When you configure SAML for your GitHub Enterprise Server instance, the external system for authentication is called an identity provider (IdP). Your instance acts as a SAML service provider (SP). For more information, see Security Assertion Markup Language on Wikipedia.

If you want to authenticate some users without adding them to your identity provider, you can configure built-in authentication in addition to SAML SSO. 更多信息请参阅“允许对身份提供程序覆盖范围以外的用户进行内置身份验证”。

支持的 SAML 服务

GitHub Enterprise Server 支持 SAML SSO 与采用 SAML 2.0 � �准的 IdP 一起使用。 更多信息请参阅 OASIS 网站上的 SAML Wiki。

GitHub officially supports and internally tests the following IdPs.

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

GitHub Enterprise Server 不支持 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.Bubbles	ms-bubbles	此用户名已成功创建。
!Ms.Bubbles	-ms-bubbles	此用户名� 法创建，� 其以短划线开头。
Ms.Bubbles!	ms-bubbles-	此用户名� 法创建，� 其以短划线结尾。
Ms!!Bubbles	ms--bubbles	此用户名� 法创建，� 其包含两个连续的短划线。
Ms!Bubbles	ms-bubbles	此用户名� 法创建。 虽然� �准化的用户名有效，但它已经存在。
Ms.Bubbles@example.com	ms-bubbles	此用户名� 法创建。 虽然� �准化的用户名有效，但它已经存在。

双重身份验证

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

SAML 元数据

The service provider metadata for your GitHub Enterprise Server instance is available at http(s)://[hostname]/saml/metadata.

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

SAML 属性

以下属性可用。 You can change the attribute names in the management console, with the exception of the administrator attribute.

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

To specify more than one value for an attribute, use multiple <saml2:AttributeValue> elements.

<saml2:Attribute FriendlyName="public_keys" Name="urn:oid:1.2.840.113549.1.1.1" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
    <saml2:AttributeValue>ssh-rsa LONG KEY</saml2:AttributeValue>
    <saml2:AttributeValue>ssh-rsa LONG KEY 2</saml2:AttributeValue>
</saml2:Attribute>

配置 SAML 设置

1. From an administrative account on GitHub Enterprise Server, in the upper-right corner of any page, click .

   

2. If you're not already on the "Site admin" page, in the upper-left corner, click Site admin.

   

3. 在左侧边� �中，单击 管理控制台。

4. 在左侧边� �中，单击 Authentication（身份验证）。

5. 选择 SAML。

   

6. Optionally, to allow people to use built-in authentication if they don't have an account on your IdP, select Allow built-in authentication. 更多信息请参阅“允许对身份提供程序覆盖范围以外的用户进行内置身份验证”。

   

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

   

   Note: We recommend keeping this value unselected. You should enable this feature only in the rare instance that your SAML implementation does not support service provider initiated SSO, and when advised by GitHub Enterprise 支持.

8. 如果您不希望 SAML 提供程序为 your GitHub Enterprise Server instance 上的用户确定管理员权限，请选择 Disable administrator demotion/promotion（禁用管理员降级/升级）。

   

9. Optionally, to allow your GitHub Enterprise Server instance to send and receive encrypted assertions to and from your SAML IdP, select Require encrypted assertions. For more information, see "Enabling encrypted assertions."

   

   Warning: Incorrectly configuring encrypted assertions can cause all authentication to your GitHub Enterprise Server instance to fail.

   • You must ensure that your IdP supports encrypted assertions and that the encryption and key transport methods in the management console match the values configured on your IdP. You must also provide your GitHub Enterprise Server instance's public certificate to your IdP. For more information, see "Enabling encrypted assertions."

   • Before enabling encrypted assertions, GitHub recommends testing encrypted assertions in a staging environment, and confirming that SAML authentication functions as you expect. 更多信息请参阅“设置暂存实例”。

10. In the Single sign-on URL field, type the HTTP or HTTPS endpoint on your IdP for single sign-on requests. 此值由您的 IdP 配置提供。 If the host is only available from your internal network, you may need to configure your GitHub Enterprise Server instance to use internal nameservers.

    

11. Optionally, in the Issuer field, type your SAML issuer's name. This verifies the authenticity of messages sent to your GitHub Enterprise Server instance.

    

12. In the Signature Method and Digest Method drop-down menus, choose the hashing algorithm used by your SAML issuer to verify the integrity of the requests from your GitHub Enterprise Server instance. Specify the format with the Name Identifier Format drop-down menu.

    

13. 在 Verification certificate（验证证书）下，单击 Choose File（选择文件）并选择用于验证 IdP 的 SAML 响应的证书。

    

14. Modify the SAML attribute names to match your IdP if needed, or accept the default names.

    

Updating a user's SAML NameID

1. From an administrative account on GitHub Enterprise Server, in the upper-right corner of any page, click .

   

2. If you're not already on the "Site admin" page, in the upper-left corner, click Site admin.

   

3. 选择 SAML。

4. 在用户列表中，点击您想要更新其 NameID � 射的用户名。

5. 在页面右上角，单击 Security。

6. 在“Update SAML NameID（更新 SAML 名称 ID）”右侧，单击 Edit（编辑）。

7. 在“NameID（名称 ID）”字段中，为用户键入新的 NameID。

8. 单击 Update NameID（更新名称 ID）。

撤销 your GitHub Enterprise Server instance 的权限

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

响应消息的要求

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

• <Destination> 元� 必须在� �响应文档上提供，而且只有在� �响应文档签署后才匹配 ACS URL。 如果断言已签名，它将被忽略。
• <Audience> 元� 必须始终作为 <AudienceRestriction> 元� 的一部分提供。 It must match the EntityId for GitHub Enterprise Server. 这是 GitHub Enterprise Server 实例的 URL，如 https://ghe.corp.example.com。
• Each assertion in the response must be protected by a digital signature. 签署各个 <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>

SAML 身份验证

GitHub Enterprise Server 在 /var/log/github/auth.log 的身份验证日志中为失败的 SAML 身份验证记录错误消息。 关于 SAML 响应要求的更多信息，请参阅“响应消息要求”。

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

When a user signs in to GitHub Enterprise Server for the first time with SAML authentication, GitHub Enterprise Server creates a user account on the instance and maps the SAML NameID to the account.

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

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

该消息通常表示此人的用户名或电子邮件地址已在 IdP 上更改。 Ensure that the NameID mapping for the user account on GitHub Enterprise Server matches the user's NameID on your IdP. 更多信息请参阅“更新用户的 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.

Ensure that you set the value for Recipient on your IdP to the full ACS URL for your GitHub Enterprise Server instance. 例如，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 is invalid. Audience attribute does not match your_instance_url

确保对您的 GitHub Enterprise Server 实例将 IdP 上的 Audience 值设为 EntityId，这是 GitHub Enterprise Server 实例的完整 URL。 For example, https://ghe.corp.example.com.