GitHub Enterprise implements the SAML 2.0 standard. We officially support the following identity providers:

• Azure AD
• Okta
• OneLogin
• Shibboleth

Username considerations with SAML

GitHub Enterprise usernames can only contain alphanumeric characters and dashes (-). GitHub Enterprise 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 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:

Username	Normalized username	Result
Ms.Bubbles	ms-bubbles	This username is created successfully.
!Ms.Bubbles	-ms-bubbles	This 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!!Bubbles	ms--bubbles	This username is not created, because it contains two consecutive dashes.
Ms!Bubbles	ms-bubbles	This username is not created. Although the normalized username is valid, it already exists.
Ms.Bubbles@example.com	ms-bubbles	This 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 on the GitHub Enterprise appliance. Two-factor authentication may be supported by the external authentication provider.

SAML metadata

your GitHub Enterprise 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

The following attributes are available.

Attribute name	Type	Description
NameID	Required	The GitHub Enterprise username. It may only contain alphanumeric characters or dashes, and cannot begin with a dash. The name identity format is urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.
administrator	Optional	When 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.
full_name	Optional	The name of the user displayed on their profile page. Users may change their names after provisioning.
emails	Optional	The email addresses for the user. More than one can be specified.
public_keys	Optional	The public SSH keys for the user. More than one can be specified.

Configuring SAML settings

1. Access the Management Console.

2. In the left sidebar, click Authentication.

3. Select SAML.

4. If you want to enable unsolicited response SSO, select idP initiated 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.

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

6. 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 instance to use internal nameservers.

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

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

Revoking access to your GitHub Enterprise 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.
• If an <Audience> element is provided as part of the <AudienceRestriction> element, it will be checked against the GitHub Enterprise Entity Id. This is currently the URL to the GitHub Enterprise 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.
• The Recipient attribute must be present and set to the ACS URL. For example:

<samlp:Response ...>
  <saml:Assertion ...>
    <saml:Subject>
      <saml:NameID ...>username</saml:NameID>
      <saml:SubjectConfirmation ...>
        <saml:SubjectConfirmationData Recipient="https://ghe.corp.example.com/saml/consume" .../>
      </saml:SubjectConfirmation>
    </saml:Subject>
  </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.