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.

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:

  • GitHub will reset the SCIM records associated with your enterprise's managed user accounts. 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. 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 Enterprise Cloud 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.

  • GitHub Enterprise Cloud will remove connections between teams on GitHub and IdP groups, and does not reinstate the connections after migration. GitHub will also remove all members from the team and leave the team unconnected to your IdP. 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 and provisioning 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 and provisioning 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 and provisioning for your enterprise. For more information, see Disabling authentication and provisioning for Enterprise Managed Users.
  3. Wait up to an hour for GitHub Enterprise Cloud to reset your enterprise's SCIM records and suspend your enterprise's members.

5. Validate suspension of your enterprise's members

After you disable authentication and provisioning, GitHub Enterprise Cloud will suspend all of the managed user accounts for your enterprise. You can validate suspension of your enterprise's members using the web UI.

  1. View the suspended members in your enterprise. For more information, see Viewing people in your enterprise.

  2. If all of your enterprise's members are not yet suspended, continue waiting, and review the logs on your SCIM provider.

    • If you use Entra ID, suspension of your members can take up to 40 minutes. To expedite the process for an individual user, click the Provision on Demand button in the "Provisioning" tab of the application for Enterprise Managed Users.

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.

To unsuspend your managed user accounts and allow them to sign in to GitHub Enterprise Cloud, your SCIM provider must reprovision their accounts.

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.