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
GitHub Enterprise Server supports SAML SSO with IdPs that implement the SAML 2.0 standard. For more information, see the SAML Wiki on the OASIS website.
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 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 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 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
AuthnRequest
back to the 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 Support.
-
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.
-
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.
-
Optionally, in the Issuer field, type your SAML issuer's name. This verifies the authenticity of messages sent to your GitHub Enterprise Server instance.
-
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.
-
Under Verification certificate, click Choose File and choose a certificate to validate SAML responses from the IdP.
-
Modify the SAML attribute names to match your IdP if needed, or accept the default names.
Updating a user's SAML NameID
- From an administrative account on GitHub Enterprise Server, click in the upper-right corner of any page.
- In the left sidebar, click All users.
- In the list of users, click the username you'd like to update the
NameID
mapping for. - In the upper-right corner of the page, click Security.
- To the right of "Update SAML NameID", click Edit .
- In the "NameID" field, type the new
NameID
for the user. - Click Update NameID.
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 theEntityId
for GitHub Enterprise Server. This is the URL to the GitHub Enterprise Server instance, such ashttps://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
.