Create a Device Level Windows AD Migration Policy
Use the AD Migration policy to migrate Windows devices from Active Directory (AD) or Entra ID management toward JumpCloud. You configure the policy in the JumpCloud Admin Portal, bind it to devices, device groups, or policy groups, and the agent runs the migration at a scheduled local time (or, for Self-Service Leave Domain, when an end user starts it).
Migration Mode controls the outcome:
- Remain in Domain — Optionally binds eligible users and unenrolls non-JumpCloud Mobile Device Management (MDM). The device stays domain-joined or Entra-joined. No profile conversion and no reboot required on success.
- Leave Domain — Optionally binds and migrates eligible users to local accounts, unenrolls non-JumpCloud MDM, leaves the domain or Entra join, joins a workgroup, and reboots on success.
A successful migration freezes that policy configuration for the device. Edits after SUCCESS are a no-op. To run again with new settings, unbind and rebind the policy, or bind a new policy.
Prerequisites
- Access to the JumpCloud Admin Portal with permission to create and bind device policies.
- Organization grant for the restricted AD Migration policy template (
ad_device_migration_windows).- The template is Early Access and is not enabled for every organization by default.
- Windows devices that are AD-joined, Entra-joined, or hybrid-joined, with the JumpCloud agent installed.
- Supported OS editions from the policy template: Windows 10 or 11, Pro, Enterprise, or Education.
- For automatic user binding or migration: JumpCloud users whose directory identifier matches a profile on the device.
- AD (on-prem or hybrid): Security Identifier (SID), populated via Active Directory Integration (ADI) or the JumpCloud API.
- Entra ID: Object ID, populated via the Entra (Microsoft 365) integration.
- See Agent Support for On-Premise Active Directory and Entra ID Joined Windows Devices.
Considerations
- Eligible users are matched automatically. You do not manually map usernames for automatic binding.
- The policy does not preview SID or Object ID matches before it applies. Eligibility is evaluated on the device when the migration runs.
- There is no dedicated migration dashboard. Use policy results and Directory Insights events (
policy_resultandassociation_change) to monitor outcomes. - Pre-existing bound and eligible users always stay bound. For Leave Domain, those users always migrate, regardless of Users to migrate.
- Pre-existing bound eligible users are included in the top-ranked calculation for One eligible user, and in whether a One eligible user or All eligible users run can succeed.
- Windows Credential Manager credentials are not migrated to a new local account. Windows Hello and other credentials encrypted with DPAPI must be reconfigured on the new account after Leave Domain.
- If more than one AD Migration policy targets the same device, only one migration runs at a time.
note
This is a device level policy that applies system-wide to the device and all of its users. You can bind this policy to individual devices or device groups. For policies that apply to a specific user's profile across devices, see Get Started: Policies and the Learn More section of this article.
Glossary
| Term | Description |
|---|---|
| Eligible | The JumpCloud user's directory identifier matches a profile on the device (SID for AD/hybrid; Object ID for Entra). |
| Migration Mode | Remain in Domain optionally binds users and leaves MDM. Leave Domain optionally binds users, migrates users, leaves MDM, and leaves the domain or Entra join. |
| Domain/Entra joined | The device is joined to an on-prem domain or an Entra tenant. Either makes the device eligible for the policy to run. |
| Pre-existing bind | A JumpCloud user-to-device association already exists when the policy executes. |
| Top-ranked | The chosen profile among eligible users when One eligible user is selected. The largest profile signed into within the last 30 days wins. If there are no sign-ins in the last 30 days, the largest profile is selected. |
| Migrated (Leave Domain) | A local account is created from the JumpCloud username, and the AD or Entra profile is converted to it. |
| Orphaned | AD or Entra profiles that are not migrated to local accounts during Leave Domain. |
| Reverting users | Migrated users are converted back to domain or Entra profiles, and the newly created local account is deleted. |
Policy Settings
| UI setting | Applicable modes | Values | Description |
|---|---|---|---|
| Migration Mode | All | Remain in Domain, Leave Domain | Selects Light Migration (remain) or Full Migration (leave). |
| Full migration type | Leave Domain | Managed, Self-Service | Managed runs on a schedule. Self-Service waits for an end user to start migration from the JumpCloud tray app. |
| Schedule | Remain; Leave Domain with Managed | Time input (device local time) | Time when the policy runs. Automatic failure retries also occur at this time. Example: 8:00 AM on the device runs at 8:00 AM in the device timezone, not the admin timezone. |
| Users to bind / Users to migrate | Remain; Leave Domain with Managed | One eligible user, All eligible users, No users | Controls which users are newly bound (and, for Leave Domain, migrated). All existing bound users are always kept bound. For Leave Domain, existing bound users with a profile on the device always migrate. |
| Workgroup Name | Leave Domain | Text (1–15 characters) | Name of the Windows workgroup for migrated accounts after leave. |
Users to Bind or Migrate Examples
When No users is selected and the device already has bound, eligible users:
- Remain: no new binds; existing bindings are kept; MDM cleanup still runs.
- Leave Domain: no new binds; all bound users with a profile on the device are still migrated.
Creating the Policy
- Log in to the JumpCloud Admin Portal.
Important
If your data is stored outside of the US, check which login URL you should be using depending on your region. If your organization uses LDAP, RADIUS, or requires firewall allow list configuration, the Fully Qualified Domain Names (FQDNs) will also be region specific. See JumpCloud Data Centers for the URLs, FQDNs, and IP addresses.
- Go to Device Management > Policy Management.
- Click +Add New.
- Select Device Policy.
- Select the Windows tab.
- Search for and select AD Migration, then click configure.
- (Optional) In Policy Name, enter a unique name, or keep the default.
- (Optional) In Policy Notes, enter deployment or testing notes.
- Under AD Migration Settings, choose Migration Mode.
- Configure mode-specific settings:
- Remain in Domain: set Users to bind and Schedule.
- Leave Domain: set Full migration type, Workgroup Name, and (for Managed) Users to migrate and Schedule.
- (Optional) Select the Policy Groups tab and choose one or more policy groups.
- Select the Device Groups or Devices tab and choose targets.
tip
To target only joined devices, create a dynamic device group with a rule for AD joined or Entra joined, then bind the policy to that group.
- Click save. Confirm if prompted.
For Managed modes, the assignment shows PENDING until the local schedule fires.
User Outcomes
A user's outcome depends on mode, selection, eligibility, and existing binding. Remain only binds. Leave Domain always migrates bound users that have a profile on the device, whatever the selection.
Remain in Domain (Managed)
| Profile on the device | One eligible user | All eligible users | No users |
|---|---|---|---|
| Eligible, not bound, top-ranked | Newly bound. bind: completed, migrate: skipped | Newly bound. bind: completed, migrate: skipped | Untouched |
| Eligible, not bound, not top-ranked | Untouched | Newly bound. bind: completed, migrate: skipped | Untouched |
| Eligible, already bound, not top-ranked | Binding kept. Not listed in policy results | Binding kept. bind: completed, migrate: skipped | Binding kept. Not listed in policy results |
| Eligible, already bound, top-ranked | Binding kept. bind: completed, migrate: skipped | Binding kept. bind: completed, migrate: skipped | Binding kept. Not listed in policy results |
| Not eligible, not bound | Untouched | Untouched | Untouched |
| Not eligible, pre-existing bind | Untouched | Untouched | Untouched |
Leave Domain (Managed)
| Profile on the device | One eligible user | All eligible users | No users |
|---|---|---|---|
| Eligible, not bound, top-ranked | Newly bound and migrated. bind: completed, migrate: completed | Newly bound and migrated. bind: completed, migrate: completed | Orphaned |
| Eligible, not bound, not top-ranked | Orphaned | Newly bound and migrated. bind: completed, migrate: completed | Orphaned |
| Eligible, already bound (any rank) | Migrated. bind: completed, migrate: completed | Migrated. bind: completed, migrate: completed | Migrated. bind: completed, migrate: completed |
| Not eligible, not bound | Orphaned | Orphaned | Orphaned |
| Not eligible, pre-existing bind | Orphaned | Orphaned | Orphaned |
note
Pre-existing bound users stay bound and always migrate on Leave Domain.
Device Outcomes
| Mode | Users | Device has | Policy result | errorCode | MDM | Domain/Entra | Reboot |
|---|---|---|---|---|---|---|---|
| Remain | No users | Any profiles | SUCCESS | None | Unenrolled | Stays joined | No |
| Remain | One eligible user | 1 or more eligible profiles | SUCCESS; top-ranked eligible user bound | None | Unenrolled | Stays joined | No |
| Remain | All eligible users | 1 or more eligible profiles | SUCCESS; every eligible user bound; ineligible users skipped | None | Unenrolled | Stays joined | No |
| Remain | One or All | Pre-existing profile that is both bound and eligible | SUCCESS | None | Unenrolled | Stays joined | No |
| Remain | One or All | Profiles exist, none eligible | FAILED; retries next day at scheduled time | USER_NOT_ELIGIBLE | Untouched | Stays joined | No |
| Remain | One or All | No domain profiles | FAILED; retries next day at scheduled time | COLLECT_FAILED | Untouched | Stays joined | No |
| Leave | No users | No bound users with a profile | SUCCESS | None | Unenrolled | Leaves | Yes |
| Leave | No users | 1 or more bound users with a profile | SUCCESS; bound users migrated | None | Unenrolled | Leaves to workgroup | Yes |
| Leave | One eligible user | 1 or more eligible or bound users | SUCCESS; bound users plus top-ranked user migrated | None | Unenrolled | Leaves to workgroup | Yes |
| Leave | All eligible users | 1 or more eligible or bound users | SUCCESS; bound and eligible users migrated; ineligible orphaned | None | Unenrolled | Leaves to workgroup | Yes |
| Leave | One or All | No eligible users | FAILED; retries next day at scheduled time | USER_NOT_ELIGIBLE | Untouched | Stays joined | No |
| Leave | Any | One user's migration fails | FAILED. Stops at that user and reverts users completed earlier in this attempt. Binds made in this attempt stay. Retries next day at scheduled time | Untouched | Stays joined | No | |
| Leave | Any | Leave domain fails after users migrated | FAILED. Migrated users stay migrated. Binds are kept. | Unenrolled | Stays joined | No |
Workarounds for Common Device Failures
No eligible (SID-matched) users for One or All
- Change Users to bind / Users to migrate to No users if you did not intend to bind or migrate users.
- Add a matching SID (or Entra Object ID) to a JumpCloud user that matches a profile on the device.
Leave Domain: a user migration fails
- Change the user target to No users if no users were intended.
- Log off all users and reboot the device before the next scheduled retry.
Leave Domain: leave fails after users are migrated
- Manually leave the domain with a script or command.
- Unbind the policy from the device to trigger a revert of migrated users back to domain profiles.
Device Preconditions
| Device condition | Remain in Domain | Leave Domain |
|---|---|---|
| Device is not domain or Entra joined | Fails | Fails |
| AD joined, Entra joined, or hybrid | Runs | Runs |
| Intune MDM but not Entra joined (BYOD) | Fails | Fails |
| No MDM enrollment | Runs; skips MDM unenrollment | Runs; skips MDM unenrollment |
| JumpCloud MDM | Runs; skips MDM unenrollment | Runs; skips MDM unenrollment |
| Third-party MDM (Intune, others) | Runs; unenrolls MDM | Runs; unenrolls MDM |
| Local account already exists with the target JumpCloud username | Fails; other newly bound users are kept; the clashing user fails to bind | Fails; any migrated users are reverted |
| User signed in or profile hive loaded | Does not apply | Runs. The migration tool logs the user off before converting. If the profile still cannot be unloaded, the run fails (MIGRATE_FAILED) and users converted earlier in the attempt are reverted. |
| User cannot be signed out or profile hive cannot be unloaded | Does not apply | Fails for that user; other migrated users are reverted |
| User converted in an earlier attempt | Does not apply | User is skipped |
note
Entra-joined devices can be joined to a workgroup and still be eligible for migration.
Lifecycle
A successful migration freezes the policy configuration. Edits after SUCCESS are a no-op, including changing from Remain to Leave. Failed runs retry at the next scheduled time on the next day.
| Event | Migration state | What happens | Result posted |
|---|---|---|---|
| Policy assigned | None | Waits for scheduled time | PENDING |
| Same config delivered again | Any | No-op | None |
| Admin edits the policy | Waiting for scheduled time | New config replaces the old one | PENDING |
| Admin edits the policy | During migration run | Edit ignored | None |
| Admin edits the policy | Success | Edit ignored. Unassign and reassign to run with the new config | None |
| Admin edits the policy | Failed | New config replaces the old one | PENDING |
| Policy unassigned | Waiting for scheduled time | Policy uninstalled | UNINSTALL_SUCCESS |
| Policy unassigned | Success | Uninstalled; no impact on users or the completed migration away from AD | UNINSTALL_SUCCESS |
| Policy unassigned | Failed | Uninstalled. Before leave domain completes, migrated users are reverted | UNINSTALL_SUCCESS |
| Policy unassigned | Run in progress | Uninstalled. Before leave domain completes, migrated users are reverted | UNINSTALL_PENDING |
| Duplicate policy | Run in progress | Duplicate waits until it can run at its schedule | DUPLICATE |
| Duplicate policy | Failed | Failed policy continues to retry at its schedule. The duplicate may also run depending on schedule and configuration | DUPLICATE, SUCCESS, or FAILED |
| Duplicate policy | Success | Duplicate runs at its scheduled time. Results depend on both policy configurations | SUCCESS or FAILED |
Changing from Remain to Leave After Success
If a device already completed Remain in Domain and you want Leave Domain:
- Unbind the policy, change Migration Mode to Leave Domain, then rebind, or
- Bind a new Leave Domain policy to the device.
The same pattern applies to any setting change after a successful run.
Primary User Assignment
Primary User assignment considers only users newly bound by the run. Pre-existing bound, non-primary users are ignored and are not newly assigned as Primary User.
| Users newly bound by the run | Pre-existing eligible user bound | Primary User before the run | Result |
|---|---|---|---|
| Exactly 1 | Yes or No | None | Newly bound user assigned as Primary User |
| Exactly 1 | Yes or No | Already set | Unchanged |
| 2 or more | Yes or No | Any | Unchanged |
| 0 | Yes or No | Any | Unchanged |
Self-Service (Leave Domain)
When Full migration type is Self-Service, the signed-in user starts migration from the JumpCloud tray app.
| User who clicks Start Migration | Other eligible, bound users with a profile | Outcome |
|---|---|---|
| Pending | Any | Tray app shows the Directory Migration section and a badge or reminder |
| Eligible, not bound | None | That user is bound and migrated |
| Eligible, not bound | 1 or more | That user is bound and migrated, and bound users are migrated too |
| Eligible, already bound | Any | That user is migrated, and bound users are migrated too |
| Not eligible (no SID match) | Any | Tray shows a not-eligible message and blocks the run |
Monitoring Migration Status
- Go to Device Management > Policy Management.
- Select the AD Migration policy.
- Open the Status tab.
- Click view for a device to open the last result log.
Directory Insights also records policy_result and association_change events.
Best Practices
Target only joined devices with a dynamic group
- Create a new device group.
- Set membership control to Dynamic.
- Add a rule for AD joined or Entra joined.
- Add any other relevant conditions.
- Bind the AD Migration policy to that group.
Coexist now, fully migrate later
- Bind a Remain in Domain policy to the device group.
- Let the policy succeed. The device stays joined; users are bound as configured.
- Later, bind a Leave Domain policy to the same group (or unbind/rebind after changing settings).
After Leave Domain
Plan for credentials that do not migrate: Windows Credential Manager, Windows Hello, and other DPAPI-protected credentials must be reconfigured on the new local account.
Was this information helpful?