Managing team synchronization for your organization

You can enable and disable team synchronization between your identity provider (IdP) and your organization on GitHub.

Organization owners can manage team synchronization for an organization.

Team synchronization is available for organizations and enterprise accounts using GitHub Enterprise Cloud. For more information, see "GitHub's products."

About team synchronization

You can enable team synchronization between your IdP and GitHub to allow organization owners and team maintainers to connect teams in your organization with IdP groups.

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 use team synchronization with supported IdPs.

  • Azure AD
  • Okta

After you enable team synchronization, team maintainers and organization owners can connect a team to an IdP group on GitHub or through the API. For more information, see "Synchronizing a team with an identity provider group" and "Team synchronization."

You can also enable team synchronization for organizations owned by an enterprise account. For more information, see "Managing team synchronization for organizations in your enterprise."

Usage limits

There are usage limits for the team synchonization feature. Exceeding these limits will lead to a degredation in performance and may cause synchronization failures.

  • Maximum number of members in a GitHub team: 5,000
  • Maximum number of members in a GitHub organization: 10,000
  • Maximum number of teams in a GitHub organization: 1,500

Enabling team synchronization

The steps to enable team synchronization depend on the IdP you want to use. There are prerequisites to enable team synchronization that apply to every IdP. Each individual IdP has additional prerequisites.

Prerequisites

To enable team synchronization with any IdP, you must obtain administrative access to your IdP or work with your IdP administrator to configure the IdP integration and groups. The person who configures your IdP integration and groups must have one of the required permissions.

IdPRequired permissions
Azure AD
  • Global administrator
  • Privileged Role administrator
Okta
  • Service user with read-only administrator permissions

You must enable SAML single sign-on for your organization and your supported IdP. For more information, see "Enforcing SAML single sign-on for your organization."

You must have a linked SAML identity. To create a linked identity, you must authenticate to your organization using SAML SSO and the supported IdP at least once. For more information, see "Authenticating with SAML single sign-on."

Enabling team synchronization for Azure AD

To enable team synchronization for Azure AD, your Azure AD installation needs the following permissions.

  • Read all users’ full profiles
  • Sign in and read user profile
  • Read directory data
  1. In the top right corner of GitHub.com, click your profile photo, then click Your organizations. Your organizations in the profile menu

  2. Next to the organization, click Settings. The settings button

  3. In the left sidebar, click Organization security.

    Organization security settings

  4. Confirm that SAML SSO is enabled for your organization. For more information, see "Managing SAML single sign-on for your organization."

  5. Under "Team synchronization", click Enable for Azure AD. Enable team synchronization button on security settings page

  6. Confirm team synchronization.

    • If you have IdP access, click Enable team synchronization. You'll be redirected to your identity provider's SAML SSO page and asked to select your account and review the requested permissions.
    • If you don't have IdP access, copy the IdP redirect link and share it with your IdP administrator to continue enabling team synchronization. Enable team synchronization redirect button
  7. Review the identity provider tenant information you want to connect to your organization, then click Approve. Pending request to enable team synchronization to a specific IdP tenant with option to approve or cancel request

Enabling team synchronization for Okta

Okta team synchronization requires that SAML and SCIM with Okta have already been set up for your organization.

To avoid potential team synchronization errors with Okta, we recommend that you confirm that SCIM linked identities are correctly set up for all organization members who are members of your chosen Okta groups, before enabling team synchronization on GitHub.

If an organization member does not have a linked SCIM identity, then team synchronization will not work as expected and the user may not be added or removed from teams as expected. If any of these users are missing a SCIM linked identity, you will need to reprovision them.

For help on provisioning users that have missing a missing SCIM linked identity, see "Troubleshooting identity and access management."

Before you enable team synchronization for Okta, you or your IdP administrator must:

  • Configure the SAML, SSO, and SCIM integration for your organization using Okta. For more information, see "Configuring SAML single sign-on and SCIM using Okta."
  • Provide the tenant URL for your Okta instance.
  • Generate a valid SSWS token with read-only admin permissions for your Okta installation as a service user. For more information, see Create the token and Service users in Okta's documentation.
  1. In the top right corner of GitHub.com, click your profile photo, then click Your organizations. Your organizations in the profile menu

  2. Next to the organization, click Settings. The settings button

  3. In the left sidebar, click Organization security.

    Organization security settings

  4. Confirm that SAML SSO is enabled for your organization. For more information, see "Managing SAML single sign-on for your organization."

  5. We recommend you confirm that your users have SAML enabled and have a linked SCIM identity to avoid potential provisioning errors. For help auditing your users, see "Auditing users for missing SCIM metadata." For help resolving unlinked SCIM identities, see "Troubleshooting identity and access management."

  6. Consider enforcing SAML in your organization to ensure that organization members link their SAML and SCIM identities. For more information, see "Enforcing SAML single sign-on for your organization."

  7. Under "Team synchronization", click Enable for Okta. Enable team synchronization for Okta button on security settings page

  8. Under your organization's name, type a valid SSWS token and the URL to your Okta instance. Enable team synchronization Okta organization form

  9. Review the identity provider tenant information you want to connect to your organization, then click Create. Enable team synchronization create button

Disabling team synchronization

Warning: When you disable team synchronization, any team members that were assigned to a GitHub team through the IdP group are removed from the team and may lose access to repositories.

  1. In the top right corner of GitHub.com, click your profile photo, then click Your organizations. Your organizations in the profile menu

  2. Next to the organization, click Settings. The settings button

  3. In the left sidebar, click Organization security.

    Organization security settings

  4. Under "Team synchronization", click Disable team synchronization. Disable team synchronization

Did this doc help you?

Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.