Migrating your enterprise to a new identity provider or tenant

If your enterprise will use a new identity provider (IdP) or tenant for authentication and provisioning after you initially configure Security Assertion Markup Language (SAML) or OpenID Connect (OIDC) and SCIM, you can migrate to a new configuration.

Who can use this feature?

Enterprise owners and people with administrative access to your IdP can migrate your enterprise to a new IdP or tenant.

Enterprise Managed Users is available for new enterprise accounts on GitHub Enterprise Cloud. See About Enterprise Managed Users.

In this article

About migrations between IdPs and tenants

While using Enterprise Managed Users, you may need to migrate your enterprise to a new tenant on your IdP, or to a different identity management system. For example, you might be ready to migrate from a test environment to your production environment, or your company may decide to use a new identity system.

Before you migrate to a new authentication and provisioning configuration, review the prerequisites and guidelines for preparation. When you're ready to migrate, you'll disable authentication and provisioning for your enterprise, then reconfigure both. You cannot edit your existing configuration for authentication and provisioning.

GitHub will delete the existing SCIM identities associated with your enterprise's managed user accounts when authentication is disabled for the enterprise. For more details on the impact of disabling authentication for an enterprise with enterprise managed users, See Disabling authentication for Enterprise Managed Users.

After authentication and provisioning is reconfigured at the end of the migration, users and groups must be re-provisioned from the new IdP/tenant. When the users are re-provisioned, GitHub will compare the normalized SCIM userName attribute values to the GitHub usernames (the portion before the _[shortcode]) in the enterprise in order to link the SCIM identities from the new IdP/tenant to existing enterprise managed user accounts. For more information, see Username considerations for external authentication.

Prerequisites

  • When you began using GitHub Enterprise Cloud, you must have chosen to create an enterprise with managed users. For more information, see Choosing an enterprise type for GitHub Enterprise Cloud.
  • Review and understand the requirements for integration with Enterprise Managed Users from an external identity management system. To simplify configuration and support, you can use a single partner IdP for a "paved-path" integration. Alternatively, you can configure authentication using a system that adheres to the Security Assertion Markup Language (SAML) 2.0 and System for Cross-domain Identity Management (SCIM) 2.0 standards. For more information, see About Enterprise Managed Users.
  • You must have already configured authentication and SCIM provisioning for your enterprise.

Preparing for migration

To migrate to a new configuration for authentication and provisioning, you must first disable authentication and provisioning for your enterprise. Before you disable your existing configuration, review the following considerations:

  • Before you migrate, determine whether the values of the normalized SCIM userName attribute will remain the same for managed user accounts in the new environment. These normalized SCIM userName attribute values must remain the same for users in order for the SCIM identities provisioned from the new IdP/tenant to get properly linked to the existing enterprise managed user accounts. For more information, see Username considerations for external authentication.

    • If the normalized SCIM userName values will remain the same after the migration, you can complete the migration yourself.
    • If the normalized SCIM userName values will change after the migration, GitHub will need to help with your migration. For more information, see Migrating when the normalized SCIM userName values will change.

  • Do not remove any users or groups from the application for Enterprise Managed Users on your identity management system until after your migration is complete.

  • GitHub will delete any personal access tokens or SSH keys associated with your enterprise's managed user accounts. Plan for a migration window after reconfiguration during which you can create and provide new credentials to any external integrations.

  • As part of the migration steps below, GitHub will delete all of the SCIM-provisioned groups in your enterprise when authentication is disabled for the enterprise. For more information, see Disabling authentication for Enterprise Managed Users.

If any of these SCIM-provisioned IdP groups are linked to teams in your enterprise, this will remove the link between these teams on GitHub and IdP groups, and these links are not automatically reinstated after the migration. GitHub will also remove all members from the previously linked teams. You may experience disruption if you use groups on your identity management system to manage access to organizations or licenses. GitHub recommends that you use the REST API to list team connections and group membership before you migrate, and to reinstate connections afterwards. For more information, see REST API endpoints for external groups in the REST API documentation.

