Skip to main content

Chapter 3: SCIM Provisioning & User Lifecycle

Part I: Foundation & Identity Prerequisites: Chapter 1: Enterprise Subscription & Environment Setup, Chapter 2: Identity & Single Sign-On GH-100 Exam Mapping: Domain 2 (Manage user identities and GitHub authentication — 11%) Verified: 2026-02-01 against official documentation

1. Introduction​

Learning Objectives​

After completing this chapter, you will be able to:

  • Configure SCIM (System for Cross-domain Identity Management) provisioning between Microsoft Entra ID and GitHub Enterprise Cloud to automate user account creation and deactivation
  • Map Entra ID security groups to GitHub teams to enforce automated team membership at scale
  • Implement the full user lifecycle -- onboarding, role changes, team transfers, and offboarding -- through identity provider (IdP) operations alone
  • Diagnose and resolve common SCIM provisioning failures using Entra ID provisioning logs and GitHub audit logs
  • Design a group-to-team mapping strategy for an organization with 50 or more developers that minimizes manual administration

Exam Domain Coverage​

DomainTopics in This Chapter
D2: Manage user identities and GitHub authentication (11%)SCIM provisioning configuration, automated user lifecycle management, group-to-team mapping, provisioning troubleshooting, attribute mapping, provisioning scopes and filters

Chapter Overview​

In See Chapter 2: Identity & Single Sign-On, you configured SAML or OIDC authentication so that developers prove their identity through your corporate identity provider. Authentication answers the question "who is this person?" But authentication alone does not answer "should this person have an account?", "which teams should they belong to?", or "what happens when they leave the company?" Those questions are answered by provisioning.

SCIM provisioning is the automated bridge between your identity provider and GitHub Enterprise Cloud. Instead of manually inviting users, assigning team memberships, and removing departed employees, SCIM allows Microsoft Entra ID to drive the entire user lifecycle. When a new developer is assigned to the GitHub application in Entra ID, SCIM creates their GitHub account or sends an invitation. When they are added to an Entra ID security group mapped to a GitHub team, SCIM updates their team membership. When they leave the organization and are removed from Entra ID, SCIM suspends or removes their GitHub account.

For enterprises with 50 or more developers, manual user management is not sustainable. A single missed offboarding creates a security exposure. A delayed onboarding costs productive hours. SCIM provisioning eliminates these risks by making the identity provider the single source of truth for GitHub access.

This chapter covers two provisioning models: organization-level SCIM provisioning (for enterprises using personal accounts with SAML SSO) and enterprise-level SCIM provisioning (for Enterprise Managed Users). Both models use the SCIM 2.0 protocol but differ in scope, capabilities, and configuration. By the end of this chapter, you will have a working SCIM integration that automatically provisions users and maps Entra ID groups to GitHub teams.


2. Theory & Deep Dive​

Understanding SCIM 2.0​

SCIM (System for Cross-domain Identity Management) is an open standard defined in RFC 7642, 7643, and 7644 that provides a common protocol for automating identity management across cloud applications. SCIM defines two primary resource endpoints:

  • /Users -- Create, read, update, and delete user accounts
  • /Groups -- Create, read, update, and delete groups and manage membership

The Microsoft Entra provisioning service acts as a SCIM client, making HTTP requests to GitHub's SCIM API endpoints. These requests flow over HTTPS and use JSON payloads conforming to the SCIM schema. The provisioning service runs on a cycle (approximately every 40 minutes after the initial synchronization) to detect and reconcile changes.

SCIM Operations Used by Entra ID:

HTTP MethodEndpointPurpose
POST/UsersCreate a new user account
GET/Users?filter=...Query for existing users by attribute
PATCH/Users/{id}Update user attributes (name, email, active status)
DELETE/Users/{id}Remove a user account
POST/GroupsCreate a new group
PATCH/Groups/{id}Update group membership
DELETE/Groups/{id}Remove a group

Enterprise Scenario: A 120-developer fintech company manually manages GitHub access. Their IT team spends an average of 4 hours per week processing onboarding requests, team membership changes, and offboarding tickets. After implementing SCIM provisioning, these tasks are automated through Entra ID group assignments, reducing the IT team's GitHub administration burden to occasional troubleshooting of provisioning exceptions.

Two Provisioning Models: Organization-Level vs. Enterprise-Level​

GitHub Enterprise Cloud supports SCIM provisioning at two levels, and the choice depends on your identity model (see Chapter 2: Identity & Single Sign-On for the identity model decision).

Organization-Level SCIM (Personal Accounts with SAML SSO)​

When your enterprise uses personal GitHub accounts with SAML SSO enforcement, SCIM provisioning operates at the organization level. This model uses the GitHub Enterprise Cloud - Organization application in the Microsoft Entra gallery.

Key characteristics:

  • SCIM manages organization membership (adding and removing members from the GitHub organization)
  • Users receive an email invitation when provisioned; they must accept it to join the organization
  • The SCIM endpoint URL pattern is: https://api.github.com/scim/v2/organizations/<Organization_name>
  • Authorization uses an OAuth app authorization flow (not a Personal Access Token)
  • SAML SSO must be configured and enabled at the organization level before SCIM will function
  • Each organization requires its own SCIM provisioning configuration in Entra ID

Limitations:

  • SCIM does not create GitHub accounts; users must already have a personal GitHub account or create one when they accept the invitation
  • Deprovisioning removes the user from the organization but does not delete their personal GitHub account
  • Group-to-team mapping requires team sync configuration, which is separate from core SCIM provisioning

Enterprise-Level SCIM (Enterprise Managed Users)​

When your enterprise uses the EMU (Enterprise Managed Users) model, SCIM provisioning operates at the enterprise level. This model uses the GitHub Enterprise Managed User (for SAML) or GitHub Enterprise Managed User (OIDC) application in the Entra gallery.

