How To: Windows Profile Migration To Entra ID Using PowerShell

Windows Profile Migration

Summary

This article documents migrating a local Windows user profile to a new Microsoft Entra ID account on the same machine. The primary focus is on developing a detailed, PowerShell-driven methodology as a viable alternative to commercial, third-party tools such as Profwiz. The inherent complexity of this task stems from the need to re-associate an existing user profile with a new security context. This is not a simple data transfer but a precise, low-level reconfiguration of core Windows components, including the file system and the registry.

The analysis concludes that a “PowerShell-only” solution is a misnomer. A robust and reliable scripted approach must orchestrate a hybrid workflow, leveraging native PowerShell cmdlets in conjunction with essential command-line utilities like reg.exe, icacls.exe, and takeown.exe. The limitations of PowerShell’s built-in providers necessitate this approach for critical actions, such as loading and unloading another user’s registry hive.

A manual, scripted migration provides granular control and eliminates licensing costs associated with commercial software. However, it is a high-risk operation that lacks built-in transactional safety and a “rollback” feature, making it suitable for one-off tasks or for IT professionals who require a deep, auditable understanding of the process. For large-scale, enterprise-level deployments, commercial tools designed for high reliability and ease of use remain the preferred solution. The scripted method, while powerful and customizable, demands a high degree of technical expertise and meticulous execution to mitigate the risk of data corruption and system instability.

The PowerShell-Driven Migration Methodology

Architectural Overview

The scripted migration process is an in-place, multi-stage operation. It is not a data copy or backup-and-restore. Instead, it is a surgical procedure that re-maps the security context of an existing profile to a new user account. The process can be broken down into three primary phases: profile re-association, file system permission re-ACLing, and finalization. Each phase must be executed in a specific order to prevent data corruption and ensure a seamless transition for the end-user. The script must be run from a separate administrative account that is neither the source local user nor the target Entra ID user.

Pre-Migration Prerequisites and Planning

Before any script is executed, several critical prerequisites must be met to ensure the safety and success of the migration.

1. Backups: A full backup of the user’s profile folder is mandatory. The migration process carries a high risk of data corruption, and a reliable backup is the only way to recover from an unrecoverable state.
2. Local Administrator: An administrative account that is not the source or target user must be used to perform the migration. This is essential to prevent file locking and to ensure the script has the necessary permissions to modify registry hives and file system ACLs.
3. Entra ID User Creation: The target Entra ID user account must be created and licensed in the tenant beforehand. This step can be automated using PowerShell cmdlets like New-MgUser or New-EntraUser.
4. PowerShell Environment: The Microsoft.Entra or Microsoft.Graph PowerShell modules must be installed and connected to the Entra ID tenant with appropriate permissions, such as User.ReadWrite. All. The script execution policy may also need to be temporarily adjusted.

The Core PowerShell Scripts and Workflows

Phase 1: Profile Enumeration and Disassociation

The first phase involves identifying the local profile to be migrated and obtaining its associated Security Identifier (SID). This information is necessary to locate and modify the correct registry key. The Win32_UserProfile WMI class or the Get-LocalUser cmdlet can be used to programmatically find a user’s SID. Once the SID is identified, the script can locate its corresponding subkey under the

ProfileList registry key.

[PowerShell]
# SCRIPT 1: Profile Enumeration and SID Discovery
# This script must be run with elevated privileges.
# Replace 'LocalUserName' with the actual local user's account name.

# Get the local user object and its SID
$localUser = Get-LocalUser -Name 'LocalUserName'
if ($localUser) {
    $sourceSID = $localUser.SID.Value
    Write-Host "Found local user '$($localUser.Name)' with SID: $($sourceSID)" -ForegroundColor Green
} else {
    Write-Host "Error: Local user 'LocalUserName' not found." -ForegroundColor Red
    return
}
# Find the registry key for the local user's profile
$profileListPath = "HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList"
$sourceProfileKey = Get-ItemProperty -Path "$profileListPath\$sourceSID"
if ($sourceProfileKey) {
    $profilePath = $sourceProfileKey.ProfileImagePath
    Write-Host "Found source profile path: $($profilePath)" -ForegroundColor Green
} else {
    Write-Host "Error: Profile registry key not found for SID: $($sourceSID)" -ForegroundColor Red
    return
}

Phase 2: Registry Reassignment and Permission Management

This is the most critical and complex phase of the migration. It involves manipulating the user’s registry hive (NTUSER.DAT) to assign it to the new Entra ID account’s SID. The PowerShell Registry provider is limited and cannot directly load a disconnected registry hive from disk. Therefore, the script must rely on a hybrid approach, using PowerShell to call the native reg.exe utility.

The process requires loading the target user’s hive under a temporary mount point in HKEY_USERS while logged in as the administrative account. The script must then use PowerShell’s Set-Acl cmdlet to grant the new Entra ID user’s SID full control over the newly loaded hive. This is a crucial step to ensure the new user can correctly access their profile’s registry settings upon login. Finally, the script must unload the hive to finalize the changes and release any file locks.

