From 4b68c057255598e15594635b8f096db788486769 Mon Sep 17 00:00:00 2001 From: Joe Clark <31087804+jc-clark@users.noreply.github.com> Date: Fri, 21 Oct 2022 16:52:48 -0700 Subject: [PATCH 1/2] Make Azure AD non-product name translation friendly (#31876) --- ...tion-and-provisioning-for-your-enterprise-using-azure-ad.md | 2 +- data/variables/enterprise.yml | 3 +++ data/variables/product.yml | 3 --- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/content/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad.md b/content/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad.md index 8775694a20..282f059d93 100644 --- a/content/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad.md +++ b/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. diff --git a/data/variables/enterprise.yml b/data/variables/enterprise.yml index 8c3561eadc..478806e3b4 100644 --- a/data/variables/enterprise.yml +++ b/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)' diff --git a/data/variables/product.yml b/data/variables/product.yml index 903b4ee61b..16646ba56b 100644 --- a/data/variables/product.yml +++ b/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' From 37dad7113bae5f057310ab9db39bb56326cce3df Mon Sep 17 00:00:00 2001 From: Joe Clark <31087804+jc-clark@users.noreply.github.com> Date: Fri, 21 Oct 2022 17:16:38 -0700 Subject: [PATCH 2/2] Add documentation on migrating IdP or Azure AD tenant (#31065) Co-authored-by: Laura Coursen --- ...d-access-management-for-your-enterprise.md | 1 + .../index.md | 1 + ...se-to-a-new-identity-provider-or-tenant.md | 58 +++++++++++++++++++ data/features/idp-tenant-migration.yml | 4 ++ 4 files changed, 64 insertions(+) create mode 100644 content/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/migrating-your-enterprise-to-a-new-identity-provider-or-tenant.md create mode 100644 data/features/idp-tenant-migration.yml diff --git a/content/admin/identity-and-access-management/managing-iam-for-your-enterprise/troubleshooting-identity-and-access-management-for-your-enterprise.md b/content/admin/identity-and-access-management/managing-iam-for-your-enterprise/troubleshooting-identity-and-access-management-for-your-enterprise.md index 5441ff3123..a95decde6d 100644 --- a/content/admin/identity-and-access-management/managing-iam-for-your-enterprise/troubleshooting-identity-and-access-management-for-your-enterprise.md +++ b/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 diff --git a/content/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/index.md b/content/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/index.md index 3cdd6e2a6a..80f19f1c78 100644 --- a/content/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/index.md +++ b/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 --- diff --git a/content/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/migrating-your-enterprise-to-a-new-identity-provider-or-tenant.md b/content/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/migrating-your-enterprise-to-a-new-identity-provider-or-tenant.md new file mode 100644 index 0000000000..6617637f80 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/data/features/idp-tenant-migration.yml b/data/features/idp-tenant-migration.yml new file mode 100644 index 0000000000..41754f7159 --- /dev/null +++ b/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: '*'