Key characteristics:

  • SCIM creates and fully manages user accounts (accounts do not exist until SCIM provisions them)
  • The SCIM endpoint URL pattern is: https://api.github.com/scim/v2/enterprises/{enterprise} (for github.com) or https://api.{subdomain}.ghe.com/scim/v2/enterprises/{subdomain} (for GHE.com)
  • Authorization uses a Personal Access Token (PAT) with the scim:enterprise scope, created by the enterprise setup user
  • SCIM handles both user provisioning and group provisioning (mapping Entra ID groups to GitHub teams)
  • Deprovisioning suspends the user's EMU account, blocking all access to the enterprise
  • A single provisioning configuration covers the entire enterprise (all organizations within it)

Comparison:

CapabilityOrganization-Level SCIMEnterprise-Level SCIM (EMU)
Account creationInvitation onlyFull account creation
Account ownershipUser (personal)Enterprise
Deprovisioning effectRemoves from orgSuspends account
ScopePer-organizationEntire enterprise
Authorization methodOAuth appPAT with scim:enterprise
SAML/OIDC prerequisiteOrg-level SAML requiredEnterprise-level SAML/OIDC required
Group-to-team mappingVia team syncNative SCIM group provisioning

Enterprise Scenario: A 500-developer enterprise has three GitHub organizations (platform, product, and data-engineering). With organization-level SCIM, they must configure three separate provisioning integrations in Entra ID, one per organization, and manage OAuth authorizations for each. After migrating to EMU with enterprise-level SCIM, a single provisioning configuration manages all users and groups across all three organizations, reducing administrative complexity significantly.

SCIM Attribute Mapping​

Attribute mapping defines how user properties in Microsoft Entra ID translate to user attributes in GitHub's SCIM schema. Correct attribute mapping is critical: misconfigurations cause provisioning failures, duplicate accounts, or incorrect user profiles.

User Attribute Mappings​

For Enterprise Managed Users (EMU):

Microsoft Entra AttributeGitHub SCIM AttributeRequiredNotes
mailNickname or objectIdexternalIdYesImmutable identifier used for matching. externalId is the primary matching attribute and must be unique.
userPrincipalNameuserNameYesBecomes the base of the EMU username (with enterprise shortcode appended)
Switch([IsSoftDeleted], , "False", "True", "True", "False")activeYesControls whether the account is active or suspended
displayNamedisplayNameNoFull display name shown in the GitHub UI
givenNamename.givenNameNoFirst name
surnamename.familyNameNoLast name
Join(" ", [givenName], [surname])name.formattedNoFormatted full name
mailemails[type eq "work"].valueNoWork email address

For Organization-Level SCIM (Personal Accounts):

Microsoft Entra AttributeGitHub SCIM AttributeNotes
userPrincipalNameuserNameMust match an email address on the user's personal GitHub account
mailemails[type eq "work"].valueUsed for invitation delivery
givenNamename.givenNameFirst name
surnamename.familyNameLast name

Critical Matching Property Warning: The externalId attribute (mapped from mailNickname or objectId in Entra ID) is used as the matching property to link Entra ID users to their GitHub accounts during update and deprovisioning operations. If this mapping is incorrect or if the matching attribute changes, the provisioning service cannot find the corresponding GitHub user, resulting in duplicate accounts or failed updates. Do not enable Matching precedence on other default attributes in the provisioning configuration, as this can cause errors.

Group Attribute Mappings​

For EMU provisioning, groups are synchronized to create and manage GitHub teams:

Microsoft Entra AttributeGitHub SCIM AttributeNotes
objectIdexternalIdImmutable group identifier
displayNamedisplayNameBecomes the GitHub team name
membersmembersList of user references for team membership

Group-to-Team Mapping Strategy​

One of the most impactful capabilities of SCIM provisioning is mapping Entra ID security groups to GitHub teams. This enables centralized access control: team membership changes in Entra ID automatically propagate to GitHub, and repository permissions tied to those teams apply immediately.

Designing Your Group Structure​

For organizations with 50 or more developers, a well-designed group structure is essential. Consider these patterns:

Pattern 1: Mirror Organizational Structure

Create Entra ID groups that reflect your engineering organization:

GH-Team-Platform-Backend
GH-Team-Platform-Frontend
GH-Team-Product-Mobile
GH-Team-Product-Web
GH-Team-Data-Engineering
GH-Team-Data-Science
GH-Team-Security
GH-Team-SRE

Each group maps to a GitHub team with the same name. Repository access is granted to teams, so when a developer moves from the Platform team to the Product team, updating their Entra ID group membership automatically updates their GitHub team membership and repository access.

Pattern 2: Role-Based Groups

Create groups based on access roles rather than organizational structure:

GH-Role-Admin          --> GitHub Enterprise Owners
GH-Role-Maintainer --> Repository maintainers
GH-Role-Developer --> Standard developers (write access)
GH-Role-ReadOnly --> Auditors and stakeholders (read access)
GH-Role-Contractor --> External contractors (limited access)

Pattern 3: Hybrid (Recommended for Large Enterprises)

Combine organizational and role-based groups:

# Organizational teams (control team membership)
GH-Team-Platform
GH-Team-Product
GH-Team-Data

# Role groups (control access level)
GH-Role-Admin
GH-Role-Developer

# Project-specific (temporary, for cross-functional work)
GH-Project-MigrationV2
GH-Project-SecurityAudit

Enterprise Scenario: A 200-developer company initially creates one Entra ID group per developer team (8 groups). As the organization grows, they add project-based groups for cross-functional initiatives, reaching 25 groups within a year. To maintain manageability, they adopt a naming convention (GH-Team-* for permanent teams, GH-Project-* for time-bound projects) and implement a quarterly review process to remove stale project groups. This prevents group sprawl while maintaining the flexibility needed for dynamic project assignments.

Team Sync for Organization-Level SCIM​

For enterprises using personal accounts with SAML SSO, team synchronization is the mechanism that maps Entra ID groups to GitHub teams. Team sync is configured separately from SCIM user provisioning.

