CROSS TENANT LAPTOP MIGRATION GUIDE
1.Cross Tenant Laptop Migration : Introduction
Microsoft has renamed Azure AD to Entra. This guide will use indifferently the term Entra or Azure AD.
What does the Azure AD registered device migration do?
-
- It breaks the AD registered device settings. The computers are registered to the source device. This jointure needs to be broken in order to allow a registration into the new target tenant.
- It breaks the Office licenses (Wold, Excell Powerpoint): Licenses are validated against the source tenant. After migration, the use of the source licenses need to be deleted. The next time that the user logins using his target credentials, Word and Excel will start using the target license.
- It stops the synchronization of the OneDrive Sync Agent. After the migration of the user, the OneDrive Synchronization agent must not synchronize anymore with the source. By breaking the synchronization with the source, the next time the user logins, It will start synchronizing with the target.
- It deletes the Outlook profile configuration. After migration, when the user starts outlook, he is prompted to enter his email address and a profile linked to the target mailbox is automatically created.
What does the Azure AD joined device migration do?
-
- The device is unjoined from the source tenant.
- The device is deregistered from the source Intune tenant.
- As for the Entra registered devices, office licenses, OneDrive Sync Agent, Outlook profiles are removed
- The Windows profile is migrated. After migration, the user logs with his target credentials but his Windows profile is preserved.
- The computer is joined automatically to the target tenant
- The computer is registered to the target Intune tenant.
- BitLocker encryption keys are backed into the new tenant.
2.How does it work?
A local agent is installed on every laptop.
The migration is centrally managed from the Cloudiway console: The administror triggers or schedules the migration from the Cloudiway user list.
The local agent periodically connects to the Cloudiway platform and starts the migration when he detects that it’s time to migrate. The administrator can request to start migration immediately or at a given date.
2.1 Pre-requisites
Email Addresses vs UPN
You must fill the Cloudiway migration list with the email addresses, not the UPNs.
When reconfiguring the laptop, various settings are stored in the user profile ( HKEY_CURRENT_USER). Essentially, this means that the user must be logged in for the migration to occur ( You cannot simply reboot the computer with nobody logged in). The agent is configured to start as a startup task when the user logs in and it runs in the background.
2.2 Environment Non Administrator of device
The migration of joined devices requires to perform several administrative tasks such as:
- Delete Intune registered settings
- Apply a provisioning package to join the target tenant
- Create Startup tasks to migrate the profiles
- etc…
If the enduser installs himself the agent (self service functionality), he must be administrator of the device. If the user is not administrator of the device, the administrators can deploy the agent on the computer devices using the method of their choice.
Installation Procedure
-
- Download the installation script
- Modify the Powershell script and append the email address of the user for which you are installing the agent. Also, add your company key.
- Download the installation script
$tmp = “$env:TEMP\CloudiwayAgent.msi” Start-Process C:\Windows\System32\msiexec.exe -ArgumentList “/i $tmp EMAIL=sourceEmail TARGETDIR=$cdw /qn COMPANYKEY=KEY;ALIAS” -Wait Start-Process -FilePath “CloudiwayAgent.exe” -WorkingDirectory “$cdw” -Verb runAs |
3. Cross Tenant Laptop Migration Setup
The steps to configure the migration tool are as follows:
- Configure the permissions
- Configure the Cloudiway platform:
- Configure the API credentials
- Configure the global settings
- Configure the migration list
- Deploy the agent
3.1 Permissions
Cloudiway uses an Entra ID application for setting various properties in Intune. This chapter explains how to set and define the permissions.
You have 2 ways to create the Entry ID Application: Automatically or manually.
- If you create the connector and use the automatic mode, an Entra ID application is automatically created and deployed in your tenant.
- If you want a complete control over what is configured, you can create your application yourself. Follow this article for how to create manually your Entra ID application.
Additionally, one call (perforrmed at the target) is using the delegated mode (rather than Application Mode). This is a limitation in Microsoft API when setting the owner of the device in the Azure Autopilot List.
- If the serrvice account that you have defined in the target connector is global administratorr, you don’t need extra steps.
- If the service account is not global administrator, you need to grant him manually the delegated permission. For this, follow these steps:
Login to graph api explorer using the account defined in the tarrget connectorrr at https://developer.microsoft.com/en-us/graph/graph-explorer and click on Consent to Permission.
Add Directory.AccessAsUser.All
3.2 Cloudiway Credential APIS
The first thing to configure is the credentials that will be used by the local agents to connect to the Cloudiway platform.
For this, login to your primary account and enter your Cloudiway project that will hold your configuration.
Then, in the upper right, click on your Account Name, then Apis.
- Give it a name (for example Intune Migration)
- Select your project
- Give it an expiration date
- Enable Agent Tenant Migration
Click on Create and store the personal access token value for later use.
3.3 Global Settings
3.2 Global Settings
Navigate to Cross Tenant Migration / Local Agent.
Click on Global Settings.
Personal Access Token: once you have created your personal access token, reference it here.
Agent Version: Enable or disable Automatic Upgrade. Useful if you validate a given version and want to stay with this version all along the project.
Global Settings: Select what actions you want to be performed or not. Migration package appears only if you select Migrate Azure AD joined device. See next chapters.
3.4 User List
Navigate to Cross Tenant Migration / Devices/ User List
From the Menu, click on Migration /Get List.
This will discover your list of users and populate the migration list.
3.5 Agent Deployment
Note:
You have 2 choices for deploying the local agent:
- MSI deployment
- Click Once Deployment
Note: Click Once deployment doesn’t work for AD Joined devices. It only works for AD Registered devices. The reason is that migration of AD Joined devices require admin priviledges and they cannot be granted to a ClickOnce application deployed through Internet.
MSI Installation:
- In the global settings, download the installation script. You will deploy this script to end users using the method of your choice ( GPO deployment, Intune deployment, share the script on a network link, etc…)
Click Once Installation:
- From the user list, click Send Mail . This will send an installation link to the selected users.
- The user receive an installation link by mail. When he clicks on the link, it will install and start the agent.
When the user clicks on the link, he is redirected to the following page:
Installation is done through click Once. The link received by the user forces the execution through Microsoft Edge because not all browsers support Click Once by default and Microsoft Edge does.
Once the installation is complete, it runs automatically in the background and it is accessible in the systray of the computer.
3.6 Migration
From the userlist, select your users and click On Migration / Start
You can schedule the migration at the time of your choice or trigger it immediately.
3.7 Monitoring
You can monitor your migration progress from the Agent Device List.
From here you can see the status of migration of each computer, restart or stop them.
If you click on a Computer, you’ll get access to the migration logs.
You can get access to the same information from the User List.
If you click on the number of computers, it opens the list of computers and from here you can also start or stop the migration of a computer and access the migration logs.
4. Azure AD Registered Devices migration: What is done exactly?
Azure AD Registered :
It deletes the registry keys that are storing the information about AD registrations.
Office licenses:
The agent implements the following steps to reinitialize the Office licenses.
OneDrive Synchronization Agent:
The agent implements the following steps: Reset the OneDrive Sync Client
Outlook Profile
The outlook profile is deleted. After migration, end users can create a new outlook profile. It is very straightforwared and requires only 3 steps documented here:
https://support.microsoft.com/en-us/office/create-an-outlook-profile-f544c1ba-3352-4b3b-be0b-8d42a540459d
5. Azure AD Joined Devices migration: Configuration
As far as we are writing this documentation, joining a tenant cannot be done programmatically. But Microsoft provides an alternative solution. It can be done by installing a migration package.
In order to join automatically your new tenant, you will have to create a provisioning package using Windows Configuration designer and upload the migration package into the Cloudiway Global settings.
The steps include installing Windows Configuration Designer and create the package from a device already joined to the tenant.
Once you have created your provisioning package, you must upload it here.
6. Azure AD Joined Devices migration: What is done exactly?
Entra Unjoining : It triggers dsregcmd.exe /Leave
Intune Leave: It unregisters from the source Intune tenant.
Office licenses, OneDrive Synchronization Agent, Outlook Profile: Same than for AD Registered devices.
Profile Migration: Windows profile is migrated in order to be used by the target account.
Join Target tenant: Target tenant is joined by installing the migration package.
Join Target Intune: Laptop is registered to the new Intune tenant.
Backup BitLocker Key: BitLocker Key is backuped and uploaded into the new tenant. Migration of Bitlocker encrypted devices is supported.
7. When and how to perform the domain switch?
If you are doing a tenant to tenant migration and you have to migrate your domains to the target tenant, you’ll wonder when to transfer the domain name: before or after the migration of the devices to the new tenant.
The answer is that you can migrate the domain before or after the migration of the laptops.
If you migrate the laptops before the migration of the domain, you don’t have to do anything particular.
However, if you migrate the domains before triggering the migration of the laptops, the Cloudiway userlist will become incorrect as the source and target email addresses recorded in the Cloudiway user list will not match anymore the email addresses of your users in the source and target tenant.
You will have to run the Cloudiway switch domain task. This task will rewrite the Cloudiway user list to reflect your changes.
8. Troubleshooting
Cloudiway provides an extensive knowledge base with many resources, including common error messages, video guides, and downloads.
Please visit the knowledgebase here: 
Cloudiway Help Center – Cloud Migration & Coexistence
Support
Support tickets are opened through the platform.
Once logged in, go to your project and select Help, then Support. The chatbot will ask you a couple of questions and then open a support ticket. You will receive an email response to your ticket, and you can continue the support by email.
More information regarding our support program is available here: 
Free Technical Support During Cloud Migration | Cloudiway
9. FAQ
Which licenses doI need?
You need a global Cross-Tenant migration license. It is a yearly subscription plus one.
Please contact sales to get a complete quote.
