Page Comparison

...

GitHub Enterprise Server is the on-premise premises version of GitHub, the well-known source control hosting system. Note that this is distinct from GitHub Business Cloud, the business-support tier of their traditional cloud offering. Provided as a virtual-appliance, it supports a variety of authentication methods, the most relevant of which (to this documentation) is SAML.The official configuration documentation (as of GitHub Enterprise version 2.15)

GitHub's official configuration documentation can be found here: https://help.github.com/en/enterprise/2.15/admin/guides/user-management/using-saml/

While the official documentation covers most of the basics, there are a number of important caveats the bear mentioning below. If these caveats are ignored, your appliance can end up in a state that officially requires GitHub Enterprise technical support Support to intervene, lest you risk voiding your support contract.

...

Identity Provider Metadata

The GitHub Enterprise Enterprise Server appliance cannot consume federated or standalone metadata, but does let you configure settings in a self-service manner. In the Admin Console, it provides you with a number of text-fields and drop-downs, allowing you to provide the following pieces of information:

...

Service Provider Metadata

GitHub Enterprise Server provides access to its metadata at http(s)://[hostname]/saml/metadata. The file is unsigned, so deployers will want to download a copy and load it statically. The certificate contained within is long-lived (~10 years), and does not seem to change if SAML authentication is disabled and re-enabled, so keeping a static copy should not prove any more bothersome than usual.

...

Early in our testing, we found that whatever GitHub Enterprise Enterprise Server uses as its SP implementation (we suspect https://github.com/onelogin/ruby-saml but the appliance code is, unsurprisingly, obfuscated) did not properly account for clock skew, and was not tunable. As such, we preemptively remove the NotBefore condition from assertions we send to them.

...

	<!-- Container for any overrides you want to add. -->

	<util:list id="shibboleth.RelyingPartyOverrides">

		<!-- other overrides... -->
	
	    <!-- GitHub Enterprise Server doesn't handle allowable clock skew correctly, so
             disable the inclusion of a NotBefore condition in assertions sent to their
             SP. -->
        <bean parent="RelyingPartyByName" c:relyingPartyIds="https://github.myuniversity.edu">
            <property name="profileConfigurations">
                <list>
                    <bean parent="SAML2.SSO"
                          p:encryptAssertions="false"
                          p:includeConditionsNotBefore="false" />
                    <ref bean="SAML2.Logout" />
                </list>
            </property>
        </bean>

     </util:list>

...

Accounts in GitHub Enterprise are Server are provisioned just-in-time during sign-in, but can also be created out-of-band if you so choose. Account provisioning relies on both attributes released to the service, as well as the NameID value. It is imperative to get these right the first time, since certain data about SAML federated users (including the NameID) cannot be edited without contacting GitHub Enterprise Server, or potentially violating your support contract. See below for details.

...

GitHub Enterprise Enterprise Server claims to require a persistent (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent) NameID format, but then in the next sentence claims (of the NameID value) "it may only contain alphanumeric characters or dashes, and cannot begin with a dash".

What they really mean is for a given username, the NameID value released to GitHub Enterprise Server must never vary independently from the username. GitHub Enterprise does Server does not care what you actually call the NameID format.

From the GitHub Enterprise Enterprise Server documentation:

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

In our testing, we (the University of Iowa) found that GitHub Enterprise Server detects this condition by comparing both the NameID and username attributes released in a SAML assertion. If the username attribute value normalizes to a username GitHub Enterprise Enterprise Server is already aware of, but the NameID of the assertion does not match the first NameID GitHub Enterprise Enterprise Server received (and persisted) for said username, the login attempt is prevented.

...

Thus, in choosing a NameID format to use with GitHub EnterpriseEnterprise Server, deployers can take one of the following approaches:

1. Release a custom NameID format based on the same attribute that you release to GitHub Enterprise Enterprise Server as the username.
2. Release the Persistent NameID format if and only if it cannot vary independently from your username attribute. Given that many deployments generate their Persistent NameID based on a more stable attribute than the username (typically, an identifier internal to their IAM platform) this is unlikely to be the case.

Given the caveats on option two, you will most likely just want to release a custom NameID format based on the attribute you release to GitHub Enterprise Server as the username. Note that in either approach, if a user's username changes, they will be given a new account (and lose access to their old data), but given the caveats on how GitHub Enterprise Enterprise Server handles the NameID, there isn't a better option.

After deciding on a NameID format, make sure you add that to the GitHub Enterprise Enterprise Server metadata in a <md:NameIDFormat> element to trigger its use.

...

Attribute Requirements

GitHub Enterprise Enterprise Server supports a number optional attributes as documented here: https://help.github.com/enterprise/2.15/admin/guides/user-management/using-saml/#saml-attributes

...

1. If you do not explicitly specify an attribute mapping for username, GitHub Enterprise Enterprise Server will use the value of the NameID by default. If you've released a custom human-readable NameID format sourced from your username attribute, you're set. If not, carefully choose an attribute that makes sense for your institution, is unique and non-reassignable across all of your users, that cannot vary independently of your NameID value, and is human readable. See the "NameID Requirements" section above to understand why this is very, very important.
2. While it doesn't appear in the Admin Console, GitHub Enterprise Enterprise Server can consume an attribute (strictly) named "administrator", that contains a Boolean value indicating whether or not the authenticated user should be promoted to an administrator (or demoted to a regular user) during log-in. See the aforementioned official documentation for more details.

...