How team sync works:

  1. An Entra ID security group is connected to a GitHub team
  2. When a user is added to the Entra ID group, they are automatically added to the corresponding GitHub team
  3. When a user is removed from the Entra ID group, they are automatically removed from the GitHub team
  4. Team sync runs periodically (not in real time) and reconciles membership differences

Requirements for team sync:

  • SAML SSO must be enabled and enforced for the organization
  • The user must have a linked SAML identity (they must have authenticated via SAML at least once)
  • The GitHub organization must be connected to the Entra ID tenant
  • An organization owner must authorize the team sync OAuth application

Group Provisioning for EMU​

For EMU enterprises, group provisioning is native to the SCIM integration. When you assign an Entra ID group to the GitHub EMU application and configure group mappings in the provisioning settings, the SCIM service:

  1. Creates a corresponding GitHub team in the enterprise's default organization
  2. Adds all group members as team members
  3. Continuously synchronizes membership changes (approximately every 40 minutes)
  4. Removes the GitHub team if the Entra ID group is unassigned from the application

User Lifecycle Management​

SCIM provisioning automates the three critical phases of the user lifecycle: onboarding, role changes, and offboarding. Understanding how each phase works helps administrators design processes that minimize manual intervention.

Phase 1: Onboarding​

Trigger: A user is assigned to the GitHub application in Entra ID (either directly or via group membership).

Organization-Level SCIM (Personal Accounts):

  1. Entra provisioning service sends a POST /Users request to GitHub's SCIM endpoint
  2. GitHub sends an email invitation to the user's mapped email address
  3. The user must accept the invitation and link their personal GitHub account
  4. The user authenticates via SAML SSO to complete the linking process
  5. The user appears as a member of the organization

Enterprise-Level SCIM (EMU):

  1. Entra provisioning service sends a POST /Users request to GitHub's SCIM endpoint
  2. GitHub creates a new managed user account with the username {userName}_{enterprise-shortcode}
  3. No invitation is required; the account is created and immediately usable
  4. The user signs in through the IdP (SAML or OIDC) using their corporate credentials
  5. If the user is also a member of provisioned groups, their team memberships are set automatically

Typical onboarding timeline for a new developer (EMU):

StepTimingActor
HR creates user in Active Directory / Entra IDDay 0HR / IT
User is assigned to GitHub EMU app (via group)Day 0 (automated via dynamic group or manual)IT Admin / Automation
SCIM provisioning cycle creates GitHub accountWithin 40 minutesAutomated
User's team memberships are provisionedWithin 40 minutesAutomated
Developer signs in to GitHub for the first timeDay 1Developer

Phase 2: Role Changes and Team Transfers​

Trigger: A user's group membership changes in Entra ID, or their attributes are updated.

Scenarios and SCIM behavior:

ScenarioEntra ID ActionSCIM Effect on GitHub
Developer moves teamsRemove from old group, add to new groupRemove from old GitHub team, add to new team
Developer promoted to team leadAdd to admin group in Entra IDRole updated (if role mapping is configured)
Developer name changeUpdate displayName, givenName, surnameProfile name updated on GitHub
Developer email changeUpdate mail attributeWork email updated on GitHub
Contractor converts to employeeUpdate group membership, remove contractor groupTeam membership updated, access adjusted

Important consideration for role changes: The provisioning cycle runs approximately every 40 minutes. During the window between a role change in Entra ID and the next SCIM sync, the user retains their previous access. For changes that must take effect immediately, administrators can trigger an on-demand provisioning cycle in the Entra admin center.

Phase 3: Offboarding​

Trigger: A user is removed from the GitHub application assignment in Entra ID (directly or by removing them from an assigned group), or the user's account is deleted or soft-deleted in Entra ID.

Organization-Level SCIM (Personal Accounts):

  1. Entra provisioning service sends a PATCH /Users/{id} request setting active to false, or a DELETE /Users/{id} request
  2. GitHub removes the user from the organization
  3. The user's personal GitHub account continues to exist
  4. The user loses access to all organization repositories
  5. Contributions (commits, issues, pull requests) are preserved and attributed to the user's personal account

Enterprise-Level SCIM (EMU):

  1. Entra provisioning service sends a PATCH /Users/{id} request setting active to false
  2. GitHub suspends the managed user account
  3. The suspended account cannot sign in or access any enterprise resources
  4. All contributions are preserved and attributed to the suspended account
  5. If the user is later re-assigned in Entra ID, SCIM reactivates the account by setting active to true

Enterprise Scenario: A 300-developer enterprise terminates a developer with access to sensitive repositories. With SCIM provisioning, the IT team disables the user in Entra ID as part of the standard HR offboarding process. Within 40 minutes, the SCIM provisioning cycle suspends the user's EMU account. Combined with OIDC conditional access (see Chapter 2: Identity & Single Sign-On), the user's active GitHub sessions are also invalidated at the next token refresh, which can occur within minutes. No manual GitHub administration is required.

Provisioning Scopes and Filters​

The Microsoft Entra provisioning service allows you to control which users are in scope for provisioning. This is important for phased rollouts and for excluding service accounts or non-developer users from GitHub provisioning.

Scope options:

  1. Sync only assigned users and groups (recommended): Only users and groups explicitly assigned to the GitHub application in Entra ID are provisioned. This gives you precise control over who gets a GitHub account.

  2. Sync all users and groups: All users in the Entra ID tenant are provisioned. This is rarely appropriate for GitHub, as most organizations do not want every employee to have a GitHub account.

Scoping filters: For more granular control, you can define scoping filters based on user attributes. For example:

  • Provision only users in the "Engineering" department: department EQUALS "Engineering"
  • Provision only users with a specific job title prefix: jobTitle STARTS WITH "Software"
  • Exclude users with a specific attribute: extensionAttribute1 NOT EQUALS "NoGitHub"

