Synchronizing a team with an identity provider group

About team synchronization

When you synchronize a GitHub team with an IdP group, changes to the IdP group are reflected on GitHub automatically, reducing the need for manual updates and custom scripts. You can use an IdP with team synchronization to manage administrative tasks such as onboarding new members, granting new permissions for movements within an organization, and removing member access to the organization.

You can connect up to five IdP groups to a GitHub team. An IdP group can be assigned to multiple GitHub teams without restriction.

Once a GitHub team is connected to an IdP group, your IdP administrator must make team membership changes through the identity provider. You cannot manage team membership on GitHub or using the API.

All team membership changes made through your IdP will appear in the audit log on GitHub as changes made by the team synchronization bot. Your IdP will send team membership data to GitHub once every hour. Connecting a team to an IdP group may remove some team members. For more information, see "Requirements for members of synchronized teams."

Parent teams cannot synchronize with IdP groups. If the team you want to connect to an IdP group is a parent team, we recommend creating a new team or removing the nested relationships that make your team a parent team. For more information, see "About teams," "Creating a team," and "Moving a team in your organization's hierarchy."

To manage repository access for any GitHub team, including teams connected to an IdP group, you must make changes with GitHub. For more information, see "About teams" and "Managing team access to an organization repository."

You can also manage team synchronization with the API. For more information, see "Team synchronization."

Requirements for members of synchronized teams

After you connect a team to an IdP group, membership data for each team member will synchronize if the person continues to authenticate using SAML SSO with the same SSO identity on GitHub, and if the person remains a member of the connected IdP group.

Existing teams or group members can be automatically removed from the team on GitHub. Any existing teams or group members not authenticating to the organization or enterprise account using SSO may lose access to repositories. Any existing teams or group members not in the connected IdP group may potentially lose access to repositories.

A removed team member can be added back to a team automatically once they have authenticated to the organization or enterprise account using SSO and are moved to the connected IdP group.

To avoid unintentionally removing team members, we recommend enforcing SAML SSO in your organization or enterprise account, creating new teams to synchronize membership data, and checking IdP group membership before synchronizing existing teams. For more information, see "Enforcing SAML single sign-on for your organization."

If your organization is owned by an enterprise account, enabling team synchronization for the enterprise account will override your organization-level team synchronization settings. For more information, see "Enforcing security settings in your enterprise account."

Prerequisites

Before you can connect a team with an identity provider group, an organization or enterprise owner must enable team synchronization for your organization or enterprise account. For more information, see "Managing team synchronization for your organization" and "Enforcing security settings in your enterprise account."

To avoid unintentionally removing team members, visit the administrative portal for your IdP and confirm that each current team member is also in the IdP groups that you want to connect to this team. If you don't have this access to your identity provider, you can reach out to your IdP administrator.

You must authenticate using SAML SSO. For more information, see "Authenticating with SAML single sign-on."

Connecting an IdP group to a team

1. In the top right corner of GitHub, click your profile photo, then click Your profile.
   
2. On the left side of your profile page, under "Organizations", click the icon for your organization.
   
3. Under your organization name, click Teams.
   
4. On the Teams tab, click the name of the team.
   
5. At the top of the team page, click Settings.
   
6. Under "Identity Provider Groups", use the drop-down menu, and select up to 5 identity provider groups.
   
7. Click Save changes.

Disconnecting an IdP group from a team

If you disconnect an IdP group from a GitHub team, team members that were assigned to the GitHub team through the IdP group will be removed from the team.

1. In the top right corner of GitHub, click your profile photo, then click Your profile.
   
2. On the left side of your profile page, under "Organizations", click the icon for your organization.
   
3. Under your organization name, click Teams.
   
4. On the Teams tab, click the name of the team.
   
5. At the top of the team page, click Settings.
   
6. Under "Identity Provider Groups", to the right of the IdP group you want to disconnect, click .
   
7. Click Save changes.