After re-ACLing the hive, the script must also update the ProfileList registry key to point the old profile folder to the new Entra ID user’s SID. This step, combined with the file system re-ACLing in the next phase, is what allows the new account to successfully load the existing profile.

[PowerShell]

# SCRIPT 2: Registry Reassignment
# This script assumes a variable $sourceSID and $targetSID are already defined.
# It also assumes you have created the target user account in Entra ID and obtained its SID.

# Path to the NTUSER.DAT file for the source profile
$hivePath = "$profilePath\NTUSER.DAT"
$tempHiveName = "MigrateTemp"
Write-Host "Loading registry hive from $($hivePath)..."
try {
    # Call reg.exe to load the hive under a temporary key
    reg.exe load "HKU\$tempHiveName" $hivePath | Out-Null
    Write-Host "Hive loaded successfully." -ForegroundColor Green
} catch {
    Write-Host "Error loading hive: $($_.Exception.Message)" -ForegroundColor Red
    return
}
# Re-ACL the loaded registry hive for the new user's SID
try {
    Write-Host "Applying permissions for new SID '$targetSID'..."
    # Get the ACL object for the loaded hive
    $acl = Get-Acl "HKU:\$tempHiveName"
 
    # Create a new access rule for the target SID
    $registryAccessRule = New-Object System.Security.AccessControl.RegistryAccessRule(
        $targetSID,
        "FullControl",
        "ContainerInherit, ObjectInherit",
        "None",
        "Allow"
    )
    # Add the new access rule to the ACL
    $acl.AddAccessRule($registryAccessRule)

    # Apply the modified ACL to the loaded hive
    $acl | Set-Acl -Path "HKU:\$tempHiveName"
    Write-Host "Permissions applied successfully." -ForegroundColor Green
} catch {
    Write-Host "Error applying permissions: $($_.Exception.Message)" -ForegroundColor Red
    # Unload the hive in case of failure to prevent it from being locked
    reg.exe unload "HKU\$tempHiveName" | Out-Null
    return
}
# Unload the registry hive
Write-Host "Unloading hive..."
try {
    reg.exe unload "HKU\$tempHiveName" | Out-Null
    Write-Host "Hive unloaded successfully." -ForegroundColor Green
} catch {
    Write-Host "Error unloading hive: $($_.Exception.Message)" -ForegroundColor Red
    return
}
# Update the ProfileList key to use the new SID and profile path
$targetProfileKey = "HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList\$targetSID"
Set-ItemProperty -Path $targetProfileKey -Name "ProfileImagePath" -Value $profilePath

Phase 3: File System Permission Re-ACLing

The third phase ensures the new Entra ID user has full control over the file system folder of their profile. Without correct NTFS permissions, the user will be unable to access their desktop, documents, or application data, leading to a dysfunctional environment.

The script must first take ownership of the profile folder, as the current administrative user may not have the rights to modify the ACLs. Once ownership is established, the script can grant the new Entra ID user’s SID

Full Control over the entire profile directory, including all subfolders and files.

This can be accomplished using the native icacls.exe utility, which is highly effective for recursive and complex permission changes. Alternatively, PowerShell’s

Get-Acl and Set-Acl cmdlets can be used, though the icacls command is often favored by sysadmins for its simplicity in this specific use case.

[PowerShell]

# SCRIPT 3: File System Permission Re-ACLing
# This script assumes $profilePath and $targetSID are defined from previous steps.

Write-Host "Taking ownership of the profile folder..."
try {
    # Use takeown.exe to take ownership of the folder and its contents
    # /R for recursive, /A to give ownership to the Administrators group
    takeown.exe /F "$profilePath" /R /A /D Y
    Write-Host "Ownership successfully taken." -ForegroundColor Green
} catch {
    Write-Host "Error taking ownership: $($_.Exception.Message)" -ForegroundColor Red
    return
}
Write-Host "Applying Full Control permissions for new SID on the profile folder..."
try {
    # Grant the new user's SID Full Control over the entire profile directory
    # /T for recursive, /C to continue on errors, /Q to suppress success messages
    icacls.exe "$profilePath" /grant "$targetSID`:(OI)(CI)F" /T /C /Q
    Write-Host "Permissions applied successfully." -ForegroundColor Green
} catch {
    Write-Host "Error applying permissions: $($_.Exception.Message)" -ForegroundColor Red
    return
}

Phase 4: Finalization and Entra ID Join

The final step is to join the device to Entra ID. This is typically a manual or semi-automated process. After the device is joined, the user can log in with their Entra ID credentials for the first time. Because the scripted migration has already re-associated the profile, the operating system will link the new login to the existing profile folder and registry hive, providing a seamless transition with all settings, applications, and data intact.

Comparative Analysis of Migration Tools

The Profwiz Methodology

Profwiz, developed by ForensiT, is a powerful and widely-used commercial tool for in-place user profile migration. The core of its value lies in its automation of the complex manual and scripted steps outlined in this report. Profwiz does not move or copy data; it reconfigures the existing profile by re-ACLing the file system and editing the necessary registry keys. It is designed to handle this process in a single, transactional operation, minimizing the risk of a failed migration.