Enterprise Scenario: A 1,000-employee company has 200 developers who need GitHub access. Rather than assigning each developer individually, they create an Entra ID dynamic group with the rule (user.department -eq "Engineering") -or (user.department -eq "DevOps") -or (user.department -eq "QA"). This dynamic group is assigned to the GitHub EMU application. When a new developer joins any of these departments, they are automatically added to the dynamic group, which triggers SCIM provisioning of their GitHub account.

Troubleshooting SCIM Provisioning Failures​

Provisioning failures are inevitable at scale. Understanding the common failure modes and their resolution strategies is essential for maintaining a reliable identity pipeline.

Common Failure Categories​

1. Authentication and Authorization Failures

ErrorCauseResolution
401 UnauthorizedPAT expired or revoked (EMU)Generate a new PAT with scim:enterprise scope from the setup user account
403 ForbiddenOAuth authorization revoked (org-level)Re-authorize the OAuth app in GitHub organization settings
403 ForbiddenPAT lacks required scopeEnsure the PAT has the scim:enterprise scope
Test Connection failsIncorrect Tenant URLVerify the URL matches the pattern exactly: https://api.github.com/scim/v2/organizations/<org> or https://api.github.com/scim/v2/enterprises/<enterprise>

2. Attribute Mapping and Matching Failures

ErrorCauseResolution
Duplicate user createdMatching attribute (externalId) not mapped correctlyVerify externalId maps to a stable, unique Entra ID attribute (e.g., objectId or mailNickname)
User not found for updateMatching attribute value changed in Entra IDDo not change the source attribute for externalId after initial provisioning
400 Bad Request on user creationRequired attribute missing or malformedCheck that userName, externalId, and active are all mapped and have valid values
Email conflictThe provisioned email already exists on another GitHub accountEnsure the mapped email is unique across all GitHub accounts in the organization/enterprise

3. Group and Team Provisioning Failures

ErrorCauseResolution
Group not provisionedGroup mappings disabled in provisioning settingsEnable "Synchronize Microsoft Entra groups to GitHub" in the Mappings section
Team created but emptyGroup members not assigned to the applicationEnsure group members are also in scope for user provisioning
Team name conflictA GitHub team with the same displayName already existsRename either the Entra ID group or the existing GitHub team

4. Rate Limiting and Service Errors

ErrorCauseResolution
429 Too Many RequestsProvisioning cycle exceeds GitHub API rate limitsReduce the number of users in scope or stagger provisioning with scoping filters
500 Internal Server ErrorTransient GitHub API errorUsually resolves on the next provisioning cycle; monitor for recurrence
Provisioning quarantinedToo many consecutive failures (threshold is typically 40%+)Review and fix the root cause, then restart provisioning

Using Entra ID Provisioning Logs​

The provisioning logs in Microsoft Entra ID are the primary diagnostic tool for SCIM troubleshooting. To access them:

  1. Navigate to Entra ID > Enterprise applications > (your GitHub app) > Provisioning > Provisioning logs
  2. Filter by:
    • Status: Failed, Skipped, or Success
    • Action: Create, Update, Delete, Disable, or Other
    • Date range: Focus on the period when the issue occurred
    • Identity: Search by the affected user's name or email

Each log entry includes:

  • Source System Details: The Entra ID user attributes sent in the SCIM request
  • Target System Details: The GitHub response, including any error messages
  • Modified Properties: Which attributes were created or changed
  • Provisioning Steps: A step-by-step breakdown of what the provisioning service attempted and where it failed

Using GitHub Audit Logs​

GitHub audit logs capture SCIM events on the GitHub side. Enterprise owners can view these at:

  • Enterprise > Settings > Audit log
  • Filter by the external_identity or org.update_member action categories
# Query SCIM-related audit log events using the GitHub CLI
gh api /enterprises/{enterprise}/audit-log \
--method GET \
-f phrase='action:external_identity' \
-f per_page=20 \
--jq '.[] | {action: .action, actor: .actor, user: .user, created_at: .created_at}'

Provisioning Quarantine​

When the Entra ID provisioning service encounters a high error rate (typically over 40% of operations failing), it enters "quarantine" mode. In quarantine:

  • The provisioning cycle interval increases from 40 minutes to once per day
  • An email notification is sent to the configured notification address
  • Provisioning continues but at a reduced frequency

To recover from quarantine:

  1. Review the provisioning logs to identify the root cause
  2. Fix the underlying issue (expired token, incorrect mapping, etc.)
  3. Navigate to Provisioning > Restart provisioning to clear the quarantine and resume normal operations

3. Diagrams​

SCIM Provisioning Flow: Entra ID to GitHub Enterprise Cloud​

sequenceDiagram
participant Admin as IT Admin
participant Entra as Microsoft Entra ID
participant SCIM as Entra Provisioning Service
participant GH as GitHub Enterprise Cloud

Admin->>Entra: 1. Assign user/group to GitHub app
Entra->>SCIM: 2. Detect change in provisioning scope
SCIM->>GH: 3. GET /Users?filter=externalId eq "abc123"
GH-->>SCIM: 4. No matching user found (empty result)
SCIM->>GH: 5. POST /Users (create new account)
GH-->>SCIM: 6. 201 Created (return user with GitHub ID)
SCIM->>Entra: 7. Record success in provisioning logs
Note over SCIM,GH: ~40 minutes later: incremental sync cycle
SCIM->>GH: 8. GET /Users (detect changes)
GH-->>SCIM: 9. Return current user state
SCIM->>SCIM: 10. Compare with Entra ID attributes
SCIM->>GH: 11. PATCH /Users/{id} (if changes detected)

Figure 1: The SCIM provisioning flow from Microsoft Entra ID to GitHub Enterprise Cloud. The provisioning service first checks for an existing user (step 3), creates the account if not found (step 5), and then continuously synchronizes attribute changes on subsequent cycles (steps 8-11).

User Lifecycle Across Entra ID and GitHub​

