Add section on migrating SAML IDP and email Domain

doc/user/group/saml_sso/index.md

@@ -214,6 +214,35 @@ we recommend the ["Use the OneLogin SAML Test Connector" documentation](https://
 
 Recommended `NameID` value: `OneLogin ID`.
 
+### Change the SAML app
+
+To change the SAML app used for sign in:
+
+- If the NameID is not identical in both the existing and new SAML apps, users must:
+  1. [Unlink the current SAML identity](#unlinking-accounts).
+  1. [Link their identity](#user-access-and-management) to the new SAML app.
+- If the NameID is identical, no change is required.
+
+### Migrate to a different SAML provider
+
+You can migrate to a different SAML provider. During the migration process users will not be able to access any of the SAML groups.
+To mitigate this, you can disable [SSO enforcement](#sso-enforcement). 
+
+To migrate SAML providers:
+
+1. [Configure](#configure-your-identity-provider) the group with the new identity provider SAML app.
+1. Ask users to [unlink their account from the group](#unlinking-accounts).
+1. Ask users to [link their account to the new SAML app](#linking-saml-to-your-existing-gitlabcom-account).
+
+### Change email domains
+
+To migrate users to a new email domain, users must:
+
+1. Add their new email as the primary email to their accounts and verify it.
+1. [Unlink their account from the group](#unlinking-accounts).
+1. [Link their account to the group](#linking-saml-to-your-existing-gitlabcom-account).
+1. (Optional) Remove their old email from the account.
+
 ## User access and management
 
 > [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/268142) in GitLab 13.7.
@@ -610,12 +639,6 @@ Alternatively, when users need to [link SAML to their existing GitLab.com accoun
 | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | As mentioned in the [NameID](#nameid) section, if the NameID changes for any user, the user can be locked out. This is a common problem when an email address is used as the identifier. | Follow the steps outlined in the ["SAML authentication failed: User has already been taken"](#message-saml-authentication-failed-user-has-already-been-taken) section. |
 
-### I need to change my SAML app
-
-If the NameID is identical in both SAML apps, then no change is required.
-
-Otherwise, to change the SAML app used for sign in, users need to [unlink the current SAML identity](#unlinking-accounts) and then [link their identity](#user-access-and-management) to the new SAML app.
-
 ### I need additional information to configure my identity provider
 
 Many SAML terms can vary between providers. It is possible that the information you are looking for is listed under another name.

doc/user/group/saml_sso/scim_setup.md

@@ -244,7 +244,7 @@ It is important not to update these to incorrect values, since this causes users
 
 ### I need to change my SCIM app
 
-Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](index.md#i-need-to-change-my-saml-app) section.
+Individual users can follow the instructions in the ["SAML authentication failed: User has already been taken"](index.md#change-the-saml-app) section.
 
 Alternatively, users can be removed from the SCIM app which de-links all removed users. Sync can then be turned on for the new SCIM app to [link existing users](#user-access-and-linking-setup).