GitHub Enterprise Cloud EMU Initial Setup | IdP Migration from Microsoft Entra SAML to OIDC

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).

In this post, I am documenting my experience in (1) migrating the IdP configuration of a GHEC EMU account from Microsoft Entra ID SAML to OIDC, and (2) the rollback process. If you are migrating from OIDC to SAML, the steps are very similar.

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: Migrating your enterprise to a new identity provider or tenant

Why Migrate to OpenID Connect (OIDC): Restrict network with GitHub Codespaces and Hosted Runners enabled

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). Utilizing OIDC with CAP allows you to:

• Use Microsoft Entra ID CAP to whitelist IP addresses that can access your source code in GitHub repositories.
• Enforce CAP to ensure even when using personal access tokens (PAT) or SSH keys.
• Enable use of GitHub Codespaces.
• Enable GitHub Actions Hosted Runners with dynamic IP addresses.

Many enterprise organizations require whitelisting IP addresses to protect source code from data exfiltration. With SAML, this is only possible through GitHub’s IP allow list. However, as detailed in this documentation, enabling GitHub’s IP allow list results in the following implications:

If you configure an IP allow list for your organization you won’t be able to use GitHub Codespaces for repositories owned by the organization.

If you use an IP allow list and would also like to use GitHub Actions, you must use self-hosted runners or GitHub-hosted larger runners with static IP address ranges. For more information, see “About self-hosted runners” or “About larger runners”.

By using Microsoft Entra ID (OIDC) with CAP, you can Skip IdP check for applications, enabling the use of GitHub Codespaces and hosted runners with dynamic IP addresses.

GHEC IdP Allow List

If you are using Copilot Business without GitHub Enterprise, the benefits of OIDC will be minimal for you. I recommend that you configure for SAML and keep OIDC as an open option for the future. This is because each Entra ID tenant can only be associated with one GHEC account via OIDC, but multiple GHEC accounts via SAML.

Preparing for Migration

1. Review the preparation guidance to determine if the notes about SCIM records apply to you. The guide operates under the assumption that normalized SCIM userName values will not change post-migration.
2. Have the following ready:
   • The GHEC root admin account credentials (i.e. {enterprise-short-code}_admin, e.g. rt_admin)
   • The SSO recovery codes (see here)
   • An account with a Microsoft Entra ID Cloud Application Administrator role, on the tenant of the users and groups
3. Plan for at least 1 hour of downtime, where other developers won’t be able to access the GitHub Enterprise account.
4. Have the Microsoft Entra ID Conditional Access Administrator and User Administrator on standby as there may be impact to the changes such as:
   • adding IP addresses previously in GitHub IP Allow Lists to the CAP,
   • user accounts which may need changes,
   • and other scenarios that may arise.

Migration Guide

Step 1: Disable MS Entra ID User Provisioning

1. Open a new browser and go to Azure portal. Log in using the Cloud Application Administrator account.
2. Go to Microsoft Entra ID → Enterprise Applications
3. Select the active “GitHub Enterprise Managed User” application (this is the default name, but it may have been renamed)
4. Navigate to the Provisioning tab
5. Click Stop Provisioning
6. Click Single sign-on
7. Look for the box that says “SAML Certificates”. Click Edit.
8. Click ... → PEM certificate download. Save this in case of rollback.
9. Look for the box that says “Set up GitHub Enterprise Managed User (SAML)”.
10. Copy the values for “Login URL” and “Microsoft Entra Identifier”.
11. DO NOT DELETE the application yet, as it may be needed for rollback.
12. KEEP THIS WINDOW OPEN as you will still need it later.

Step 2: Disable GitHub IdP Configuration

This step may take up to 1 hour to complete.

1. Open a new browser in private or incognito mode
2. Go to https://github.com/enterprises/{enterprise-slug}

3. In the log-in screen, Sign in as the enterprise admin

4. Log in using the {enterprise_shortcode}_admin username and password (not recovery key)