stateDiagram-v2
[*] --> AssignedInEntra: User added to GitHub app
AssignedInEntra --> Provisioning: SCIM sync cycle
Provisioning --> ActiveOnGitHub: Account created / invitation sent
ActiveOnGitHub --> TeamMembershipUpdated: Group membership changed
TeamMembershipUpdated --> ActiveOnGitHub: Sync complete
ActiveOnGitHub --> AttributesUpdated: Name, email, or role changed
AttributesUpdated --> ActiveOnGitHub: Sync complete
ActiveOnGitHub --> Suspended: User removed from app / disabled in Entra ID
Suspended --> ActiveOnGitHub: User re-assigned to app
Suspended --> [*]: Account deleted (EMU) or org membership removed

Figure 2: The complete user lifecycle as managed by SCIM provisioning. Users flow from assignment in Entra ID through provisioning to active status on GitHub. Team and attribute changes are handled as in-place updates. Offboarding suspends the account, with the option to reactivate if the user returns.

Group-to-Team Mapping Architecture​

graph LR
subgraph "Microsoft Entra ID"
G1[GH-Team-Platform<br/>Security Group]
G2[GH-Team-Product<br/>Security Group]
G3[GH-Team-Data<br/>Security Group]
G4[GH-Role-Admin<br/>Security Group]
end

subgraph "SCIM Provisioning Service"
S[Attribute Mapping<br/>& Sync Engine]
end

subgraph "GitHub Enterprise Cloud"
T1[platform<br/>GitHub Team]
T2[product<br/>GitHub Team]
T3[data-engineering<br/>GitHub Team]
T4[enterprise-admins<br/>GitHub Team]
R1[platform-api repo]
R2[mobile-app repo]
R3[data-pipeline repo]
end

G1 --> S
G2 --> S
G3 --> S
G4 --> S
S --> T1
S --> T2
S --> T3
S --> T4
T1 -- write access --> R1
T2 -- write access --> R2
T3 -- write access --> R3

style S fill:#2d333b,stroke:#539bf5,color:#adbac7

Figure 3: Group-to-team mapping architecture. Entra ID security groups are mapped through the SCIM provisioning service to GitHub teams. Repository access is then granted to teams, creating a chain from IdP group membership to repository permissions. Changing a developer's Entra ID group membership automatically adjusts their repository access.

Troubleshooting Decision Tree​

flowchart TD
A[SCIM provisioning<br/>failure detected] --> B{Check provisioning<br/>logs in Entra ID}
B --> C{Error type?}
C -- "401/403<br/>Authentication" --> D[Verify PAT or<br/>OAuth authorization]
C -- "400 Bad<br/>Request" --> E[Check attribute<br/>mappings]
C -- "409 Conflict /<br/>Duplicate" --> F[Verify externalId<br/>matching property]
C -- "429 Rate<br/>Limited" --> G[Reduce scope or<br/>stagger provisioning]
C -- "500 Server<br/>Error" --> H{Retry on<br/>next cycle?}
D --> D1[Regenerate PAT or<br/>re-authorize OAuth app]
E --> E1[Fix missing or<br/>malformed attributes]
F --> F1[Reconcile duplicate<br/>accounts manually]
H -- "Resolves" --> I[No action needed]
H -- "Persists" --> J[Check GitHub<br/>status page & audit logs]

style A fill:#2d333b,stroke:#e5534b,color:#adbac7
style I fill:#2d333b,stroke:#57ab5a,color:#adbac7

Figure 4: Troubleshooting decision tree for SCIM provisioning failures. Start with the Entra ID provisioning logs to identify the error type, then follow the corresponding resolution path.


4. Summary​

Key Takeaways:

  • SCIM (System for Cross-domain Identity Management) provisioning automates user lifecycle management between Microsoft Entra ID and GitHub Enterprise Cloud, eliminating manual account creation, team assignment, and offboarding tasks
  • Two provisioning models exist: organization-level SCIM (for personal accounts with SAML SSO) manages organization membership via invitations, while enterprise-level SCIM (for Enterprise Managed Users) creates and fully controls user accounts
  • The SCIM Tenant URL differs by model: https://api.github.com/scim/v2/organizations/<org> for organization-level, and https://api.github.com/scim/v2/enterprises/<enterprise> for EMU
  • Group-to-team mapping enables centralized access control: Entra ID security groups synchronize to GitHub teams, and repository permissions assigned to those teams apply automatically to group members
  • The externalId attribute is the critical matching property that links Entra ID users to their GitHub accounts; misconfiguring this mapping causes duplicate accounts or failed updates
  • The provisioning service runs incremental synchronization cycles approximately every 40 minutes; the initial synchronization takes longer and covers all users and groups in scope
  • Offboarding through SCIM suspends EMU accounts (preserving contributions) or removes organization membership (for personal accounts); no manual GitHub administration is required
  • Provisioning quarantine activates when the failure rate exceeds approximately 40%, reducing sync frequency to once per day until the root cause is resolved

What's Next: See Chapter 4: Copilot Licensing for configuring GitHub Copilot seat assignments and understanding how provisioned users relate to Copilot license allocation.


5. Hands-On Assignment​

Prerequisites Check: Before starting this lab, ensure you have completed:

  • A working GitHub Enterprise Cloud environment (Chapter 1: Enterprise Subscription & Environment Setup)
  • SAML SSO configured with Microsoft Entra ID (Chapter 2: Identity & Single Sign-On)
  • A Microsoft Entra ID tenant with Cloud Application Administrator role
  • At least two test user accounts in Entra ID

Lab: Configure SCIM Provisioning and Group-to-Team Mapping​

Objective: Configure SCIM provisioning between Microsoft Entra ID and your GitHub Enterprise Cloud environment, create Entra ID security groups mapped to GitHub teams, provision test users, and verify the complete onboarding and offboarding lifecycle.