A key component of Profwiz’s success is its ability to handle peripheral, but crucial, steps. It can deploy Microsoft Windows Configuration Designer provisioning packages to automatically join a device to Entra ID, and it can re-register Windows AppX applications, which often break during a profile change. This automation and built-in error handling are the primary reasons why many IT professionals view it as a reliable solution for enterprise-scale deployments.

Scripted Migration vs. Commercial Tools

The choice between a scripted, manual approach and a commercial tool is a trade-off between cost, complexity, and risk. A meticulously constructed PowerShell script can replicate the core functionality of a tool like Profwiz, but it requires a deep understanding of Windows internals and is prone to human error. The transactional safety and comprehensive, purpose-built features of commercial software are a direct response to the inherent fragility of the manual process.

A manual, scripted migration is a valid and powerful option for specific use cases. It is ideal for a one-off migration where an administrator needs to understand every detail of the process, or in a highly customized environment where a commercial tool might not provide the necessary flexibility. However, for a large number of devices, the scripted approach’s lack of a reliable “rollback” and its reliance on external commands make it a high-risk solution. Conversely, tools like Profwiz offer a “set it and forget it” experience, making them invaluable for large-scale, automated deployments.

Table 2: Scripted Migration vs. Automated Tool Comparison

Advanced Troubleshooting and Common Post-Migration Issues

 “User Profile Service failed the logon” Error

This is the most common and frustrating error encountered during a failed profile migration. It occurs when the ProfileList registry key points to a profile folder that the user cannot access, either because of incorrect NTFS permissions or a corrupted registry hive. The most common cause is a failure to properly re-ACL the file system and the

NTUSER.DAT hive. The operating system, unable to reconcile the user’s new SID with the profile’s permissions, creates a temporary profile or fails the logon entirely.

Diagnosis and Remediation:

• Locate the Problematic Key: Boot into Safe Mode or log in with a separate administrative account. Open the Registry Editor and navigate to HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList. Look for a key that ends with .bak, which indicates a corrupted or failed profile load attempt.
• Correcting Permissions: The primary solution is to correct the file and registry permissions for the new user’s SID. Use the
  icacls command from Phase 3 to grant the new SID Full Control of the profile folder.
• Fixing the Registry: If the registry key has a .bak extension, rename it to remove the extension. Inside this key, ensure that the ProfileImagePath value is correct. If the RefCount value is not 0, change it to 0, and ensure the State value is also 0.

Application-Specific Challenges

After a successful profile migration, certain applications, particularly those from Microsoft 365, may experience authentication issues. This is due to cached credentials, stale identity tokens, or browser cookies that are linked to the old user account’s SID.

Remediation:

• Clear Credential Manager: The user’s credential cache must be cleared. This can be done manually in the Windows Credential Manager by removing entries that begin with “Microsoft,” “MS,” or “Outlook”.
• Remove Registry Keys: Specific registry keys related to Office identity may also need to be deleted from the user’s hive. These keys are located under HKEY_CURRENT_USER\Software\Microsoft\Office\15.0\Common\Identity\Identities and HKEY_CURRENT_USER\Software\Microsoft\Office\15.0\Common\Identity\Profiles.

Browser Profiles: For browsers like Chrome or Edge, the user may need to sign out and back in. In some cases, a new browser profile linked to the Entra ID account may need to be created, and data from the old profile manually re-imported.

Table 3: Common Errors and Remediation

Conclusions and Recommendations

The analysis confirms that a comprehensive, PowerShell-driven migration of a local user profile to an Entra ID account is technically feasible. However, it is a complex, high-risk, and labor-intensive process that requires a hybrid approach utilizing both PowerShell cmdlets and native command-line utilities. The fundamental challenge lies in the meticulous re-association of a profile’s file system and registry components with a new security identifier. The process is not a simple data transfer but a surgical operation on the operating system’s core architecture.

For a systems administrator or IT professional tasked with a limited number of migrations (e.g., 1-10 devices), the scripted methodology detailed in this report provides a free, educational, and highly customizable alternative. It offers unparalleled control and a deep understanding of the migration process.

For large-scale deployments or for organizations prioritizing efficiency and reliability, commercial tools such as Profwiz are the recommended solution. These tools abstract the underlying complexity, providing transactional safety, built-in error handling, and automation for peripheral tasks like application re-registration. While they come at a cost, the reduction in labor, risk, and potential for post-migration help desk calls provides a significant return on investment. The Microsoft-supported User State Migration Tool (USMT) is another viable option for large deployments, particularly in PC refresh scenarios, but it is not intended for single machine migrations requiring end-user interaction.

In all migration scenarios, thorough pre-migration planning, including comprehensive data backups and a well-defined troubleshooting plan, is non-negotiable. The adage “measure twice, cut once” is never more relevant than in the high-stakes environment of user profile management.