Using SAML

SAML is an XML-based standard for authentication and authorization. GitHub Enterprise Server can act as a service provider (SP) with your internal SAML identity provider (IdP).

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

Supported SAML services

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 上注销。

Username considerations with SAML

Each GitHub Enterprise Server username is determined by one of the following assertions in the SAML response, ordered by priority:

  • The custom username attribute, if defined and present
  • An http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name assertion, if present
  • An http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress assertion, if present
  • The NameID element

The NameID element is required even if other attributes are present.

A mapping is created between the NameID and the GitHub Enterprise Server username, so the NameID should be persistent, unique, and not subject to change for the lifecycle of the user.

Note: If the NameID for a user does change on the IdP, the user will see an error message when they try to sign in to your GitHub Enterprise Server instance. To restore the user's access, you'll need to update the user account's NameID mapping. For more information, see "Updating a user's SAML 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 metadata

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

To configure your identity provider manually, the Assertion Consumer Service (ACS) URL is http(s)://[hostname]/saml/consume. It uses the urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST binding.

SAML attributes

These attributes are available. You can change the attribute names in the management console, with the exception of the administrator attribute.

Default attribute nameTypeDescription
NameIDRequiredA persistent user identifier. Any persistent name identifier format may be used. The NameID element will be used for a GitHub Enterprise Server username unless one of the alternative assertions is provided.
administratorOptionalWhen the value is 'true', the user will automatically be promoted as an administrator. Any other value or a non-existent value will demote the user to a normal user account.
usernameOptionalThe GitHub Enterprise Server username.
full_nameOptionalThe name of the user displayed on their profile page. Users may change their names after provisioning.
emailsOptionalThe email addresses for the user. More than one can be specified.
public_keysOptionalThe public SSH keys for the user. More than one can be specified.
gpg_keysOptionalThe GPG keys for the user. More than one can be specified.

Configuring SAML settings

  1. 从 GitHub Enterprise Server 上的管理帐户,点击任何页面右上角的 用于访问站点管理员设置的火箭图标

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

  3. 在左侧边栏中,单击 Authentication(身份验证)设置侧边栏中的身份验证选项卡

  4. Select SAML. SAML authentication

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

  6. Optionally, to enable unsolicited response SSO, select IdP initiated SSO. By default, GitHub Enterprise Server will reply to an unsolicited Identity Provider (IdP) initiated request with an AuthnRequest back to the IdP. SAML idP SSO

    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 支持.

  7. Select Disable administrator demotion/promotion if you do not want your SAML provider to determine administrator rights for users on your GitHub Enterprise Server instance. SAML disable admin configuration

  8. In the Single sign-on URL field, type the HTTP or HTTPS endpoint on your IdP for single sign-on requests. This value is provided by your IdP configuration. If the host is only available from your internal network, you may need to configure your GitHub Enterprise Server instance to use internal nameservers. SAML authentication

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

  10. 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. SAML method

  11. Under Verification certificate, click Choose File and choose a certificate to validate SAML responses from the IdP. SAML authentication

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

Updating a user's SAML NameID

  1. 从 GitHub Enterprise Server 上的管理帐户,点击任何页面右上角的 用于访问站点管理员设置的火箭图标
  2. In the left sidebar, click All users. "All users" sidebar item in site administrator settings
  3. In the list of users, click the username you'd like to update the NameID mapping for. Username in list of instance user accounts
  4. 在页面右上角,单击 SecuritySecurity 选项卡
  5. To the right of "Update SAML NameID", click Edit . "Edit" button under "SAML authentication" and to the right of "Update SAML NameID"
  6. In the "NameID" field, type the new NameID for the user. "NameID" field in modal dialog with NameID typed
  7. Click Update NameID. "Update NameID" button under updated NameID value within modal

Revoking access to your GitHub Enterprise Server instance

If you remove a user from your identity provider, you must also manually suspend them. Otherwise, they'll continue to be able to authenticate using access tokens or SSH keys. For more information, see "Suspending and unsuspending users".

Response message requirements

The response message must fulfill the following requirements:

  • The <Destination> element must be provided on the root response document and match the ACS URL only when the root response document is signed. If the assertion is signed, it will be ignored.
  • The <Audience> element must always be provided as part of the <AudienceRestriction> element. It must match the EntityId for GitHub Enterprise Server. This is the URL to the GitHub Enterprise Server instance, such as https://ghe.corp.example.com.
  • Each assertion in the response must be protected by a digital signature. This can be accomplished by signing each individual <Assertion> element or by signing the <Response> element.
  • A <NameID> element must be provided as part of the <Subject> element. Any persistent name identifier format may be used.
  • The Recipient attribute must be present and set to the ACS URL. For example:
<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>

Troubleshooting SAML authentication

GitHub Enterprise Server logs error messages for failed SAML authentication in the authentication log at /var/log/github/auth.log. For more information about SAML response requirements, see "Response message requirements."

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.

When the user signs in again, GitHub Enterprise Server compares the account's NameID mapping to the IdP's response. If the NameID in the IdP's response no longer matches the NameID that GitHub Enterprise Server expects for the user, the sign-in will fail. The user will see the following message.

Another user already owns the account. Please have your administrator check the authentication log.

The message typically indicates that the person's username or email address has changed on the IdP. Ensure that the NameID mapping for the user account on GitHub Enterprise Server matches the user's NameID on your IdP. For more information, see "Updating a user's SAML NameID."

Error: Recipient in SAML response was blank or not valid

If the Recipient does not match the ACS URL for your GitHub Enterprise Server instance, one of the following two error messages will appear in the authentication log when a user attempts to authenticate.

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. For example, https://ghe.corp.example.com/saml/consume.

Error: "SAML Response is not signed or has been modified"

If your IdP does not sign the SAML response, or the signature does not match the contents, the following error message will appear in the authentication log.

SAML Response is not signed or has been modified.

Ensure that you configure signed assertions for the GitHub Enterprise Server application on your IdP.

Error: "Audience is invalid" or "No assertion found"

If the IdP's response has a missing or incorrect value for Audience, the following error message will appear in the authentication log.

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

Ensure that you set the value for Audience on your IdP to the EntityId for your GitHub Enterprise Server instance, which is the full URL to your GitHub Enterprise Server instance. For example, https://ghe.corp.example.com.

上一个指南配置主机名下一个指南Site admin dashboard

此文档对您有帮助吗?

隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或者, 了解如何参与。