Prerequisites:

  • A GitHub Enterprise Cloud trial with SAML SSO configured (completed in See Chapter 1: Enterprise Subscription & Environment Setup and See Chapter 2: Identity & Single Sign-On)
  • A Microsoft Entra ID tenant with Cloud Application Administrator (or higher) role
  • At least two test user accounts in Entra ID
  • For EMU: the enterprise setup user credentials and a PAT with scim:enterprise scope
  • For org-level SCIM: organization owner role and GitHub admin permissions
  • GitHub CLI (gh) installed (version 2.40 or later)

Assignment Tasks:

  1. Configure SCIM provisioning in the Microsoft Entra admin center for your GitHub application:

    • Set the provisioning mode to Automatic
    • Enter the correct Tenant URL for your provisioning model (organization-level or enterprise-level)
    • Provide the authorization credentials (OAuth or PAT)
    • Test the connection
  2. Configure attribute mappings for users:

    • Verify externalId maps to a stable identifier (objectId or mailNickname)
    • Verify userName maps to userPrincipalName
    • Verify the active attribute uses the correct expression for soft-delete mapping
  3. Create two Entra ID security groups for GitHub team mapping:

    • GH-Team-Alpha with one test user assigned
    • GH-Team-Beta with the other test user assigned
  4. Assign both groups to the GitHub application in Entra ID and enable group provisioning

  5. Trigger an initial provisioning cycle and monitor the provisioning logs

  6. Verify on GitHub:

    • Both test users have been provisioned (accounts created for EMU, or invitations sent for org-level)
    • Two GitHub teams exist corresponding to the Entra ID groups
    • Each user is a member of the correct team
  7. Test a lifecycle change:

    • Move one test user from GH-Team-Alpha to GH-Team-Beta in Entra ID
    • Wait for the next provisioning cycle (or trigger on-demand provisioning)
    • Verify the user's GitHub team membership has updated
  8. Test offboarding:

    • Remove one test user from all GitHub-assigned groups in Entra ID (or unassign them from the application)
    • Verify the user's GitHub account is suspended (EMU) or removed from the organization

Expected Outcome: A working SCIM provisioning integration where user accounts and team memberships in GitHub are automatically managed based on Entra ID assignments. Lifecycle changes (team transfers and offboarding) propagate to GitHub within a provisioning cycle.

Validation Checklist:

  • Entra ID provisioning logs show successful user creation events
  • GitHub team membership matches Entra ID group membership
  • Team transfer correctly updates GitHub team assignment
  • Offboarding results in account suspension (EMU) or organization removal (org-level)

6. Step-by-Step Walkthrough​

This section provides a guided solution for the hands-on assignment above. If you completed the assignment independently, you can skip this section or use it to verify your approach.

The walkthrough below demonstrates the EMU enterprise-level provisioning flow. For organization-level SCIM, the steps are similar but use the organization-specific Tenant URL and OAuth authorization instead of a PAT.

Step 1: Generate a Personal Access Token (EMU Only)​

  1. Sign in to GitHub as the enterprise setup user (the account created when the EMU enterprise was established, typically named {shortcode}_admin)
  2. Navigate to Settings > Developer settings > Personal access tokens > Tokens (classic)
  3. Click Generate new token (classic)
  4. Set the following:
    • Note: SCIM Provisioning - Entra ID
    • Expiration: Choose an appropriate expiration (90 days recommended; set a calendar reminder to rotate)
    • Scopes: Select admin:enterprise > scim:enterprise
  5. Click Generate token and copy the token value immediately (it will not be shown again)
# Verify the token works by querying the SCIM endpoint
curl -H "Authorization: Bearer ghp_YOUR_TOKEN_HERE" \
-H "Accept: application/scim+json" \
"https://api.github.com/scim/v2/enterprises/YOUR-ENTERPRISE/Users" \
| jq '.totalResults'

Step 2: Configure Provisioning in Microsoft Entra ID​

  1. Sign in to the Microsoft Entra admin center as a Cloud Application Administrator
  2. Navigate to Entra ID > Enterprise applications
  3. Select your GitHub EMU application (or add GitHub Enterprise Managed User from the gallery if not yet added)
  4. Select the Provisioning tab
  5. Click Get started
  6. Set Provisioning Mode to Automatic

Step 3: Enter Admin Credentials​

  1. In the Admin Credentials section:
    • Tenant URL: https://api.github.com/scim/v2/enterprises/YOUR-ENTERPRISE (Replace YOUR-ENTERPRISE with your enterprise slug)
    • Secret Token: Paste the PAT generated in Step 1
  2. Click Test Connection
  3. Verify the success message: "The supplied credentials are authorized to enable provisioning"
  4. Click Save

