ImmyBot Documentation

Appearance

Directory Migration ​

Overview ​

The Directory Migration Task is intended to move computers from one IDP to another. This will simplify your projects to move computers from Active Directory to Azure AD, or Workgroup to Active Directory, etc. You can find a compatibility matrix below. The task will also migrate the user profiles so that they can get back to work as soon as the migration is complete.

Prerequisites ​

An active ImmyBot subscription or trial

  • Admin access to your Microsoft Tenant.
  • Computers that are migrating cannot be Windows Home.
  • Custom Azure Permissions are set up and established for the tenant.
  • If you're using Enhanced AzureAD Join, you need to set up automatic Intune Enrollment
  • Do not have folder redirection set up to a server via GPO.
  • Ensure that all available updates are applied to the computer(s).

Deployment Planning ​

Data Protected by Windows DPAPI ​

Windows DPAPI (Data Protection API) user-based encryption binds encrypted data to the user's domain credentials. When a user's domain association changes during migration, any data encrypted with DPAPI will become inaccessible.

Affected Components:

  • Windows Hello (biometric authentication, PINs)
  • Browser stored passwords (Chrome, Edge, Firefox)
  • Saved credentials in Credential Manager
  • Application-specific encrypted data

Pre-Migration Requirements ​

  1. Enable Browser Sync: Users must sign into their browsers (Chrome, Edge, etc.) and enable synchronization before migration. This ensures passwords and other encrypted data are backed up to the cloud and can be re-downloaded after migration.

  2. Document Windows Hello Usage: Users will need to reconfigure Windows Hello features, including facial recognition, fingerprint readers, and PINs after migration is complete.

  3. Review Credential Manager: Any credentials stored in Windows Credential Manager should be documented, as these may need to be re-entered post-migration.

DEM User Creation ​

INFO

You only need to create DEM users if you're adding these computers to Azure.

Do not use a Global Administrator

From a security standpoint, we do NOT recommend using a global admin or existing user as a DEM.

