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
| Domain | Topics 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 Method | Endpoint | Purpose |
|---|---|---|
POST | /Users | Create 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 | /Groups | Create 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) orhttps://api.{subdomain}.ghe.com/scim/v2/enterprises/{subdomain}(for GHE.com) - Authorization uses a Personal Access Token (PAT) with the
scim:enterprisescope, 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:
| Capability | Organization-Level SCIM | Enterprise-Level SCIM (EMU) |
|---|---|---|
| Account creation | Invitation only | Full account creation |
| Account ownership | User (personal) | Enterprise |
| Deprovisioning effect | Removes from org | Suspends account |
| Scope | Per-organization | Entire enterprise |
| Authorization method | OAuth app | PAT with scim:enterprise |
| SAML/OIDC prerequisite | Org-level SAML required | Enterprise-level SAML/OIDC required |
| Group-to-team mapping | Via team sync | Native 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 Attribute | GitHub SCIM Attribute | Required | Notes |
|---|---|---|---|
mailNickname or objectId | externalId | Yes | Immutable identifier used for matching. externalId is the primary matching attribute and must be unique. |
userPrincipalName | userName | Yes | Becomes the base of the EMU username (with enterprise shortcode appended) |
Switch([IsSoftDeleted], , "False", "True", "True", "False") | active | Yes | Controls whether the account is active or suspended |
displayName | displayName | No | Full display name shown in the GitHub UI |
givenName | name.givenName | No | First name |
surname | name.familyName | No | Last name |
Join(" ", [givenName], [surname]) | name.formatted | No | Formatted full name |
mail | emails[type eq "work"].value | No | Work email address |
For Organization-Level SCIM (Personal Accounts):
| Microsoft Entra Attribute | GitHub SCIM Attribute | Notes |
|---|---|---|
userPrincipalName | userName | Must match an email address on the user's personal GitHub account |
mail | emails[type eq "work"].value | Used for invitation delivery |
givenName | name.givenName | First name |
surname | name.familyName | Last 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 Attribute | GitHub SCIM Attribute | Notes |
|---|---|---|
objectId | externalId | Immutable group identifier |
displayName | displayName | Becomes the GitHub team name |
members | members | List 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:
- An Entra ID security group is connected to a GitHub team
- When a user is added to the Entra ID group, they are automatically added to the corresponding GitHub team
- When a user is removed from the Entra ID group, they are automatically removed from the GitHub team
- 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:
- Creates a corresponding GitHub team in the enterprise's default organization
- Adds all group members as team members
- Continuously synchronizes membership changes (approximately every 40 minutes)
- 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):
- Entra provisioning service sends a
POST /Usersrequest to GitHub's SCIM endpoint - GitHub sends an email invitation to the user's mapped email address
- The user must accept the invitation and link their personal GitHub account
- The user authenticates via SAML SSO to complete the linking process
- The user appears as a member of the organization
Enterprise-Level SCIM (EMU):
- Entra provisioning service sends a
POST /Usersrequest to GitHub's SCIM endpoint - GitHub creates a new managed user account with the username
{userName}_{enterprise-shortcode} - No invitation is required; the account is created and immediately usable
- The user signs in through the IdP (SAML or OIDC) using their corporate credentials
- If the user is also a member of provisioned groups, their team memberships are set automatically
Typical onboarding timeline for a new developer (EMU):
| Step | Timing | Actor |
|---|---|---|
| HR creates user in Active Directory / Entra ID | Day 0 | HR / 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 account | Within 40 minutes | Automated |
| User's team memberships are provisioned | Within 40 minutes | Automated |
| Developer signs in to GitHub for the first time | Day 1 | Developer |
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:
| Scenario | Entra ID Action | SCIM Effect on GitHub |
|---|---|---|
| Developer moves teams | Remove from old group, add to new group | Remove from old GitHub team, add to new team |
| Developer promoted to team lead | Add to admin group in Entra ID | Role updated (if role mapping is configured) |
| Developer name change | Update displayName, givenName, surname | Profile name updated on GitHub |
| Developer email change | Update mail attribute | Work email updated on GitHub |
| Contractor converts to employee | Update group membership, remove contractor group | Team 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):
- Entra provisioning service sends a
PATCH /Users/{id}request settingactivetofalse, or aDELETE /Users/{id}request - GitHub removes the user from the organization
- The user's personal GitHub account continues to exist
- The user loses access to all organization repositories
- Contributions (commits, issues, pull requests) are preserved and attributed to the user's personal account
Enterprise-Level SCIM (EMU):
- Entra provisioning service sends a
PATCH /Users/{id}request settingactivetofalse - GitHub suspends the managed user account
- The suspended account cannot sign in or access any enterprise resources
- All contributions are preserved and attributed to the suspended account
- If the user is later re-assigned in Entra ID, SCIM reactivates the account by setting
activetotrue
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:
-
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.
-
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
| Error | Cause | Resolution |
|---|---|---|
401 Unauthorized | PAT expired or revoked (EMU) | Generate a new PAT with scim:enterprise scope from the setup user account |
403 Forbidden | OAuth authorization revoked (org-level) | Re-authorize the OAuth app in GitHub organization settings |
403 Forbidden | PAT lacks required scope | Ensure the PAT has the scim:enterprise scope |
| Test Connection fails | Incorrect Tenant URL | Verify 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
| Error | Cause | Resolution |
|---|---|---|
| Duplicate user created | Matching attribute (externalId) not mapped correctly | Verify externalId maps to a stable, unique Entra ID attribute (e.g., objectId or mailNickname) |
| User not found for update | Matching attribute value changed in Entra ID | Do not change the source attribute for externalId after initial provisioning |
400 Bad Request on user creation | Required attribute missing or malformed | Check that userName, externalId, and active are all mapped and have valid values |
| Email conflict | The provisioned email already exists on another GitHub account | Ensure the mapped email is unique across all GitHub accounts in the organization/enterprise |
3. Group and Team Provisioning Failures
| Error | Cause | Resolution |
|---|---|---|
| Group not provisioned | Group mappings disabled in provisioning settings | Enable "Synchronize Microsoft Entra groups to GitHub" in the Mappings section |
| Team created but empty | Group members not assigned to the application | Ensure group members are also in scope for user provisioning |
| Team name conflict | A GitHub team with the same displayName already exists | Rename either the Entra ID group or the existing GitHub team |
4. Rate Limiting and Service Errors
| Error | Cause | Resolution |
|---|---|---|
429 Too Many Requests | Provisioning cycle exceeds GitHub API rate limits | Reduce the number of users in scope or stagger provisioning with scoping filters |
500 Internal Server Error | Transient GitHub API error | Usually resolves on the next provisioning cycle; monitor for recurrence |
| Provisioning quarantined | Too 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:
- Navigate to Entra ID > Enterprise applications > (your GitHub app) > Provisioning > Provisioning logs
- 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_identityororg.update_memberaction 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:
- Review the provisioning logs to identify the root cause
- Fix the underlying issue (expired token, incorrect mapping, etc.)
- 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, andhttps://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
externalIdattribute 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:enterprisescope - For org-level SCIM: organization owner role and GitHub admin permissions
- GitHub CLI (
gh) installed (version 2.40 or later)
Assignment Tasks:
-
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
-
Configure attribute mappings for users:
- Verify
externalIdmaps to a stable identifier (objectIdormailNickname) - Verify
userNamemaps touserPrincipalName - Verify the
activeattribute uses the correct expression for soft-delete mapping
- Verify
-
Create two Entra ID security groups for GitHub team mapping:
GH-Team-Alphawith one test user assignedGH-Team-Betawith the other test user assigned
-
Assign both groups to the GitHub application in Entra ID and enable group provisioning
-
Trigger an initial provisioning cycle and monitor the provisioning logs
-
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
-
Test a lifecycle change:
- Move one test user from
GH-Team-AlphatoGH-Team-Betain Entra ID - Wait for the next provisioning cycle (or trigger on-demand provisioning)
- Verify the user's GitHub team membership has updated
- Move one test user from
-
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)
- Sign in to GitHub as the enterprise setup user (the account created when the EMU enterprise was established, typically named
{shortcode}_admin) - Navigate to Settings > Developer settings > Personal access tokens > Tokens (classic)
- Click Generate new token (classic)
- 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
- Note:
- 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
- Sign in to the Microsoft Entra admin center as a Cloud Application Administrator
- Navigate to Entra ID > Enterprise applications
- Select your GitHub EMU application (or add GitHub Enterprise Managed User from the gallery if not yet added)
- Select the Provisioning tab
- Click Get started
- Set Provisioning Mode to Automatic
Step 3: Enter Admin Credentials
- In the Admin Credentials section:
- Tenant URL:
https://api.github.com/scim/v2/enterprises/YOUR-ENTERPRISE(ReplaceYOUR-ENTERPRISEwith your enterprise slug) - Secret Token: Paste the PAT generated in Step 1
- Tenant URL:
- Click Test Connection
- Verify the success message: "The supplied credentials are authorized to enable provisioning"
- 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:enterprisescope - Verify the PAT was generated by the setup user account
Step 4: Configure User Attribute Mappings
- Under Mappings, click Synchronize Microsoft Entra users to GitHub Enterprise Managed User
- Review the default attribute mappings. Ensure the following are configured:
| Microsoft Entra Attribute | GitHub Attribute | Matching Precedence |
|---|---|---|
objectId | externalId | 1 |
userPrincipalName | userName | -- |
Switch([IsSoftDeleted], , "False", "True", "True", "False") | active | -- |
displayName | displayName | -- |
givenName | name.givenName | -- |
surname | name.familyName | -- |
mail | emails[type eq "work"].value | -- |
- Verify that only
externalIdhas a Matching precedence value. Do not set matching on other attributes. - Click Save
Step 5: Configure Group Attribute Mappings
- Under Mappings, click Synchronize Microsoft Entra groups to GitHub Enterprise Managed User
- Ensure the mapping is Enabled
- Verify the following attribute mappings:
| Microsoft Entra Attribute | GitHub Attribute | Matching Precedence |
|---|---|---|
objectId | externalId | 1 |
displayName | displayName | -- |
members | members | -- |
- Click Save
Step 6: Create Security Groups in Entra ID
- Navigate to Entra ID > Groups > New group
- 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
- Repeat for the second group:
- Group name:
GH-Team-Beta - Add Test User B as a member
- Click Create
- Group name:
# 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
- Navigate to Enterprise applications > (your GitHub EMU app) > Users and groups
- Click Add user/group
- Under Users and groups, select both
GH-Team-AlphaandGH-Team-Betasecurity groups - 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
- Navigate to the Provisioning tab
- 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
- Click Save
- Click Start provisioning (or Restart provisioning if it was previously started)
Step 9: Monitor the Initial Synchronization
- Navigate to Provisioning > Provisioning logs
- Wait for the initial sync to begin (this may take a few minutes)
- 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)
- In the Entra admin center, navigate to Entra ID > Groups > GH-Team-Alpha
- Under Members, remove Test User A
- Navigate to GH-Team-Beta > Members > Add members > add Test User A
- Return to the GitHub EMU app > Provisioning and click Provision on demand
- Search for Test User A and click Provision
- 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
- In the Entra admin center, navigate to the GitHub EMU application > Users and groups
- Remove Test User B from all assigned groups (or unassign them from the application directly)
- Trigger on-demand provisioning for Test User B, or wait for the next sync cycle
- 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:
- Entra ID Provisioning logs: All Create, Update, and Disable actions show Status: Success
- GitHub team membership: Matches the current Entra ID group assignments
- Offboarded user: Account is suspended (EMU) or removed from the organization
- 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-AllDevelopersand manage team assignments manually in GitHub - B) Use Entra ID groups named
GH-Team-*for permanent teams andGH-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:enterprisescope - 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
userNameorexternalId) 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
| Q | Answer | Explanation |
|---|---|---|
| 1 | B | In 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) |
| 2 | B | The 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) |
| 3 | B | The 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) |
| 4 | C | The 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) |
| 5 | C | With 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) |
| 6 | B | A 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) |
| 7 | B | When 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) |
| 8 | B | SCIM 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) |
| 9 | C | For 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) |
| 10 | B | A 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) |