If the test connection fails:

  • Verify the Tenant URL has no trailing slash
  • Verify the enterprise slug is correct (check at https://github.com/enterprises/YOUR-ENTERPRISE)
  • Verify the PAT has the scim:enterprise scope
  • Verify the PAT was generated by the setup user account

Step 4: Configure User Attribute Mappings​

  1. Under Mappings, click Synchronize Microsoft Entra users to GitHub Enterprise Managed User
  2. Review the default attribute mappings. Ensure the following are configured:
Microsoft Entra AttributeGitHub AttributeMatching Precedence
objectIdexternalId1
userPrincipalNameuserName--
Switch([IsSoftDeleted], , "False", "True", "True", "False")active--
displayNamedisplayName--
givenNamename.givenName--
surnamename.familyName--
mailemails[type eq "work"].value--
  1. Verify that only externalId has a Matching precedence value. Do not set matching on other attributes.
  2. Click Save

Step 5: Configure Group Attribute Mappings​

  1. Under Mappings, click Synchronize Microsoft Entra groups to GitHub Enterprise Managed User
  2. Ensure the mapping is Enabled
  3. Verify the following attribute mappings:
Microsoft Entra AttributeGitHub AttributeMatching Precedence
objectIdexternalId1
displayNamedisplayName--
membersmembers--
  1. Click Save

Step 6: Create Security Groups in Entra ID​

  1. Navigate to Entra ID > Groups > New group
  2. Create the first group:
    • Group type: Security
    • Group name: GH-Team-Alpha
    • Group description: GitHub team - Alpha squad
    • Membership type: Assigned (or Dynamic if using attribute-based rules)
    • Add Test User A as a member
    • Click Create
  3. Repeat for the second group:
    • Group name: GH-Team-Beta
    • Add Test User B as a member
    • Click Create
# Verify groups were created using Azure CLI (optional)
az ad group list --display-name "GH-Team" --query "[].{Name:displayName, Id:id}" --output table

Step 7: Assign Users and Groups to the GitHub Application​

  1. Navigate to Enterprise applications > (your GitHub EMU app) > Users and groups
  2. Click Add user/group
  3. Under Users and groups, select both GH-Team-Alpha and GH-Team-Beta security groups
  4. Click Assign

Note: By assigning the groups, all members of those groups are automatically in scope for provisioning.

Step 8: Set Provisioning Scope and Start Provisioning​

  1. Navigate to the Provisioning tab
  2. Under Settings:
    • Scope: Select Sync only assigned users and groups
    • Notification Email: Enter your admin email address
    • Check Send an email notification when a failure occurs
  3. Click Save
  4. Click Start provisioning (or Restart provisioning if it was previously started)

Step 9: Monitor the Initial Synchronization​

  1. Navigate to Provisioning > Provisioning logs
  2. Wait for the initial sync to begin (this may take a few minutes)
  3. Monitor the logs for:
    • Action: Create events for both test users
    • Action: Create events for both groups
    • Status: Success for all events
# On the GitHub side, verify provisioned users (EMU)
gh api /enterprises/YOUR-ENTERPRISE/members --jq '.[].login'

# Verify teams were created
gh api /orgs/YOUR-ORG/teams --jq '.[].name'

# Verify team membership
gh api /orgs/YOUR-ORG/teams/gh-team-alpha/members --jq '.[].login'
gh api /orgs/YOUR-ORG/teams/gh-team-beta/members --jq '.[].login'

Step 10: Test a Lifecycle Change (Team Transfer)​

  1. In the Entra admin center, navigate to Entra ID > Groups > GH-Team-Alpha
  2. Under Members, remove Test User A
  3. Navigate to GH-Team-Beta > Members > Add members > add Test User A
  4. Return to the GitHub EMU app > Provisioning and click Provision on demand
  5. Search for Test User A and click Provision
  6. Verify the provisioning steps show a successful group membership update

Alternatively, wait for the next automatic provisioning cycle (approximately 40 minutes) and verify:

# Test User A should now be in GH-Team-Beta, not GH-Team-Alpha
gh api /orgs/YOUR-ORG/teams/gh-team-alpha/members --jq '.[].login'
gh api /orgs/YOUR-ORG/teams/gh-team-beta/members --jq '.[].login'

Step 11: Test Offboarding​

  1. In the Entra admin center, navigate to the GitHub EMU application > Users and groups
  2. Remove Test User B from all assigned groups (or unassign them from the application directly)
  3. Trigger on-demand provisioning for Test User B, or wait for the next sync cycle
  4. Verify the provisioning logs show a Disable action with Status: Success
# Verify the user is suspended on GitHub (EMU)
# Suspended users will not appear in the active members list
gh api /enterprises/YOUR-ENTERPRISE/members --jq '.[].login'

# Check the audit log for the suspension event
gh api /enterprises/YOUR-ENTERPRISE/audit-log \
--method GET \
-f phrase='action:external_identity.deprovision' \
-f per_page=5 \
--jq '.[] | {action: .action, user: .user, created_at: .created_at}'

Verification​

Confirm the full provisioning lifecycle by reviewing:

  1. Entra ID Provisioning logs: All Create, Update, and Disable actions show Status: Success
  2. GitHub team membership: Matches the current Entra ID group assignments
  3. Offboarded user: Account is suspended (EMU) or removed from the organization
  4. Audit trail: Both Entra ID provisioning logs and GitHub audit logs contain corresponding events for all lifecycle actions
# Final verification: list all teams and their members
for team in $(gh api /orgs/YOUR-ORG/teams --jq '.[].slug'); do
echo "Team: $team"
gh api "/orgs/YOUR-ORG/teams/$team/members" --jq '.[].login'
echo "---"
done

7. Q&A -- Chapter Review​

Instructions: Select the best answer for each question. Answers and explanations follow after all questions.

Question 1​

A 150-developer enterprise uses Enterprise Managed Users (EMU) with Microsoft Entra ID. A new developer joins the Platform team. What is the correct process to provision their GitHub account and team membership?

  • A) Create a GitHub account manually, then add them to the Platform team in GitHub
  • B) Assign the developer to the GitHub EMU application in Entra ID and add them to the Entra ID security group mapped to the Platform team
  • C) Send the developer a GitHub invitation link and ask them to create a personal account
  • D) Use the GitHub CLI to create a managed user account and assign team membership

Question 2​

What is the SCIM Tenant URL format for provisioning users to an Enterprise Managed Users enterprise on github.com?

  • A) https://github.com/scim/v2/enterprises/{enterprise}
  • B) https://api.github.com/scim/v2/enterprises/{enterprise}
  • C) https://api.github.com/v3/scim/enterprises/{enterprise}
  • D) https://scim.github.com/v2/enterprises/{enterprise}

Question 3​

An IT administrator notices that a user who was removed from Entra ID two hours ago still appears as an active member in the GitHub organization. What is the most likely explanation?

  • A) SCIM provisioning is not configured for the organization
  • B) The SCIM provisioning cycle has not yet run since the removal, and the service is operating within its normal ~40-minute interval
  • C) GitHub does not support automated deprovisioning
  • D) The user's GitHub account is a personal account and cannot be removed by SCIM

Question 4​

Which attribute serves as the primary matching property that links a Microsoft Entra ID user to their corresponding GitHub account during SCIM provisioning?

  • A) userName
  • B) displayName
  • C) externalId
  • D) emails[type eq "work"].value

