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 Server 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/nameassertion, if present - An
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressassertion, if present - The
NameIDelement
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. For more information, see "Error: 'Another user already owns the account'."
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:
| 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 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 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 name | Type | Description |
|---|---|---|
NameID | Required | A 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. |
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. |
username | Optional | The GitHub Enterprise Server username. |
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. |
gpg_keys | Optional | The GPG keys for the user. More than one can be specified. |
Configuring SAML settings
-
From an administrative account on GitHub Enterprise Server, click in the upper-right corner of any page.
-
In the left sidebar, click Management Console.
-
In the left sidebar, click Authentication.
-
Select SAML.
-
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.
-
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
AuthnRequestback to the IdP.