Change Microsoft Entra ID tenant with the same domain
Change Microsoft Entra ID tenant with different domain
Same Microsoft Entra ID tenant with different domain
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 |
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. [email protected]) 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 | ||
Workspace 365 URL |
Object Ids for users and groups must be identical in the new Microsoft Entra ID tenant compared to the old tenant.
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.
RequestEmergencyAdminAccess with the admin. You will receive an email with instructions.
Follow the email flow and configure Single Sign-On manually.
Optional: after the Single Sign-On setup, you may remove/clean up the old Microsoft Entra ID tenant.
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 | ||
Workspace 365 url |
Object Ids for users and groups must be identical in the new Microsoft Entra ID tenant compared to the old tenant.
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).
In the new Entra ID tenant, manually create the SSO application.
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.
Both user provisioning and SSO are now linked to the new Entra ID tenant.
Optional: after the Single Sign-On setup, you may remove/clean up the old Microsoft Entra ID tenant.
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.
Make sure you have the Azure AD synctool or SCIM API connected to the Workspace environment.
Go to the Workspace SSO settings page.
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.
Click 'Verify'. If successful, you should see a green screen.
If you see a red screen with an error, as an alternative you can use the Provisioning API SSO put request to change the authority.
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.
Synchronize all the users with the Azure AD synctool or SCIM to the Workspace environment.
Login to test if everything is working as expected.