Migrating to a new IdP or tenant

To migrate to a new IdP or tenant, you must complete the following tasks.

  1. Validate matching SCIM userName attributes.
  2. Download single sign-on recovery codes.
  3. Disable provisioning on your current IdP.
  4. Disable authentication for your enterprise.
  5. Validate suspension of your enterprise's members.
  6. Reconfigure authentication and provisioning.

1. Validate matching SCIM userName attributes

For a seamless migration, ensure that the SCIM userName attribute on your new SCIM provider matches the attribute on your old SCIM provider. If these attributes don't match, see Migrating when the normalized SCIM userName values will change.

2. Download single sign-on recovery codes

If you don't already have single sign-on recovery codes for your enterprise, download the codes now. For more information, see Downloading your enterprise account's single sign-on recovery codes.

3. Disable provisioning on your current IdP

  1. On your current IdP, deactivate provisioning in the application for Enterprise Managed Users.
    • If you use Entra ID, navigate to the "Provisioning" tab of the application, and then click Stop provisioning.
    • If you use Okta, navigate to the "Provisioning" tab of the application, click the Integration tab, and then click Edit. Deselect Enable API integration.
    • If you use PingFederate, navigate to the channel settings in the application. From the Activation & Summary tab, click Active or Inactive to toggle the provisioning status, and then click Save. For more information about managing provisioning, see Reviewing channel settings and Managing channels in the PingFederate documentation.
    • If you use another identity management system, consult the system's documentation, support team, or other resources.

4. Disable authentication for your enterprise

  1. Use a recovery code to sign into GitHub as the setup user, whose username is your enterprise's shortcode suffixed with _admin. For more information about the setup user, see Getting started with Enterprise Managed Users.
  2. Disable authentication for your enterprise. For more information, see Disabling authentication for Enterprise Managed Users.
  3. Wait up to an hour for GitHub to suspend your enterprise's members, delete the linked SCIM identities, and delete the SCIM-provisioned IdP groups.

5. Validate suspension of your enterprise's members

After you disable authentication in your GitHub enterprise settings, GitHub will suspend all of the managed user accounts (with the exception of the setup user account) in your enterprise. You can validate suspension of your enterprise's members on GitHub.

  1. View the suspended members in your enterprise. For more information, see Viewing people in your enterprise.
  2. If all of the managed user accounts in your enterprise are not yet suspended, continue waiting and monitoring in GitHub before proceeding with the next step.

6. Reconfigure authentication and provisioning

After you validate the suspension of your enterprise's members, reconfigure authentication and provisioning.

  1. Configure authentication using SAML or OIDC SSO. For more information, see Configuring authentication for Enterprise Managed Users.
  2. Configure SCIM provisioning. For more information, see Configuring SCIM provisioning for Enterprise Managed Users.

7. Make sure users and groups are reprovisioned from the new IdP/tenant

  1. To unsuspend your managed user accounts and allow them to sign in to GitHub, the users must be reprovisioned from the new IdP/tenant. This links the SCIM identities from the new IdP/tenant to the existing enterprise managed user accounts. An enterprise managed user must have a linked SCIM identity in order to sign in.
    • When reprovisioning the IdP user accounts, if a user has been successfully linked to their SCIM identity from the new IdP/tenant, you will see an SSO identity linked link on their page in your enterprise settings, which will show a SCIM identity section with SCIM attributes. For more information, see Viewing people in your enterprise.
    • You can also review related external_identity.* and user.unsuspend events in the enterprise audit log. For more information, see Audit log events for your enterprise
  2. Groups must be reprovisioned from the new IdP/tenant as well.
  3. Once IdP groups have been reprovisioned to the enterprise, admins can link the groups to teams in the enterprise as needed.

Migrating when the normalized SCIM userName values will change

If the normalized SCIM userName values will change, GitHub must provision a new enterprise account for your migration. Contact our sales team for help.