5. After logging in, you should see a post like this. If you don’t, go to https://github.com/enterprises/{enterprise-slug} again.
   

6. Click Use a recovery code
7. Enter one of your recovery codes (Note: each code is one-time use only)
8. Disable the IdP
   • Go to Settings → Authentication Security
   • Uncheck the active single sign-on configuration (SAML/OIDC) and click Save
     

9. Go to People → Suspended and wait for every member to be in this suspended list. (Note: This could take up to 1 hour depending on the number of users. You may choose to start the next step while waiting.)

10. KEEP THIS WINDOW OPEN (DO NOT CLOSE)!!! (If you do, you may need to use another recovery code to log-in)

From this point, the original configuration is disabled.

Step 3: Configure the IdP with Microsoft Entra ID

Configure the GHEC account with a new IdP. For Microsoft Entra ID, see:

• Microsoft Entra ID (OIDC) Configuration
• Microsoft Entra ID (SAML) Configuration

Step 4: Validate Migration

1. Open a new browser and go to https://github.com/enterprises/{enterprise-slug}. Log in with an Enterprise Owner account that was configured in the new GitHub Enterprise Managed User Entra ID enterprise application (not the {enterprise_shortcode}_admin account!)
2. If you are unable to log in, something went wrong. Review the previous steps and try again.
3. After logging in, go to People → Members, you should see that the original members to be successfully migrated are no longer suspended.

Congratulations! You have successfully migrated your IdP configuration!

Rollback Guide

This section documents the rollback process in case of issues during the migration.

Step 1: Disable MS Entra ID User Provisioning

Follow the same steps as Migration Guide: Disable MS Entra ID User Provisioning.

Step 2: Disable GitHub IdP Configuration

Follow the same steps as Migration Guide: Disable GitHub IdP Configuration.

Step 3: Re-enable Microsoft Entra ID (SAML) IdP

1. Go back to the private/incognito browser window with the logged in {enterprise_shortcode}_admin account. (If you closed the window, open a new one and log in to https://github.com/enterprises/{enterprise-slug} again, you may need to use another recovery code.)
2. Go to Settings → Authentication Security
3. Check Require SAML authentication
   • This step will ask you to re-enter values originally in the SAML configuration, which we copied in Migration Step 1.6 to 1.10.
     
   • Sign on URL = Login URL
   • Issuer = Microsoft Entra ID Identifier
   • Public certificate = {contents of the .pem certificate downloaded}
4. Click Test SAML configuration
5. Log in with an Enterprise Owner account that was configured in the original GitHub Enterprise Managed User Entra ID enterprise application (not the {enterprise_shortcode}_admin account!)
6. Click Save SAML settings
7. Download the new set of Recovery Codes
8. Enable SAML authentication and continue

If you see a screen that looks like this, congratulations! The IdP is now configured and so the {enterprise_shortcode}_admin account is not able to access the GHEC settings anymore.

Step 4: Re-start User Provisioning

1. Go back to the browser window with the logged in Cloud Application Administrator account. (If you closed the window, open a new one and log in to https://portal.azure.com again.)
2. Navigate to your original GitHub Enterprise Managed User Entra ID Enterprise Application
3. Go to Provisioning → Provisioning and set Provisioning Status = On
4. Save
5. Go to Overview and Start Provisioning

Automatic user provisioning is now reconfigured. 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 5: Validate Rollback

1. Open a new browser and go to https://github.com/enterprises/{enterprise-slug}. Log in with an Enterprise Owner account that was configured in the original GitHub Enterprise Managed User Entra ID enterprise application (not the {enterprise_shortcode}_admin account!)
2. If you are unable to log in, something went wrong. Review the previous steps and try again.
3. After logging in, go to People → Members, you should see that the original members are no longer suspended.

Congratulations! You have successfully rolled back your IdP configuration! Head to the directory if you need to do more, like set-up Azure Billing.