Work Notes | GitHub Enterprise Cloud EMU Initial Setup | Microsoft Entra ID (SAML) 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). I wrote more about this topic here.

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

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

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:

1. Tutorial: Microsoft Entra single sign-on (SSO) integration with GitHub Enterprise Managed User
2. Tutorial: Configure GitHub Enterprise Managed User for automatic user provisioning

Pre-Requisities

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: Create a MS Entra ID Enterprise Application

1. Open a new browser and go to https://azure.microsoft.com. Log in using the Cloud Application Administrator account.
2. Go to Microsoft Entra ID → Enterprise Applications
3. Click New application
4. Search for GitHub Enterprise Managed User
5. Select, change the name as needed, and then Save
6. In the newly created enterprise application, select Single sign-on → SAML
7. Edit the Basic SAML Configuration
8. Set the following values:
   
   • Identifier: https://github.com/enterprises/{enterprise_slug}
   • Reply URL: https://github.com/enterprises/{enterprise_slug}/saml/consume
   • Sign-on URL: https://github.com/enterprises/{enterprise_slug}/sso
9. Click Save
10. Scroll down and look for SAML Certificates, click Edit
11. Click ... → PEM certificate download
12. Scroll down and look for Set up GitHub Enterprise Managed User (SAML)
13. Copy the values for “Login URL” and “Microsoft Entra Identifier”.
14. Go to Users and Groups and Assign GitHub Enterprise Owners, and maybe a few more users. Make sure you know the cretentials of at least one Enterprise Owner
15. KEEP THIS WINDOW OPEN as you will still need it later.

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

1. Go back to the browser window where you have the GHEC admin account logged in (in Step 1)
2. Go to Settings → Authentication Security
3. Check the Require SAML authentication box and enter the values as noted in Step 2.11 and 2.13.
   
   • Sign on URL = Login URL
   • Issuer = Microsoft Entra ID Identifier
   • Public certificate = {contents of the .pem certificate downloaded}
4. Click Test SAML configuration and log in with an Enterprise Owner account added in Step 2.14
5. Click Save SAML settings
6. Download the new set of Recovery Codes
7. Enable SAML authentication and continue
8. The result will look like this (and that’s ok!)
9. You may now close this browser (that’s logged in as {enterprise_shortcode}_admin)

Step 4: Configure Automatic User Provisioning

1. Go back to the browser window where you have the Microsoft Entra ID Enterprise Application open (in Step 2)
2. Select the “GitHub Enterprise Managed User” enterprise application that you just created
3. Go to Provisioning → Provisioning
4. Set Provisioning Mode = Automatic
5. In Admin Credentials, enter
   • Tenant URL: https://api.github.com/scim/v2/enterprises/{enterprise_slug}
   • Secret Token: {PAT from Step 1}
6. Test Connection
7. Click Save
8. 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
9. In Mappings validate Provision Microsoft Entra ID Groups
   
   • Add missing mappings as needed
     
   • In my case, it wasn’t missing anything.
10. After saving everything, go back to Provisioning → Provisioning and set Provisioning Status = On
11. Check Settings and define the Scope of users to be provisioned as needed (i.e. only assigned users or all users)
12. Click Save
13. 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 5: Validate SAML 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 (SAML)! Head to the directory if you need to do more, like set-up Azure Billing.