The initial EMU setup

READ THIS BEFORE CLICKING ON PASSWORD RESET LINK!!!!
Once your EMU instance is ready you will receive a password reset link. It is absolutely crucial to open the password reset link in a new incognito browser window and within 7 days! If the password reset link is opened in a non-incognito session or after 7 days window - the link will no longer work. Also, the reset your password option in GitHub UI is not meant to work with EMUs. The only option from there would be for your account manager to work with internal team to re-generate the link which would introduce a few days delay (or in busy times - a week).

When you sign up for Enterprise Managed Users (EMU), you most likely have provided three items to the GitHub team:

• Enterprise Identifier (also known as shortcode): This is the 3-8 character alpha-numeric short code (e.g. dtnrd) that will be appended to each username in your account, e.g. andrekolodochka_dtnrd. The first part of the username will come from Okta or Entra ID. This shortcode cannot be changed later! Talk to your friendly GitHub Solutions Engineer, they’ll be able to advise whether a particular value is available.
• Enterprise Account URL: e.g. datanerd, so the URL to access your account will be https://github.com/enterprises/datanerd This value should be unique across the whole GitHub platform, so if you pick something very generic it’s likely GitHub will add something like a _emu at the end.
• Email address of the first admin user: This is the email address of the administrator who will be setting up the EMU-enabled Enterprise Account. The password reset link for the first admin user will be sent to this email address. The sole purpose of it is to receive the password reset link and the email won’t be used from then on. As result, I strongly recommend providing an individual’s email address as the link sent to a distribution list or a shared mailbox might be opened by others who are not aware of the context and haven’t seen the red boxes above and below.

Resetting the password for the main admin account

All users (except one) in each EMU instance will come from your IdP and the usernames will be dictated by Okta/Entra ID. GitHub will add Enterprise Identifier at the end of the username (e.g. andrekolodochka_datanerd), but the first part of the user name will come from your IdP. However, you will need a user in your EMU instance with admin permissions first to configure the integration with your IdP. To avoid this “chicken and egg” problem, GitHub creates the initial admin account with user name <enterprise identifier>_admin, e.g. datanerd_admin. This will be a “local” user account which is not linked to your IdP.

During the initial set up, the password reset link for this user is sent to the email address provided in the initial request. The email will look like this:

If you are an existing GitHub user and already have a session active in your browser, by clicking on that link you will reset your personal GitHub account’s password and not the password of the admin in your new EMU instance.

It is absolutely crucial to open the password reset link in a new incognito browser window to avoid GitHub confusing your personal account with the new EMU instance’s admin account. If that does happen, the password reset link will no longer work and you will need to contact GitHub to generate a new link.

You need to click on that link within 7 days. “To get a new link, click here” option won’t work for EMUs and once the original link expires you’ll need to contact GitHub to generate a new one.

Majority of browsers offer an “Open link in incognito” context menu options.

If your browser doesn’t offer such an option - right click on the Set your password button, copy the link, open a new incognito browser window and copy-paste the link there.

The next screen will ask you to provide a new password. Given that this is the admin user for your whole enterprise account, I suggest picking a VERY strong password.

Once you provide the new password value and clicked on Change password button, you’ve successfully changed admin’s password:

You will also receive an email confirmation about the password change in your account:

Things to watch out for

• Do not just click on the link in the email! Instead, right click (or copy the link) and open in incognito browser.

Loging into your EMU Enterprise Account

Now that you’ve reset the password for your admin account, you can login into your EMU instance. Note, as this stage there are still no users in your enterprise account other than the initial admin.

To login as admin, either just log in from the screen after password reset or visit the usual GitHub login page https://github.com/login. Make sure that you use your EMU admin username (the one with _admin at the end, for example datanerd_admin) and password instead of your personal GitHub account username.

Once logged in, you will see a screen similar to what you would see on usual http://github.com (after all EMU is hosted on the same platform!). However, you should be able to find your new enterprise account by clicking in your profile picture in top right corner and selecting Your enterprises from the menu:

If you go into your EMU enterprise, you should notice two things:

1. The URL of the Enterprise Account should match the URL GitHub set up for you (in my example it’s https://github.com/enterprises/datanerd)
2. Unlike the classic Enterprise Account, EMU won’t ask you to create an organisation first. Instead, you’ll be required to configure single sign-on and SCIM user provisioning.

From here you can click on Configure a single sign-on button and follow the documentation to set up the connection to your identity provider.

Things to watch out for

• Do not use the email address to log in. Even though it says that you can provide your email address instead of user name to login, for EMU instances users have to use their username. EMU doesn’t support logins using email address.
• Do not create any objects (orgs, repos, etc) while logged in as EMU instance admin. EMU admin account should be used only for initial configuration of SAML SSO and SCIM and for recovery: if there are any issues with identity provider - EMU admin is the only account which will be able to adjust the settings as it doesn’t require IdP to log in.
• You cannot have a session with EMU and non-EMU organisations in the same browser. Either log into one at a time, use incognito mode for one or utilise profiles-like feature in Chrome.
• VERY IMPORTANT if you configured 2FA for the initial admin account: resetting 2FA for the initial admin is a very sensitive task for GitHub support and you will be asked to jump through quite a few hoops to prove who you are and that you are authorised to do so and that might take some time. And often you would need the access to that account in situations when you don’t have time. So make sure you can re-configure 2FA for the initial admin on another device at any time.
• Save the initial admin user credentials in a safe place.Usually the initial admin account is rarely used and therefore it is quite easy to forget/lose the credentials. Make sure you keep the credendials in a safeplace which can be accessed by the next administrator.

Configure SAML/OIDC

Once you log in, go to the enterprise settings and start by configuring SAML SSO. Please follow instructions for Okta, EntraID SAML, EntraID OIDC (there is also a very good walk-through video for that).

If you are not on Okta/EntraID/Ping - follow instructions for SAML through non-partner providers.

Things to watch out for

• You may want to create a personal access token for SCIM before you configure SAML/OIDC (see the section below about SCIM). Once you finish SAML/OIDC configuration, the initial admin user will have to use backup 2FA codes to log in and generate the token. Doing so before SAML/OIDC configuration avoids that hassle.
• Make sure to select correct enterprise application in EntraID. It must be GitHub Enterprise Managed User for SAML and GitHub Enterprise Managed User (OIDC) for OIDC
• Make sure to save backup codes at the end of SAML/OIDC set up. You will need these codes if you want to ever log into your instance with the initial admin user
• Only EntraID, Okta and Ping have out-of-the-box SCIM applications, so while you can easily configure any other SAML provider, you will have to build your own SCIM integration with those.

Configure SCIM user provisioning

Except the initial admin, all users in your EMU instance will be provisioned from your IdP through SCIM. Firstly, create personal access token as initial admin user with scim:enterprise scope and no expiration (you may want to do this before setting up SAML/OIDC) and then follow instructions for Okta, Entra ID SAML, Entra ID OIDC to configure SCIM user proviioning or build your own SCIM integration for other IdPs.

Now you are ready to start granting users/groups access to your GitHub Enterprise via your Identity Provider (IdP) by assigning Enterprise Owner or User roles to relevant users or groups in your identity provider.

Things to watch out for

• Unlike with the classic enterprise account, there is no option to add enterprise admin in EMU UI. Instead, you assign a user Enterprise Owner role in IdP. Once the user is provisioned to your EMU instance, they will have enterprise admin access.

Remaining steps

From here you start configuring your enterprise account policies, link your billing to your Azure subscription and create organisations.

Things to watch out for

• Make sure to perform all actions with your own username (e.g. johnsmith_dataner) and not as the initial admin user.