How to Properly Create a GitHub Organization Linked to a Client’s Microsoft Tenant (and Fix It If You Didn’t)

aferencz21
Aug 13
3 min read

When working with enterprise clients, aligning GitHub organizations with their Microsoft Entra ID (formerly Azure AD) tenant is critical for security, compliance, and streamlined identity management. Unfortunately, many teams create GitHub organizations without linking them to the client’s Microsoft tenant, leading to headaches later.

This guide covers:

How to properly set up a GitHub organization tied to a Microsoft tenant from the start.

How to fix an organization that was set up incorrectly.

Organizations and teams documentation - GitHub Docs

✅ Part 1: Properly Creating a GitHub Organization Linked to Microsoft Entra ID

Step 1: Choose the Right GitHub Plan

Use GitHub Enterprise Cloud (required for SAML SSO and SCIM provisioning).
If you need centralized identity and user lifecycle management, consider Enterprise Managed Users (EMU).

Step 2: Create the GitHub Organization

Sign in to GitHub Enterprise Cloud.
Create a new organization under your enterprise account (or request one from GitHub if using EMU).
Assign an initial admin account (preferably a service account, not a personal user).

Step 3: Integrate with Microsoft Entra ID

Add GitHub as an Enterprise App in Microsoft Entra:
- Go to Microsoft Entra Admin Center → Enterprise Apps → New Application → Add from Gallery.
- Search for GitHub Enterprise Cloud – Organization and add it.
Configure SAML SSO:
- In Entra, set Single Sign-On → SAML.
- Configure:
  - Identifier (Entity ID): https://github.com/orgs/<OrganizationName>
  - Reply URL: https://github.com/orgs/<OrganizationName>/saml/consume
  - Sign-on URL: https://github.com/orgs/<OrganizationName>/sso
- Download the SAML certificate and copy the Login URL and Identifier.
Enable SAML in GitHub:
- In GitHub, go to Organization Settings → Security → Enable SAML Authentication.
- Paste the SSO URL, Issuer, and certificate from Entra.
Test SSO with a test user before rolling out.

Step 4: Configure Automatic User Provisioning (Optional but Recommended)

In Entra, go to Enterprise Apps → GitHub → Provisioning.
Set Provisioning Mode = Automatic.
Enter:
- Tenant URL: https://api.github.com/scim/v2/organizations/<OrganizationName>
- Secret Token: Generated from GitHub (requires admin:enterprise scope).
Test the connection and enable provisioning.
Assign users/groups in Entra to control GitHub access.

❌ Part 2: How to Fix an Improperly Set Up GitHub Organization

If you created a GitHub organization without linking it to the client’s Microsoft tenant, here’s how to fix it:

Scenario A: Organization Exists but No SSO

Enable SAML SSO now:
- Follow the same steps as above to configure SAML in Entra and GitHub.
Communicate to users that they must re-authenticate via SSO.

Scenario B: Wrong GitHub Account Ownership

Transfer the organization to the correct enterprise account:
- In GitHub, go to Organization Settings → Danger Zone → Transfer Organization.
- Transfer to the client’s enterprise account (requires admin approval).

Scenario C: Users Already Onboarded Without Entra Integration

Enable SAML SSO and enforce it:
- GitHub will require users to link their accounts to Entra.
Optionally, migrate to Enterprise Managed Users for full identity control (requires GitHub support).

Scenario D: Azure Integration Issues

If GitHub org doesn’t appear in Azure services (e.g., Static Web Apps):
- Revoke and reauthorize GitHub access in GitHub Settings → Applications → Authorized OAuth Apps.
- Ensure the correct organization is authorized for Azure.