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. In the top-right corner of GitHub, click your profile picture.

2. Depending on your environment, click Enterprise, or click Enterprises then click the enterprise you want to view.

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

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

5. Under Identity provider, click Groups.

6. 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."

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

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