GitHub Enterprise Cloud EMU Initial Setup | Introduction

This post kicks off a series where I’ll share my personal notes on setting up a new GitHub Enterprise Cloud (GHEC) environment, specifically for Enterprise Managed Users (EMU), with Microsoft Entra ID serving as the Identity Provider (IdP).

Directory of Contents

1. Introduction (this post)
2. Azure Billing Configuration
3. IdP Configuration
   • with Microsoft Entra ID (OIDC)
   • with Microsoft Entra ID (SAML)
4. (Optional) IdP Migration from Microsoft Entra ID SAML to OIDC

Objective and Disclaimer: These posts are written for my future personal reference. I took screenshots as I configured a new GHEC EMU account while following the documentation from GitHub. There will surely be scenarios which are not covered in these posts. Please refer to the official GitHub documentation for the most accurate and up-to-date information.

GitHub Enterprise Cloud EMU Account Activation

Before you can create a new GHEC EMU environment, your GitHub account manager will need the following details to set up your enterprise account:

1. Enterprise Name: The official name of your enterprise account.
2. Enterprise Slug: A unique string that serves as the URL for your enterprise account. For example, for RazType, the URL would be https://github.com/enterprises/RazType.
3. Enterprise Short Code: A unique, shortened version of the URL for your enterprise account. For example, https://github.com/enterprises/rt will redirect to https://github.com/enterprises/RazType.
4. Admin E-mail Address: The email address of the root administrator account. Provide an e-mail address that is not associated to any existing GitHub account.

Upon creation, the admin will receive an email containing a link to activate the root GitHub Enterprise Managed Administrator Account. The username follows the format {enterprise-short-code}_admin (e.g. rt_admin). As part of the activation process, the admin will set their password. With activation complete, you can begin the initial configuration.

If the email address you provided is already associated as a primary email address with an existing GitHub account, the activation link will not work. Instead, it will attempt to reset the password for the other GitHub account. If you encounter this issue, you can resolve it by modifying the existing GitHub account first. Simply change the primary email address of that account before proceeding with the activation link.

2024-08-13 Update: If you have an Azure Subscription, you can now create a new GitHub Enterprise Account fully self-service. I wrote about this here.

GHEC EMU: Initial Configuration

graph LR
    subgraph "GitHub"
        A[Billing]
        B[Identity Provider #40;IdP#41;]
    end
    subgraph "Microsoft Entra ID Tenant B"
        subgraph "Enterprise Applications"
            C[GitHub Subscription Permission Validation]
        end
        C --- E[Azure Subscription]
    end
    subgraph "Microsoft Entra ID Tenant A"
        subgraph "Enterprise Applications"
            D[GitHub Enterprise Managed User]
        end
    end
    A --- C
    B --- D

GHEC EMU: Initial Configuration Diagram

For a new GHEC EMU environment, two primary configurations must be completed:

1. Azure Billing Configuration: This links your Azure subscription to the GitHub Enterprise account for the purpose of billing.
2. Identity Provider Configuration (IdP): This connects your Microsoft Entra ID tenant to the GitHub Enterprise account to manage user authentication.

Refer to the above diagram for visual clarification: Billing and IdP configurations are managed through separate Microsoft Entra ID Enterprise Applications. Note: While it is common to use the same Microsoft Entra ID tenant for both billing and identity configuration, it is not a requirement.

GitHub also supports other Identity Providers such as Okta and PingFederate. Unfortunately, I do not have accounts with these services to document the setup process. If you’re configuring your environment using these IdPs, please refer to the official documentation.

Let’s Get Started

Head to the directory and get started!