GitHub Enterprise Cloud EMU Initial Setup | Microsoft Entra ID (OIDC) Configuration

This is part of a series of posts where I share my personal notes on setting up a new GitHub Enterprise Cloud (GHEC) environment, specifically for Enterprise Managed Users (EMU).

There can be a debate when choosing between SAML and OIDC. However, the main practical reason for using Microsoft Entra ID (OIDC) with GitHub is that it supports Conditional Access Policies (CAP). This is useful if you’re using the full features of GitHub Enterprise and have strict access requirements. I wrote more about this topic here.

If you prefer to configure SAML instead, go to Microsoft Entra ID (SAML) Configuration.

In this post, I am documenting my experience in configuring a GHEC EMU account with Microsoft Entra ID (OIDC).

Objective and Disclaimer: This post is 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 following official GitHub documentation for the most accurate and up-to-date information: Tutorial: Configure GitHub Enterprise Managed User (OIDC) for automatic user provisioning

Pre-Requisities

GitHub currently only supports Entra ID for OIDC. It’s important to note that each Entra ID tenant can only be associated with a single GHEC via OIDC. If you are not using Entra ID or if you already have an existing GHEC integrated via OIDC, it is recommended to configure SAML instead.

Before starting, the following user accounts are required:

1. The GHEC root admin account credentials (i.e. {enterprise-short-code}_admin, e.g. rt_admin)
2. An account with a Microsoft Entra ID Cloud Application Administrator role, on the tenant of the users and groups

Step-by-Step Guide

Step 1: Generate a Personal Access Token (PAT) for the GHE Admin

1. Open a new browser in private/incognito mode and go to https://github.com/enterprises/{enterprise_slug}
2. In the log-in screen, Sign in as the enterprise admin
3. Log in with your {enterprise_shortcode}_admin username and password (not recovery key)
4. Click your Profile Icon on the top right → Settings → Developer Settings → Personal access tokens → Tokens (classic) → Generate new token (classic)
5. Enter any valid name, Select scope = admin:enterprise
6. Click *Generate token
7. Copy the PAT to a temporary text file.
8. KEEP THIS WINDOW OPEN as you will still need it later.

Step 2: Enable GitHub Enterprise Managed User Single Sign-On (SSO)

1. Go back to https://github.com/enterprises/{enterprise_slug}/settings
2. Go to Settings → Authentication Security
3. Check the Require OIDC single sign-on and Save
4. Login with a Microsoft Entra ID Cloud Application Administrator account
5. Download the new set of Recovery Codes
6. Enable OIDC authentication and Continue
7. The result will look like this (and that’s ok!)
8. You may now close this browser (that’s logged in as {enterprise_shortcode}_admin)

Step 3: Configure Automatic User Provisioning

1. Open a new browser and go to the Azure Portal. Login with a Microsoft Entra ID Cloud Application Administrator account.
2. Go to Microsoft Entra ID → Enterprise Applications
3. Select the newly created “GitHub Enterprise Managed User (OIDC)” enterprise application
4. Go to Users and Groups and Assign one or more GitHub Enterprise Owners. Make sure you know the cretentials of at least one Enterprise Owner. (Tip: you may also start adding other users and groups with the User role here.)
5. Go to Provisioning → Provisioning
6. Set Provisioning Mode = Automatic
7. In Admin Credentials, enter
   • Tenant URL: https://api.github.com/scim/v2/enterprises/{enterprise_slug}
   • Secret Token: {PAT from Step 1}
8. Test Connection
9. Click Save
10. In Mappings validate Provision Microsoft Entra ID Users
    
    • Add missing mappings as needed
      
    • In my case, it was missing home and other
      
    • Expression: Coalesce([mail], [userPrincipalName])
    • Target attribute: {as above} - Click Save
11. In Mappings validate Provision Microsoft Entra ID Groups
    
    • Add missing mappings as needed
      
    • In my case, it wasn’t missing anything.
12. After saving everything, go back to Provisioning → Provisioning and set Provisioning Status = On
13. Check Settings and define the Scope of users to be provisioned as needed (i.e. only assigned users or all users)
14. Click Save
15. Go to Overview and Start Provisioning

Automatic user provisioning is now configured. This job runs every 40 minutes. If you can’t wait, you can manually provision for specific users and groups using the Provision on demand option.

Step 4: Validate OIDC Configuration

1. Open a new browser and go to https://github.com/enterprises/{enterprise_slug}
2. In the log-in screen, Sign in as normal by clicking the Continue button
3. If you are unable to log in, something went wrong. Review the previous steps and try again.
4. After logging in, you should see your username in the format of {entra_id_username}_{enterprise_shortcode} in the top right corner

Congratulations! You have successfully configured your GitHub Enterprise Cloud EMU for MS Entra ID (OIDC)! Head to the directory if you need to do more, like set-up Azure Billing.