This version of GitHub Enterprise will be discontinued on This version of GitHub Enterprise was discontinued on 2020-08-20. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

Article version: Enterprise Server 2.18

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).

In this article

Did this doc help you?

If you want to authenticate users without adding them to your identity provider, you can configure built-in authentication. For more information, see "Allowing built-in authentication for users outside your identity provider."

Supported SAML services

We offer limited support for all identity providers that implement the SAML 2.0 standard. We officially support these identity providers that have been internally tested:

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

GitHub Enterprise does not support SAML Single Logout. To terminate an active SAML session, users should log out directly on your 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 lifecyle of the user.

GitHub Enterprise Server usernames can only contain alphanumeric characters and dashes (-). GitHub Enterprise Server will normalize any non-alphanumeric character in your account's username into a dash. For example, a username of gregory.st.john will be normalized to gregory-st-john. Note that normalized usernames also can't start or end with a dash. They also can't contain two consecutive dashes.

Usernames created from email addresses are created from the normalized characters that precede the @ character.

If multiple accounts are normalized into the same GitHub Enterprise Server username, only the first user account is created. Subsequent users with the same username won't be able to sign in.

This table gives examples of how usernames are normalized in GitHub Enterprise Server:

UsernameNormalized usernameResult
Ms.Bubblesms-bubblesThis username is created successfully.
!Ms.Bubbles-ms-bubblesThis username is not created, because it starts with a dash.
Ms.Bubbles!ms-bubbles-This username is not created, because it ends with a dash.
Ms!!Bubblesms--bubblesThis username is not created, because it contains two consecutive dashes.
Ms!Bubblesms-bubblesThis username is not created. Although the normalized username is valid, it already exists.
Ms.Bubbles@example.comms-bubblesThis username is not created. Although the normalized username is valid, it already exists.

Two-factor authentication

When using SAML or CAS, two-factor authentication is not supported or managed on the GitHub Enterprise Server appliance, but may be supported by the external authentication provider. Two-factor authentication enforcement on organizations is not available. For more information about enforcing two-factor authentication on organizations, see "Requiring two-factor authentication in your organization."

SAML metadata

Your GitHub Enterprise Server instances'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. In the upper-right corner of any page, click .

    Rocketship icon for accessing site admin settings

  2. In the left sidebar, click Management Console.

    Management Console tab in the left sidebar

  3. In the left sidebar, click Authentication.

    Authentication tab in the settings sidebar

  4. Select SAML.

    SAML authentication

  5. Optionally, select Allow built-in authentication to invite users to use built-in authentication if they don’t belong to your GitHub Enterprise Server instance's identity provider.

    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 Support.

  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 config

  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

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 GitHub Enterprise Server Entity Id. 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>

Error messages

If the Recipient does not match the ACS URL, the following error message will be present in the auth log:

Recipient in the SAML response was not valid.

If the Recipient is not part of the response message, the following error message will be present in the auth log:

Recipient in the SAML response must not be blank.

If the SAML response is not signed, or the signature does not match the contents, the following error message will be present in the auth log:

SAML Response is not signed or has been modified.

If the Audience is missing or does not match the GitHub Enterprise Server Entity Id, the following error message will be present in the auth log:

Audience is invalid. Audience attribute does not match your_instance_url

Did this doc help you?

Ask a human

Can't find what you're looking for?

Contact us