Troubleshooting team membership with identity provider groups

About management of team membership with IdP groups

With Enterprise Managed Users, you can manage team and organization membership within your enterprise through your IdP by connecting teams on GitHub with groups on your IdP. You can review a list of teams that you've synchronized to IdP groups from your enterprise's settings. For more information, see Managing team memberships with identity provider groups.

GitHub also runs a reconciliation job once per day, which synchronizes team membership with IdP group membership that is stored on GitHub, based on information previously sent from the IdP via SCIM. If this job finds that a user is a member of an IdP group in the enterprise, but they are not a member of the mapped team or its organization, the job will attempt to add the user to the organization and team.

If GitHub is unable to synchronize team membership with a group on your IdP, you can view an error message and troubleshoot the problem.

Viewing errors for team synchronization with an IdP group

1. Navigate to your enterprise. For example, from the Enterprises page on GitHub.com.

2. In the list of enterprises, click the enterprise you want to view.

3. To review a list of IdP groups, in the left sidebar, click Identity provider.

4. Under Identity provider, click Groups.

5. If synchronization for a group is experiencing problems, you'll see a message that reads "Some groups are failing to synchronize to teams. Check that you have available licenses."

6. In the list of IdP groups, click the group you'd like to review.

7. To review the synchronization error for the group, under the name of the group, click Teams.

   If a team is unable to sync membership with a group on your IdP, you'll see a description of the problem under the team's name and membership count.

Error: "Out of sync due to insufficient licenses"

GitHub stores IdP group membership data for Enterprise Managed Users at the enterprise level. This data is populated and updated through Group SCIM API calls from your identity provider (IdP).

For IdP groups that are mapped to teams, GitHub runs a daily reconciliation job to synchronize team membership with the stored enterprise-level IdP group data. The reconciliation also runs whenever a Group SCIM API call updates group membership, or when an admin links or unlinks a team to a stored group on GitHub.

If your enterprise does not have enough licenses available, GitHub may be unable to complete this synchronization. When this occurs, you’ll see the message:

"Out of sync due to insufficient licenses"

As a result, the affected team or organization may be missing members.

To investigate this issue, review your enterprise's total available licenses, as well as detailed information about which users are consuming licenses and why. For more information, see People who consume a license in an organization and Viewing usage for your GitHub Enterprise plan.

Resolving the issue

To allow synchronization to complete successfully, make additional enterprise licenses available using one of the following approaches:

• Free up existing licenses

  • Identify which users are consuming licenses and whether they still need access.
  • Remove users from organizations or IdP groups as needed, depending on how you manage organization and team membership (see Viewing people in your enterprise):
    • If you manage your organization's membership via IdP groups, remove users from the relevant group(s).
  • Monitor these enterprise audit log events to track SCIM API calls that update group membership or managed user accounts (see Audit log events for your enterprise:
    • external_group.scim_api_failure / external_group.scim_api_success
    • external_identity.scim_api_failure / external_identity.scim_api_success

• Purchase additional licenses

  • If all current users require access, purchase more licenses for your enterprise. For more information, see Managing user licenses for an organization or enterprise.

Error: "Out of sync"

If synchronization of team membership with a group on your IdP fails due to a problem other than licensing, you'll see a message that reads "Out of sync".

GitHub will try to resolve this problem automatically during the next sync, which occurs at least once daily. You may be able to resolve the problem by unlinking the impacted team from the IdP group and then linking it to the same group again. For more information, see Managing team memberships with identity provider groups.

If the problem persists, contact GitHub Enterprise Support and provide details about the organization, team, and the IdP group you're experiencing problems with.

SCIM API incomplete events

If you see an external_identity.scim_api_incomplete or external_group.scim_api_incomplete event in your enterprise audit log, a SCIM request from your identity provider was received by GitHub but did not complete successfully. No response was sent back to your identity provider, which may report the operation as failed or timed out.

Resolving the issue

Re-trigger provisioning from your identity provider for the affected user or group. SCIM operations are idempotent, so re-provisioning will not create duplicates.

• Entra ID: In the Microsoft Entra admin center, go to Enterprise Applications > your SCIM app > Provisioning, and use Provision on demand for the affected user or group, or Restart provisioning for a full sync. For more information, see On-demand provisioning in Microsoft Entra ID in the Microsoft documentation.
• Okta: Re-push the affected group from Push Groups, or re-assign the app to the affected user. For more information, see Push Groups in the Okta documentation.
• Other identity providers: Consult your identity provider's documentation for how to re-trigger SCIM provisioning for a specific user or group.

Checking if the change was applied

If you have audit log streaming configured, you can search your streamed logs for other events with the same request_id value from the scim_api_incomplete event. For more information, see Streaming the audit log for your enterprise.

A single group SCIM API call can trigger any of the following events during processing:

Audit log event	Description
external_group.provision	Group was created
external_group.delete	Group was deleted
external_group.update	Group metadata was updated
external_group.update_display_name	Display name was changed
external_group.add_member	A specific member was added
external_group.remove_member	A specific member was removed

To determine which member changes were applied before the interruption, the add_member and remove_member events are the most useful. They identify the specific member affected. If you find fewer member events than the request intended, the remaining members were not processed.

Common causes

Common causes of incomplete events

• Processing time exceeds the connection timeout, often because of large groups.
• A network interruption occurs between the identity provider and GitHub.
• A transient issue occurs on GitHub's infrastructure.
• Your network environment, such as corporate proxies, firewalls, or CASB solutions, interferes with the connection.
• The identity provider's SCIM client timeout settings are too restrictive.

If this event recurs for the same group or user, contact GitHub Enterprise Support with the request_id values from the affected events.

Large group timeouts

A single SCIM PUT or PATCH request for a group with a large number of members can exceed the request timeout. When this happens, your identity provider may report the operation as failed, and you may see an external_group.scim_api_incomplete event in your enterprise audit log.

The SCIM provisioning rate limits describe a limit of 1,000 users per group per hour, but a single PUT or PATCH request that changes membership for a large group can also exceed the request timeout before all members are processed. For more information, see Provisioning users and groups with SCIM using the REST API.

Preventing timeouts

• Break large groups into smaller groups. If your identity provider supports it, consider splitting groups that frequently time out into multiple smaller groups. This reduces the processing time per SCIM request.
• Use incremental updates. Where possible, use PATCH requests to add or remove individual members rather than PUT requests that replace the entire membership list.
• Monitor for incomplete events. Set up audit log streaming and alert on scim_api_incomplete events so you can re-trigger provisioning promptly.