About domain or tenant migrations in Microsoft Entra ID or Workspace 365

Table of Contents

 

For all three scenarios, we strongly recommend to do this outside office hours. When switching domain, do not delete the old domain until you have verified everything works with the new domain.

 

Introduction

There are different kind of scenarios where you need to switch/migrate to a new Microsoft Entra ID (previously called Azure AD) tenant and/or update the domain for the Microsoft Entra ID tenant. In this article, we describe into detail what needs to be updated and in which scenarios. In this article, we use the following example:

Microsoft Entra ID tenant domain UPN Workspace 365 URL

w365support.com

a.carter@w365support.com

https://portal.workspace.url/w365support

 

 

Instruction manuals

Change Microsoft Entra ID tenant with the same domain

If you want to migrate/change the exact same domain and users with UPN (e.g. a.carter@w365support.com) to a new Microsoft Entra ID tenant, there are a few things to consider/update on the Workspace side. 

  Old New

Microsoft Entra ID tenant

w365support.onmicrosoft.com

newtenant.onmicrosoft.com

Microsoft Entra ID domain

w365support.com

w365support.com

UPN

a.carter@w365support.com

a.carter@w365support.com

Workspace 365 URL

https://portal.workspace.url/w365support

https://portal.workspace.url/w365support
  1. Object Ids for users and groups must be identical in the new Microsoft Entra ID tenant compared to the old tenant.
  2. Make sure the workspace admin (see “Licensing” page under Users & groups in the Workspace), is active and has a mailbox enabled. This is required for the next step.
  3. RequestEmergencyAdminAccess with the admin. You will receive an email with instructions.
  4. Follow the email flow and configure Single Sign-On manually.
  5. Optional: after the Single Sign-On setup, you may remove/clean up the old Microsoft Entra ID tenant.

Back to top

 

Change Microsoft Entra ID tenant with different domain

If you are migrating to a new Microsoft Entra ID tenant and the domain changes as well, there are a few things to consider/update on the Workspace side. 

  Old New

Microsoft Entra ID tenant

w365support.onmicrosoft.com

newtenant.onmicrosoft.com

Microsoft Entra ID domain

w365support.com

newdomain.com

UPN

a.carter@w365support.com

a.carter@newdomain.com

Workspace 365 url

https://portal.workspace.url/w365support

https://portal.workspace.url/w365support
  1. Object Ids for users and groups must be identical in the new Microsoft Entra ID tenant compared to the old tenant.
  2. Configure user provisioning to the new Entra ID tenant using our SCIM sync, ensure the users and groups are added to the scope.
    If syncing is not an option to update the UPN, a change in the database is also an option. However, this is a last resort solution. For a database change, make sure you have the following in place:
    • Old domain (e.g. w365support.com)
    • New domain (e.g. newdomain.com)
    • Tenant URL (e.g. portal.workspace365.net/w365support)
      (If you are a self-hosted partner you can update this yourself. If you are a hosted partner, contact us).
  3. In the new Entra ID tenant, manually create the SSO application.
  4. Link the SSO application in the new Entra ID tenant to the workspace, this can be done in two ways:
    • RequestEmergencyAdminAccess, note that this requires the admin to have a valid Exchange license and mailbox.
    • As a partner, you can use the Reset SSO tool to link the new SSO application to the workspace.
  5. Both user provisioning and SSO are now linked to the new Entra ID tenant.
  6. Optional: after the Single Sign-On setup, you may remove/clean up the old Microsoft Entra ID tenant.

Back to top

 

Same Microsoft Entra ID tenant with different domain

If the Microsoft Entra ID tenant remains the same, but the domain changes, follow the steps below.

  1. Make sure you have the Azure AD synctool or SCIM API connected to the Workspace environment.
  2. Go to the Workspace SSO settings page.
  3. Change the authority from “https://login.windows.net/olddomain“ to “https://login.windows.net/newdomain“.
    • When clearing the URL for the old domain, it will also automatically clear the corresponding key. So you need to re-enter the key. This key must match with the key in the corresponding SSO App registration in Microsoft Entra ID under Certificates & Secrets -> Client secret. For more information, go to: Manual setup of SSO
    • Important: If the old domain is deleted from Microsoft Entra ID before the authority has been changed, then users will not be able to login.
  4. Click 'Verify'. If successful, you should see a green screen.
  5. In Azure, update the users to the new domain, so that the new domain is used in their UPN.
    • Note: At this moment, no workspace user is able to log into the workspace environment. 
  6. Synchronize all the users with the Azure AD synctool or SCIM to the Workspace environment.
  7. Login to test if everything is working as expected. 

Back to top