Post

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

Here are some reasons on why you might choose SAML over OIDC:

  • If you are not using Microsoft Entra ID, as GitHub only supports Entra ID for OIDC.
  • If you already have an existing GHEC integrated via OIDC, as each Entra ID tenant can only be associated with a single GHEC via OIDC.
  • If you are using Copilot Business without GitHub Enterprise, the benefits of OIDC are minimal.

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

  1. Open a new browser and go to Azure portal. Log in using the Cloud Application Administrator account.
  2. Go to Microsoft Entra IDEnterprise 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-onSAML Enterprise App - SSO - SAML
  7. Edit the Basic SAML Configuration Enterprise App - SSO - SAML - Basic Config
  8. Set the following values:
    Enterprise App - SSO - SAML - Basic Config 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 SAML Certificates
  11. Click ...PEM certificate download Download PEM Certificate
  12. Scroll down and look for Set up GitHub Enterprise Managed User (SAML) 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 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
  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 SettingsAuthentication Security
  3. Check the Require SAML authentication box and enter the values as noted in Step 2.11 and 2.13.
    GHEC Authentication Security SAML Config
    • 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!) SSO Config Results
  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 ProvisioningProvisioning
  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
    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
  9. 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.
  10. After saving everything, go back to ProvisioningProvisioning and set Provisioning Status = On Set Provisioning 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 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 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 (SAML)! 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.