Entra ID tenant-to-tenant migration

Autopilot can move a Windows device from one Microsoft Entra ID tenant to another, taking the user’s profile with it. This is the tool for a customer acquisition, a divestment, or a tenant consolidation — the cases where the device stays but the identity behind it changes.

It is not a background task. The device leaves one tenant, joins another, restarts, and the user signs in with a different account. Plan it as a scheduled piece of work.

One reboot, and the user signs in differently afterwards

The device restarts mid-migration and is unusable while it runs. Afterwards the user must choose Other user at the sign-in screen and use their new account — not the one they have been using. Tell them before the day, or you will get the ticket instead.

What actually moves

Moves	Does not move
The user’s profile contents, copied via robocopy	The old profile — it stays on disk, deliberately
Personalization and theme settings	The device’s place in Windows Autopilot in the source tenant
OneDrive known-folder content, copied while sync is still active
BitLocker recovery keys, re-escrowed to the new tenant

The previous profile is left behind on purpose. It is the recovery path when something turns out to be missing afterwards.

Before you start

Autopilot runs a preflight check and reports every failure at once rather than one at a time, so you can fix them in a single pass. It checks fifteen conditions. The ones that most often stop a wave:

• The device is Hybrid Entra ID joined, or joined to an Active Directory domain. Neither is supported by this flow.
• The destination account is not set for that user.
• The device is registered in Windows Autopilot in the source tenant. It must be removed there first.
• BitLocker is on but the recovery key is not in the vault. Autopilot forces a key sync and only fails if the key is still missing afterwards — so a first failure here is often self-correcting on retry.
• The agent is out of date. Update it before migrating.
• Insufficient disk space. The message states how much more is needed. The profile is copied to a transition folder before being moved into place, so the device needs room for both copies at once.
• Third-party antivirus present, or a Web Account Manager error.
• Source and destination are the same user.

A failed preflight is not a dead end

Preflight failure sets the device to StartingError and the control panel resets it to Enabled so it can be retried once you have fixed the cause.

Which path the device takes

Autopilot decides based on where the device currently sits:

Current state	Path	What happens
Not joined to Entra ID	Join	Downloads and applies a provisioning package
Already in the destination tenant	SkipJoin	No provisioning package needed
Joined to a different tenant	DisjoinAndRejoin	Leaves the old tenant, then joins the new one — the true tenant-to-tenant case

All three converge on the same profile-migration work, so there is a single reboot regardless of path.

Running a migration

1. Enable migration for the device from the control panel. The device becomes eligible and preflight runs.
2. Confirm preflight passed. Only then do the Start Migration button and the Migration Ready notification appear to the user.
3. Start it, either from the control panel or by having the user click Start Migration in the tray application.
4. Phase 1 runs as the system account. It syncs BitLocker keys, cleans the old enrolment, leaves the old tenant, waits for the change to propagate, joins the new tenant, creates the destination profile, copies the source profile into a transition folder, and reboots.
5. The user signs in at the Windows sign-in screen using Other user and their new account.
6. Phase 2 runs as that user, moving the transition folder into the new profile.
7. Cleanup runs as the system account — re-registers the device against the destination organization, re-escrows the BitLocker key to the new tenant, and removes the working files.

Enabling migration does not show the user anything

Visibility of the button and notifications is controlled by a separate flag that is only set when preflight passes after an explicit opt-in. Background preflight checks — the ones that populate dashboard status — deliberately do not set it, so enabling migration for reporting purposes will not prompt users.

Tracking progress

Migration status runs through a defined sequence. Watch it in the control panel; the same values are written to the registry on the device.

Enabled → PreflightPassed → Started → CopyCompleted → DeviceReregistered → Completed

Status	Means
Enabled	Eligible, preflight not yet passed
PreflightPassed	All checks passed, ready to start
StartingError	Preflight failed — the message lists every failure
Started	Phase 1 in progress
CopyCompleted	Phase 2 finished copying; cleanup pending
DeviceReregistered	Device registered against the destination organization
Completed	Finished, working files removed
MigrationError	Unrecoverable failure — rollback is available
Rollback	An administrator has rolled the migration back

If the notification from Phase 2 to the system service is lost, a watchdog picks the migration up within fifteen minutes and completes the cleanup. A device sitting at CopyCompleted is not necessarily stuck — give it that long before intervening.

Rollback, and what it will not do

Rollback is available for devices in MigrationError. It inspects the device’s live state first and then takes one of four paths — which matters, because what it can undo depends on how far the migration got.

Situation	What rollback does
In the destination tenant, user signed in	Non-destructive cleanup only — removes the provisioning package, Defender exclusions and migration state. It will not delete the profile or leave the tenant, because someone is actively working on the device.
In the destination tenant, nobody signed in	Full rollback: removes the user from local groups, deletes the created profile, cleans enrolment and identity caches, leaves the tenant, and reboots.
In a workgroup (stranded)	The device left the old tenant but never joined the new one. Cleans up what it can, but the device must be re-enrolled manually.
Still in the source tenant	Phase 1 failed before the join changed. Minimal cleanup; the device is already where it should be.

Rollback does not restore the user's session

Rollback undoes the migration mechanics — join state, profile creation, working files. It does not put a part-migrated user back exactly as they were, and in the first case above it deliberately does very little. Treat it as damage limitation, not as an undo button, and confirm the device state before relying on it.

The stranded-workgroup case is the one to watch for: it means the disjoin succeeded but the join did not, so the device has no tenant at all. It needs manual re-enrolment regardless of what rollback reports.

When something fails

State lives in two registry locations on the device:

• HKLM\SOFTWARE\MSPControl\AzureAdMigration — status, and a per-user subkey holding the migration context
• HKLM\SOFTWARE\MSPControl\Migration — the flag controlling whether the user sees the migration prompts

The working copy of the profile sits in C:\MigrateData under a per-user folder while the migration runs, and is removed on completion or rollback. Finding it still present on a device is a reliable sign that a migration did not finish.

If Phase 1 fails, Autopilot attempts its own cleanup automatically before reporting the error: it removes the user from local groups, deletes the created profile and working folder, uninstalls the provisioning package, and leaves the tenant. Every step is best-effort, so check the outcome rather than assuming it succeeded.

Phase 2 errors are recorded on the device only

Phase 2 runs as the migrated user and has no server credentials, so a failure there is written to the registry but not reported to the control panel until the system service picks it up. If the panel looks stale for a device that has passed the reboot, check the device.

Related

• The Autopilot icon on your computer — what the user sees, including the Migration Ready prompt
• Install Autopilot — deploying the agent