Merge pull request #21545 from github/repo-sync

repo sync

Author: Octomerger

content/admin/identity-and-access-management/managing-iam-for-your-enterprise/troubleshooting-identity-and-access-management-for-your-enterprise.md

@@ -27,6 +27,7 @@ If you're experiencing problems while switching between different authentication
 
 - "[Switching your SAML configuration from an organization to an enterprise account](/admin/identity-and-access-management/using-saml-for-enterprise-iam/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account)"
 - "[Migrating from SAML to OIDC](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/migrating-from-saml-to-oidc)"
+- "[Migrating your enterprise to a new identity provider or tenant](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/migrating-your-enterprise-to-a-new-identity-provider-or-tenant)"
 
 ## Accessing your enterprise when SSO is not available
 

content/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/index.md

@@ -22,5 +22,6 @@ children:
   - /managing-team-memberships-with-identity-provider-groups
   - /about-support-for-your-idps-conditional-access-policy
   - /migrating-from-saml-to-oidc
+  - /migrating-your-enterprise-to-a-new-identity-provider-or-tenant
 ---
 

content/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/migrating-your-enterprise-to-a-new-identity-provider-or-tenant.md

@@ -0,0 +1,58 @@
+---
+title: Migrating your enterprise to a new identity provider or tenant
+shortTitle: Migrate to new IdP or tenant
+intro: 'You can migrate your enterprise to a different identity provider (IdP) or Azure AD tenant.'
+product: '{% data reusables.gated-features.emus %}'
+versions:
+  feature: idp-tenant-migration
+topics:
+  - Access management
+  - Accounts
+  - Administrator
+  - Authentication
+  - Enterprise
+  - SSO
+---
+
+## About migrations between IdPs and tenants
+
+While using {% data variables.product.prodname_emus %}, you may need to migrate your enterprise to a new IdP or Azure AD tenant. For example, you might be ready to migrate from a test environment to your production environment.
+
+Before you migrate your {% data variables.enterprise.prodname_emu_enterprise %} to a new IdP or tenant, determine whether the values of the normalized SCIM `userName` attribute will remain the same for your {% data variables.enterprise.prodname_managed_users %} in the new environment. For more information about username normalization, see "[Username considerations for external authentication](/admin/identity-and-access-management/managing-iam-for-your-enterprise/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](#migrating-when-the-normalized-scim-username-values-will-remain-the-same)."
+
+If the normalized SCIM `userName` values will change after the migration, {% data variables.product.company_short %} will need to help with your migration. For more information, see "[Migrating when the normalized SCIM `userName` values will change](#migrating-when-the-normalized-scim-username-values-will-change)."
+
+## Migrating when the normalized SCIM `userName` values will remain the same
+
+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 %}
+
+**Warning:** Do not remove any users or groups from the application for {% data variables.product.prodname_emus %} in your original IdP or tenant until after your migration is complete.
+
+{% endwarning %}
+
+1. 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](/admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise/downloading-your-enterprise-accounts-single-sign-on-recovery-codes)."
+1. In your current IdP, deactivate provisioning in the application for {% data variables.product.prodname_emus %}.
+    -  If you use Azure AD, 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**.
+1. Use a recovery code to sign into {% data variables.product.prodname_dotcom_the_website %} as the setup user, whose username is your enterprise's shortcode suffixed with `_admin`. For more information about the setup user, see "[About {% data variables.product.prodname_emus %}](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users#getting-started-with-enterprise-managed-users)."
+
+1. Deactivate SAML for the {% data variables.enterprise.prodname_emu_enterprise %}.
+   -  From your profile, click **Your enterprises**, and then click the appropriate enterprise.
+   - Click {% octicon "gear" aria-label="The Settings gear" %} **Settings**, and then click **Authentication security**. 
+   - Under "SAML single sign-on", deselect **Require SAML authentication**, and then click **Save**. 
+   
+1. Wait for all users in the enterprise to show as suspended.
+
+1. While still signed in as the setup user, configure SAML and SCIM for the new IdP or tenant with a new {% data variables.product.prodname_emus %} application.
+   
+   After you configure provisioning for the new application, the {% data variables.enterprise.prodname_managed_users %} 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 Azure AD. To expedite the process for an individual user, click the **Provision on Demand** button in the "Provisioning" tab of the application for {% data variables.product.prodname_emus %}.
+
+## Migrating when the normalized SCIM `userName` values will change
+
+If the normalized SCIM `userName` values will change, {% data variables.product.company_short %} must provision a new enterprise account for your migration. [Contact our sales team](https://github.com/enterprise/contact) for help.

content/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad.md

@@ -44,7 +44,7 @@ To configure authentication and user provisioning for {% data variables.product.
 
 {% ifversion ghae %}
 
-1. In Azure AD, add {% data variables.product.ae_azure_ad_app_link %} to your tenant and configure single sign-on. For more information, see [Tutorial: Azure Active Directory single sign-on (SSO) integration with {% data variables.product.prodname_ghe_managed %}](https://docs.microsoft.com/azure/active-directory/saas-apps/github-ae-tutorial) in the Microsoft Docs.
+1. In Azure AD, add the {% data variables.enterprise.ae_azure_ad_app_link %} to your tenant and configure single sign-on. For more information, see [Tutorial: Azure Active Directory single sign-on (SSO) integration with {% data variables.product.prodname_ghe_managed %}](https://docs.microsoft.com/azure/active-directory/saas-apps/github-ae-tutorial) in the Microsoft Docs.
 
 1. In {% data variables.product.prodname_ghe_managed %}, enter the details for your Azure AD tenant.
 

data/features/idp-tenant-migration.yml

@@ -0,0 +1,4 @@
+# Reference: #7781
+# Documentation for migrating an EMU-enabled enterprise's IdP or tenant
+versions:
+  ghec: '*'

data/variables/enterprise.yml

@@ -13,3 +13,6 @@ prodname_emu_org: 'organization with managed users'
 ## Phrase content so that the uncapitalized unified contributions or unified search variables are not used at the start of a sentence.
 prodname_unified_contributions: 'unified contributions'
 prodname_unified_search: 'unified search'
+
+# Azure AD
+ae_azure_ad_app_link: '[GitHub AE application](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/aad.githubenterpriseserver)'

data/variables/product.yml

@@ -110,9 +110,6 @@ prodname_oauth_apps: 'OAuth Apps'
 prodname_enterprise_api: '{% ifversion ghes %}GitHub Enterprise Server{% elsif ghae %}GitHub AE{% endif %} APIs'
 prodname_unfurls: 'Content Attachments'
 
-# Azure AD
-ae_azure_ad_app_link: 'the [GitHub AE application](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/aad.githubenterpriseserver)'
-
 # GitHub Actions
 ## Use this variable only when referring to GitHub Actions the product. When referring to the thing that someone creates using the product, call it an action (small a). See the terminology page of the Brand Guide for more.
 prodname_actions: 'GitHub Actions'