While using Enterprise Managed Users, you may need to migrate your enterprise to a new tenant on your IdP. For example, you might be ready to migrate from a test environment to your production environment.
Migrating to a new IdP or tenant can cause disruption to integrations and automated flows in your enterprise.
- When your current SAML IdP is disabled, personal access tokens and SSH keys associated with managed user accounts will be deleted. You should plan for a migration window after configuring your new IdP, during which you can create and deploy new keys to your integrations where necessary.
- When you migrate to a new IdP or tenant, connections between GitHub teams and IdP groups are removed, and are not reinstated after the migration. This will remove all members from the team and leave the team unconnected to your IdP, which may cause disruption if you use team sync to manage access to organizations or licenses from your IdP. We recommend you use the "External groups" endpoints of the REST API to gather information about your teams setup before you migrate, and to reinstate connections afterwards. For more information, see "External groups."
- After you initially configure authentication and provisioning, GitHub does not recommend migration to a different platform for authentication or provisioning. If you need to migrate an existing enterprise to a different platform for authentication or provisioning, contact your account manager on GitHub's Sales team.
Before you migrate your enterprise with managed users to a new IdP or tenant, determine whether the values of the normalized SCIM
userName attribute will remain the same for your managed user accounts in the new environment. For more information about username normalization, see "Username considerations for external authentication."
If the normalized SCIM
userName values will remain the same after the migration, you can complete the migration by yourself. For instructions, see "Migrating when the normalized SCIM
userName values will remain the same."
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."
To migrate to a new IdP or tenant, you cannot edit your existing SAML configuration. Instead, you must completely deactivate SAML for your enterprise account, then create new SAML and SCIM configurations for the new IdP or tenant.
Warning: Do not remove any users or groups from the application for Enterprise Managed Users in your original IdP or tenant until after your migration is complete.
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."
In 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 Ping Federate documentation.
Use a recovery code to sign into GitHub.com as the setup user, whose username is your enterprise's shortcode suffixed with
_admin. For more information about the setup user, see "About Enterprise Managed Users."
Deactivate SAML for the enterprise with managed users. For more information, see "Disabling authentication for Enterprise Managed Users."
Wait for all users in the enterprise to show as suspended.
While still signed in as the setup user, configure SAML and SCIM for the new IdP or tenant with a new Enterprise Managed Users application.
After you configure provisioning for the new application, the managed user accounts will be unsuspended, and your developers will be able to sign into their existing accounts again.
By default, this process can take up to 40 minutes for Entra ID. 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.
If the normalized SCIM
userName values will change, GitHub must provision a new enterprise account for your migration. Contact our sales team for help.