Question 5​

An enterprise uses organization-level SCIM provisioning with personal GitHub accounts. When a developer is deprovisioned through SCIM, what happens to their GitHub account?

  • A) The personal GitHub account is permanently deleted
  • B) The personal GitHub account is suspended and cannot be used
  • C) The developer is removed from the organization but their personal GitHub account continues to exist
  • D) The personal GitHub account is converted to a free account with no organization access

Question 6​

A company with 200 developers wants to implement SCIM group-to-team mapping. They have 12 engineering teams that change quarterly and 3 cross-functional project groups that change monthly. Which group naming strategy best supports this?

  • A) Use a single Entra ID group called GH-AllDevelopers and manage team assignments manually in GitHub
  • B) Use Entra ID groups named GH-Team-* for permanent teams and GH-Project-* for temporary project groups, with a quarterly review to remove stale project groups
  • C) Create GitHub teams directly without Entra ID group mapping and manage membership manually
  • D) Use Entra ID dynamic groups based on job title only, ignoring project assignments

Question 7​

The Microsoft Entra provisioning service has entered quarantine mode for the GitHub SCIM integration. Which statement accurately describes the quarantine behavior?

  • A) All provisioning stops immediately and no changes are synchronized until an administrator intervenes
  • B) The provisioning cycle interval increases to once per day, and a notification email is sent to the configured address
  • C) Only new user provisioning is paused; existing user updates continue normally
  • D) The provisioning service automatically retries every 5 minutes with exponential backoff

Question 8​

An EMU enterprise administrator needs to ensure that a terminated employee's GitHub access is revoked as quickly as possible. Which combination of configurations provides the fastest revocation?

  • A) SCIM provisioning with SAML authentication
  • B) SCIM provisioning with OIDC authentication and conditional access policies
  • C) Manual account suspension in GitHub by an enterprise owner
  • D) Revoking the user's SSH keys and Personal Access Tokens in GitHub

Question 9​

When configuring SCIM provisioning for GitHub Enterprise Managed Users, what type of credential is used as the Secret Token in the Entra ID provisioning configuration?

  • A) A Microsoft Entra ID client secret
  • B) A GitHub OAuth application client secret
  • C) A Personal Access Token (PAT) created by the enterprise setup user with the scim:enterprise scope
  • D) A SAML signing certificate converted to a bearer token

Question 10​

A provisioning log entry in Entra ID shows a 400 Bad Request error when attempting to create a user in GitHub. Which of the following is the most likely cause?

  • A) The GitHub API rate limit has been exceeded
  • B) A required SCIM attribute (such as userName or externalId) is missing or has an invalid value in the attribute mapping
  • C) The user already has a personal GitHub account with the same email address
  • D) The Entra ID provisioning service certificate has expired

Answer Key​

QAnswerExplanation
1BIn the EMU model, user accounts and team memberships are managed entirely through the identity provider. Assigning the developer to the GitHub EMU app in Entra ID triggers SCIM to create their managed account, and adding them to the appropriate Entra ID security group provisions their team membership. Manual GitHub administration (options A, C, D) defeats the purpose of SCIM automation. (D2)
2BThe correct Tenant URL for EMU provisioning on github.com is https://api.github.com/scim/v2/enterprises/{enterprise}. This URL is entered in the Tenant URL field in the Provisioning tab of the Entra ID application. The other URL patterns are incorrect and will cause a Test Connection failure. (D2)
3BThe Entra provisioning service runs incremental synchronization cycles approximately every 40 minutes. If the user was removed two hours ago, the provisioning cycle should have run, but delays can occur due to service load or if the provisioning service is in quarantine. The first troubleshooting step is to check the provisioning logs for the deprovisioning event. Option D could also be relevant, but the question states the user "appears as an active member," which SCIM should address for org membership. (D2)
4CThe externalId attribute is the primary matching property in SCIM provisioning. It is typically mapped from objectId or mailNickname in Entra ID and provides a stable, unique identifier that links the Entra ID user to their GitHub account. The provisioning service uses externalId to find the correct GitHub user when performing updates and deprovisioning. (D2)
5CWith organization-level SCIM (personal accounts), deprovisioning removes the user from the GitHub organization but does not affect their personal GitHub account. The account continues to exist and can be used for other organizations or open source contributions. This is a key difference from EMU, where deprovisioning suspends the entire managed account. (D2)
6BA naming convention that distinguishes permanent teams (GH-Team-*) from temporary project groups (GH-Project-*) provides clarity and maintainability. The quarterly review process for project groups prevents group sprawl. Option A sacrifices automated team mapping. Option C abandons centralized management. Option D ignores project-based access needs. (D2)
7BWhen the provisioning service enters quarantine (typically triggered by a failure rate above 40%), the sync interval increases to once per day, and a notification email is sent. Provisioning does not stop entirely. The administrator must identify and fix the root cause, then restart provisioning to exit quarantine and resume the normal ~40-minute cycle. (D2)
8BSCIM provisioning with OIDC authentication provides the fastest revocation. SCIM handles account suspension on the next provisioning cycle, while OIDC conditional access policies can invalidate the user's active sessions at the next token refresh (which can happen within minutes). With SAML only (option A), active sessions persist until the SAML session expires, which could be hours. (D2)
9CFor EMU SCIM provisioning, the Secret Token is a Personal Access Token (PAT) created by the enterprise setup user with the scim:enterprise scope. This PAT authorizes the Entra provisioning service to make SCIM API calls to the GitHub enterprise. The PAT should be rotated before expiration and stored securely. (D2)
10BA 400 Bad Request error during user creation typically indicates that a required SCIM attribute is missing or has an invalid value. Common causes include an unmapped userName or externalId attribute, or an expression that returns null for a required field. The provisioning log entry's "Target System Details" section will contain the specific error message from GitHub's API. Rate limiting would return a 429 error (option A), not a 400. (D2)