AzureAD/Entra Join DEM User Instructions

  1. Create a DEM (Device Enrollment Manager) user in the Customer's Azure AD (Ex. dem@contoso.com)
  2. Assign the DEM user an Intune license (Intune Plan 1 is fine)
  3. Do NOT make the user a Global Admin (You shouldn't be bypassing MFA for Global Admins)
  4. Go to Roles and administrators and assign the Cloud Device Administrator or Cloud PC Administrator role
  5. Go to Device Enrollment Managers and make the user a Device Enrollment Manager
  6. Go to MFA Enrollment Settings and verify Require Multi-Factor Authentication to register or join devices with Azure AD is set to "No"
  7. MANUALLY LOGON AS THE USER AN INCOGNITO WINDOW
    • Verify a password change is not required
  8. Verify the user is not being prompted for MFA or MFA Registration

Parameters ​

ParameterDescription
DestinationDirectoryTypeChoose the destination directly type here. ImmyBot will use information available to it to get the computers to the target destination.
ProfileTypesToMigrateFor each profile on a machine, ImmyBot gets the SID of the associated user, and determines if that SID is Local, ActiveDirectory, or AzureAD. ImmyBot will not attempt to migrate the machine if it can't find a target account in the destination directory for every profile. You can avoid this by limiting the profiles using this parameter.
Workgroup MigrationsUse this if the computer(s) are in a workgroup. This will allow us to convert generic profiles into named profiles. (e.g., C:\Users\JFrontDesk actually belongs to jane.doe@company.com)
ProfileNamesToAvoidUse this to avoid migrating profiles that don't have a matching identity in the target AzureAD. (Like local admin accounts). Does a case insensitive "Contains" search. For example, C:\Users\ITAdmin would be excluded if you enter ITAdmin or admin.
FuzzyMatchEnable this to allow Immy to find usernames in the target directory based on profile foldername
IgnoreProfilesWithoutMatchingUsersNot recommended. This will suppress errors when Immy can't find a user to map a profile to.
SkipDomainControllerLookupUse this in a hostile takeover situation where you are unable to install an agent on the domain controller. The domain controller is used to verify that user is active and still exists (to prevent trying to map profiles to users for employees that are no longer with the company)
LimitToPrimaryUserThis only works in Hybrid Joined environments! We ask Azure AD for the OnPremiseSecurityIdentifier of the primary user. Then we only migrate the profile associated to that user. This is useful if you don't want to have to exclude all profiles that can't be mapped.
OAuthInfoLogin using a device enrollment manager account in the target tenant. This must be a DEM User.
CacheProvisioningPackage
SkipRegistryTestSkips registry validation and modification steps required for Azure AD Join. When not specified, the script performs checks for Azure AD Join-related registry settings, diagnoses potential issues with DSRegCmd and Intune enrollment states, and removes conflicting MDM policy enrollments.
ClearExistingEnrollmentsSet this to clear all existing enrollments before joining (including User/Workplace Joins).
UseEnhancedAzureADJoinUse certificate-based Azure AD Join instead of PPKG (BETA). Important: Test thoroughly before production use. Limitations: The following parameters are not supported with this option: • RequireInternetEnrollment • CacheProvisioningPackage

Supported Migrations ​

Source ↓ Destination ->WorkgroupAzureADActive Directory
WorkgroupUnsupportedSupportedSupported
AzureADUnsupportedUnsupportedSupported
Active DirectoryUnsupportedSupportedSupported

Troubleshooting ​

Azure Specific Issues ​

Join Issues ​

MFA Prohibiting AAD Joins (0xCAA2000C): ​

If your conditional access policies require MFA for all users, adjust the settings as follows:

  1. Exclude 'Microsoft Intune Enrollment' from the Cloud Apps requiring MFA.

  2. In Azure AD, create a Dynamic Security Group named 'Provisioning Packages'. Set its Dynamic Membership Rule to: user.userPrincipalName -startsWith "package_"

  3. Ensure that this 'Provisioning Packages' group is excluded from the MFA requirement.

Azure SyncFabric App ​

This cloud app needs to exist for the task to run properly. Many new environments do not have the app when they are created, so you will need to create them. Microsoft has also been known to occasionally remove the app from tenants that already have it.

To add the cloud app to the desired tenant, run the following script:

powershell
#Install-Module AzureAD #Uncomment this if you do not already have the AzureAD module installed
Import-Module AzureAD
Connect-AzureAd -TenantId contoso.com # Login as Global admin in customer tenant
New-AzureADServicePrincipal -AppId 00000014-0000-0000-c000-000000000000

⚠️ WARNING Replace the "contoso.com" domain with the one corresponding to your desired tenant.

Alternatively, there is a cloud task that can add Azure SyncFabric back to the tenant. It may require a custom app registration, though.

Known Error Codes ​

0xCAA10059 ​

The account (DEM) you are using to enroll the device does not have permissions to join devices to Azure AD. Add the account to 'Selected Users' or enable 'Allow All' users to join devices at:

Microsoft Entra ID - Device Settings

0xCAA50021 ​

The AAD Broker Plugin has been reset by us. You'll need to re-run the task if you see this.

0x8018000A ​

The device is already enrolled by a user. Re-run with 'ClearExistingEnrollments' set to 'True'.

0x801C0024 ​

The package_ AAD user associated with the PPKG was not found. Please run again with 'CacheProvisioningPackage' set to 'False' to generate a new package and user. This one shouldn't be an issue anymore, since we implemented retries that will generate a new package user if we are unable to create a token on the first try.

0x800700B7 ​

The provisioning package already exists. This may happen if you have executed the provisioning package earlier on this machine.

AADSTS90092 or AADSTS90202 ​

This tenant is missing the Microsoft.Graph.SyncFabric app (Microsoft stopped including it at some point in life)

Refer to Azure SyncFabric App

AADSTS240005 ​

To correct this, navigate to Intune - Roles

Assign the Cloud Device Administrator or Cloud PC Administrator role to the DEM account you are using and try again.

AADSTS50126 ​

The credentials are invalid OR the user has not been excluded from your Registration Campaign

Microsoft Entra Admin Center - Registration Campaign

AADSTS50055 ​

Reset the user's password via Microsoft Admin Center

AADSTS240003 ​

This issue might be related to Multi-Factor Authentication (MFA) being enabled for $Username.

It's recommended to disable MFA for this account or consider using OAuth for a more secure authentication method.

AADSTS90002 ​

This error can typically be resolved by using the OAuth flow instead of the username/password flow.




Document information

Author: Mark Gomez and Brandon Ritchey
Date Published: 11/14/2025
Date Revised: N/A
Version Number: 1.0