Post

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 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 → SettingsDeveloper SettingsPersonal access tokensTokens (classic)Generate new token (classic)
  5. Enter any valid name, Select scope = admin:enterprise Admin PAT Scope
  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 SettingsAuthentication 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!) SSO Config Results
  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 IDEnterprise 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.) Assign Users and Groups
  5. Go to ProvisioningProvisioning
  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
    User Provisioning Mappings
    • Add missing mappings as needed
      User Provisioning Actual Mappings
    • In my case, it was missing home and other
      User Provisioning Missing Mappings
    • Expression: Coalesce([mail], [userPrincipalName])
    • Target attribute: {as above} - Click Save
  11. In Mappings validate Provision Microsoft Entra ID Groups
    Group Provisioning Mappings
    • Add missing mappings as needed
      Group Provisioning Actual Mappings
    • In my case, it wasn’t missing anything.
  12. After saving everything, go back to ProvisioningProvisioning and set Provisioning Status = On Set Provisioning 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 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 GHEC Sign In
  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 GHEC Logged In

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.

This post is licensed under CC BY 4.0 by the author.