SAML is an XML-based standard for authentication and authorization. GitHub Enterprise can act as a service provider (SP) with your internal SAML identity provider (idP).
GitHub Enterprise implements the SAML 2.0 standard. We officially support the following identity providers:
- Shibboleth
- Okta
- OneLogin
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 with a dash.
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. 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. |
SAML Metadata
Your 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
In the left sidebar, click Authentication.
Select SAML.
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 instance's DNS to use internal nameservers.
Under Verification certificate (replace existing), click Choose File and choose a certificate to sign SAML responses before they are sent. This certificate is used as a shared secret to verify incoming responses originated from the idP.
Revoking access to your 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
A response message must contain a Recipient
set to the Assertion Consumer Service 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>
In addition to the Recipient
attributes, the following will also be verified if supplied in the response message:
-
Destination
on the root response document will also be checked against the ACS URL. -
Audience
as part of the audience will be checked against the GHE Entity Id. This is currently the URL to the GitHub Enterprise instance, such ashttps://ghe.corp.example.com
.
Error messages
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 Recipient
does not match the ACS URL, the follow error message will be present in the auth log:
Recipient in the SAML response was not valid.