Migrate workgroup-joined Windows endpoints to AD or Entra Joined while preserving the user's local profile. This guide covers both how the migration actually works under the hood and a scripted, RMM-driven bulk process for doing it at scale. A manual single-machine walkthrough is included as an appendix for anyone who prefers to roll their own automation.

Migration Scripts: https://github.com/PowerSyncPro/MigrationAgent/tree/main/BulkWorkgroup

This guide is designed for environments where:

• Devices are not joined to an Active Directory domain or Microsoft Entra
• You have remote management of the machines (RMM, etc.)
• You need to preserve the user's local profile

Use Case

You have standalone Windows machines (workgroup only) and need to migrate them to AD or Entra Joined without reimaging, Autopilot, or user-profile disruption.

Limitations

• Only one local profile per device can be migrated.
  • If multiple local profiles exist, you must designate which one to migrate.
  • Additional users may sign in post-migration, but their prior local profiles will not be automatically migrated. The translation table can be enhanced with more entries if needed, but this guide covers a single user per device.
• Workstations must be licensed with Windows 10 / 11 Professional or higher.
  • Windows Home editions do not support AD or Entra join.
  • Verify this using your RMM / management tools before attempting migration.
• Devices need line of sight to the target environment (AD on the LAN, or the internet for Entra) to complete the join.
• As with any device migration, confirm the machines will meet device compliance and conditional access requirements with your device management and identity teams (or have an exclusion in place).

How the Migration Works (Background)

PowerSyncPro Migration Agent (PSP MA) was designed around AD-joined and Hybrid devices, where the source identity, target identity, and device object are all easy to look up. Workgroup machines don't fit that model cleanly, and this process exists to fill the gaps. Understanding why each step exists makes it much easier to adapt this to your own tooling.

The migration must overcome the following challenges:

1. The local user's SID is unknown to PSP. Without it, the agent can't build the translation mapping it uses to update permissions on the registry and file system.
2. The target user's SID is also unknown. PSP needs to know which Entra or AD identity the local profile is being migrated to. For Entra, this means converting the user's Object ID into a SID-format string (S-1-12-1-…).
3. PSP scopes machines into batches from a source AD. Workgroup devices have no AD object, so PSP has nothing to put into a batch. The workaround is to create a dummy AD computer object that matches the workstation's hostname, purely so PSP has something to scope and register against.
4. Runbooks are coordinated by the workstation itself. The agent talks to the PSP server only to fetch the runbooks assigned to it. Because PSP can't push the local→target SID mapping into a workgroup machine through normal sync, the translation table has to be placed manually in the correct runbook directory on the local machine before migration runs.
5. Only the currently logged-in user is migrated unless you extend the translation table. Other local profiles will remain on the device but won't be re-permissioned to a target identity.

The bulk process below automates all five of these steps. The manual appendix walks through them one machine at a time so you can see exactly what is happening if you need to script it differently.

Prerequisites

Setup Steps

Create the Migration CSV

Create a file named mig_db.csv with these headers:

computer_name,local_username,target_upn,target_identity

Field definitions:

You may use the blank CSV provided in the repository.

Populate this CSV with the machines and local username combinations you wish to migrate. When the deployment script runs on a workstation, it checks whether the host is listed in this CSV. If it is, it confirms the specified local user exists, then uses that information to build the translation table.

Populate User Identity (SID or GUID)

For Entra

On a machine with Microsoft Graph PowerShell installed, run:

.\1-Lookup_User_GUID_or_SID.ps1 -CsvPath .\mig_db.csv -TargetType Entra

You will authenticate against the target Entra tenant. The script resolves each UPN to its Entra Object ID and writes the value into target_identity in the CSV.

This can also be populated manually from the Entra Portal if you'd rather not use the script.

For AD

On a machine with a connection to the target Active Directory, run:

.\1-Lookup_User_GUID_or_SID.ps1 -CsvPath .\mig_db.csv -TargetType AD

The script will look up each UPN listed in the CSV in Active Directory and write the SID to the CSV under target_identity. The migration script uses this to build the translation table mapping the local user to the domain user.

This can also be populated manually from Active Directory Users and Computers (shown under objectSID in the Attribute Editor).

Populate the Dummy AD Environment

PowerSyncPro requires each device to exist in a source directory. Since these machines are workgroup-joined, you must create dummy computer objects inside an AD domain.

You may use:

• An existing AD domain, or
• A dedicated dummy domain (recommended) — the PowerSyncPro server can be promoted to a domain controller and used as the dummy domain if necessary.

Source / Target Domains in AD Migrations

If your target is an Active Directory, the dummy domain must be separate from the target environment. This can be the PowerSyncPro server itself or a separate server promoted to a domain controller.

No communication between the migrating workstations and the dummy domain is required. It exists only as a place to store computer objects so PowerSyncPro can import them into its database.

Requirements

• Promote the PSP server to a domain controller (if using a dedicated dummy domain).
• Add the dummy domain as a Source Directory in PowerSyncPro.
• Ensure the schedule is configured in PowerSyncPro (Sync Service → Schedule).
• Create a Match Only sync profile between the dummy domain and the target directory (Entra or AD).
  • Only computer objects matter for this process.
  • No matching rules are required — this is solely to ensure PowerSyncPro syncs computer objects from the dummy domain into its database.

Create the Dummy AD Objects

On the source domain controller, run:

.\2-Create_Dummy_AD_Objects.ps1 -CsvPath .\mig_db.csv

or

.\2-Create_Dummy_AD_Objects.ps1 -CsvPath .\mig_db.csv -TargetOU "OU=PSP Computers,DC=pspdummy,DC=local"

• CsvPath is the path to the CSV file.
• TargetOU is the distinguished name of the OU where computer objects will be created. Optional — by default, objects are created in the default Computers container.

Notes:

• The script creates AD computer objects matching the computer_name values.
• After creation, run a PSP sync to import these objects: Sync Service Tab → Schedule → Run Now.

After the objects are created and the sync has run, you can confirm they exist using the Single Object Report.

Licensing Reminder

Your PSP license must include:

• Source: dummy domain (e.g., dummy.local)
• Target: Your Entra tenant (e.g., company.onmicrosoft.com) or your target AD domain (e.g., domain.company.com)

Build Runbooks and Batches

Create the Runbook

Create a new runbook for this migration. You'll capture its GUID in the next step.

For Migrations Targeting Entra

• Migration Agent Tab → Runbooks → Create
  • Source Directory: Dummy Domain
  • Target Directory: Entra
• Startup Tab:
  • Set up a Fallback Username / Password (breakglass account).
  • Enable Prevent Login.
• User Experience Tab: Customize as needed; defaults are fine for most cases.
• Device State Tab:
  • Remove From: All Directories
  • Domain Join: Entra ID
  • Enroll to Intune if necessary.
• Permission Updates Tab: Leave as default. Confirm that target account permissions are applied to the file system.
• App Reconfiguration Tab: Usually default. If the workgroup machines are already using the same Entra / M365 tenant as the target, no reconfiguration is needed.
• Completion Tab: Default.

For Migrations Targeting Active Directory

• Migration Agent Tab → Runbooks → Create
  • Source Directory: Dummy Domain
  • Target Directory: Target AD
• Startup Tab:
  • Set up a Fallback Username / Password (breakglass account).
  • Enable Prevent Login.
• User Experience Tab: Customize as needed; defaults are fine for most cases.
• Device State Tab:
  • Remove From: All Directories
  • Domain Join: Active Directory
  • Set an OU for computers to be created in the target domain.
  • Enter an account with domain-join permissions.
  • Note: Offline Domain Join is not supported in this scenario. Migrating workstations must have line-of-sight communication (e.g., on the corporate network) to target domain controllers for the duration of the migration.
• Permission Updates Tab: Leave as default.
• App Reconfiguration Tab: Usually default.
• Completion Tab: Default.

Get the Runbook GUID

Option 1 — Browser Developer Tools

1. In a Chromium-based browser (Chrome, Edge, Brave, Opera, etc.), open the Runbooks page in PowerSyncPro.
2. Press F12 (or Ctrl + Shift + I) to open Developer Tools.
3. Click the Network tab.
4. Click Edit on your selected runbook.
5. You will see a request for EditModal with your runbook ID as a parameter, e.g.: https://psp1.company.com/migrationAgent/Runbooks/EditModal?runbookId=df0a0278-9d4a-4c96-32dc-08de15914463
6. Right-click the request and choose Copy URL.
7. The runbook ID is the GUID after the = sign — e.g., df0a0278-9d4a-4c96-32dc-08de15914463.
8. Save this runbook ID; you'll need it when editing the deployment script.

Option 2 — SQL Server Management Studio (SSMS)

If you have access to the PSP SQL instance, you can query the runbook ID directly. Connect to the PSP database (typically named PowerSyncProDb) and run:

USE PowerSyncProDb;
SELECT Id, Name FROM dbo.Runbooks;

Or, to filter by runbook name:

USE PowerSyncProDb;
SELECT Id, Name FROM dbo.Runbooks WHERE Name = 'Your Runbook Name';

The Id column contains the GUID you need. You can also browse the table in Object Explorer under Databases → PowerSyncProDb → Tables → dbo.Runbooks and right-click → Select Top 1000 Rows for the same result.

Create a Batch

• Migration Agent Tab → Batches → Create
• Source Directory: Dummy Domain
• Target Directory: Target Directory (Entra or AD)
• Runbooks: Assign the runbook created above.
  • Available From: When users should be alerted that a migration is available after the script runs. For an immediate prompt, set this to now (or in the past).
  • Enforced After: When the migration must be completed by. Users will be forced to migrate at this time.
  • Timezone: Local, unless UTC is required.
• Computer Tab:
  • If your computer objects are already in the dummy domain, you should be able to add them here.
  • To migrate everything, select All computers except the following to apply the batch to all computers in the dummy AD.

Customize the Deployment Script

Edit WorkgroupMigrator.ps1 (downloaded from the GitHub repo) before deploying it via your RMM.

Update:

• $basePath — Directory where the RMM will place the CSV and MSI (e.g., C:\Temp).
• $csvName — Name of the CSV created earlier (e.g., mig_db.csv).
• $domainName — Dummy domain FQDN (e.g., dummy.local).
• $RunbookGUIDs — GUID(s) of the PSP runbook to execute, captured above.
• $PspMsiName — Filename of the PSP Migration Agent MSI you downloaded.
• $PSPServerUrl — Your PSP server's Agent endpoint URL (e.g., https://psp1.company.com/Agent).
• $PspPsk — Migration Agent PSK for your server.
• $TargetIdentityType — Set to Entra or AD to match this migration's target.

After updating, package the following files for deployment:

• The customized PowerShell script
• The CSV file
• The PSP Migration Agent MSI

RMM Deployment Instructions

Your RMM should:

• Copy the CSV, MSI, and PowerShell script into the directory defined by $basePath.
• Execute WorkgroupMigrator.ps1 as Administrator or SYSTEM.

The script will:

• Load the CSV.
• Confirm it is running on a hostname contained within the CSV.
• Install and register the PSP Migration Agent.
• Build the required translation table.
• Prepare the device for PSP-managed migration.

If the device is already part of an active batch, it will prompt for migration immediately. Otherwise, it will wait for standard PSP batch scheduling.

The script logs to C:\Temp\Migration_Kickoff_Log.log.

Appendix: Manual Single-Machine Migration

This appendix is the original step-by-step manual process for migrating a single workgroup machine. Use it if you want to migrate a one-off device, or if you're designing your own automation and want to see exactly what the bulk process is doing under the hood.

The bulk process performs all of these steps automatically; this section just spells them out one machine at a time.

Overview

You need to create a runbook for the migration to your desired target, and a batch. The source environment can be any AD environment PSP can connect to. You'll add a computer account to the source AD as the scoping/registration mechanism — this account isn't used for anything else and can be deleted after migration. Consider a dedicated OU for these dummy objects. Make sure your runbook is configured to add the target account's permissions to places like the file system.

Once you've done this once, it's straightforward to repeat for any number of machines — the core values you've collected ($DomainName and $RunbookGUIDs) can be reused on every machine.

Step 1 — Capture the Workstation Hostname

Open an administrative PowerShell prompt on the workgroup machine and capture the hostname:

$env:COMPUTERNAME

Step 2 — Add the Computer to the Source AD

Add the computer object into the source Active Directory using AD Users & Computers.

After PowerSyncPro's sync schedules have run, confirm you can add the computer to the batch.

While in ADUC, capture the domain name where you registered the computer. From a domain-joined session you can run:

(Get-ADDomain).DnsRoot

Or read it from the top of ADUC.

Step 3 — Install PowerSyncPro on the Workgroup Machine

Install PowerSyncPro on the workgroup workstation using the normal PSK and URL for your environment.

Step 4 — Build the Variables in PowerShell

Return to your administrative PowerShell on the workgroup machine.

Set the domain name:

$DomainName = "what you collected earlier"

For example:

$DomainName = "migsource.net"

Capture the SID of the currently logged-in user (the one being migrated) so the agent knows which local user to migrate:

$LocalSiD = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value

Alternatively, run whoami /user and copy the SID into $LocalSiD.

Step 5 — Get the Target User SID

How you do this depends on whether the target is AD or Entra Joined.

For Active Directory

(Get-ADUser <username>).SID.Value

Double-check you have the correct user — pointing the migration at the wrong account will corrupt the workgroup machine's profile.

In the same PowerShell session that holds $LocalSiD, set:

$TargetSiD = "results from your collection"

For example:

$TargetSiD = "S-1-5-21-3501267240-3051813510-3927905062-1115"

For Entra Joined

First, capture the target user's Object ID from the Entra portal:

$objectid = "d49043fc-c389-4652-9eb5-d9815a30a92c"

Convert the Object ID to a SIDusing this PowerShell snippet:

function Convert-AzureAdObjectIdToSid {
    param (
        [Parameter(Mandatory = $true)]
        [String]$ObjectId
    )

    # Parse the Object ID into a GUID and convert it to a byte array
    $guidBytes = [Guid]::Parse($ObjectId).ToByteArray()

    # Initialize an array to hold the UInt32 values
    $uintArray = New-Object 'UInt32[]' 4

    # Copy the byte array into the UInt32 array
    [Buffer]::BlockCopy($guidBytes, 0, $uintArray, 0, 16)

    # Construct the SID string
    $sid = "S-1-12-1-$($uintArray[0])-$($uintArray[1])-$($uintArray[2])-$($uintArray[3])"

    return $sid
}

$targetsid = Convert-AzureAdObjectIdToSid -ObjectId $objectId
Write-Output $targetsid

Step 6 — Verify the Captured Values

Confirm both SIDs and the domain name are present:

$targetsid
$LocalSiD
$DomainName

If any of these are empty, repeat the relevant step before continuing.

Step 7 — Build the Translation File

Create the translation file in the current PowerShell working directory. (The snippet below covers a single user; extend it if you're mapping additional profiles.)

$TranslationTableString = '{"' + $Localsid + '":"' + $targetsid +'"}'
$TranslationTableString | Out-File -FilePath "TranslationTable.json" -Encoding UTF8

Step 8 — Capture the Runbook GUID

You need the runbook GUID so the translation file lands in the right place. On the PSP server, using SSMS, navigate to dbo.Runbooks and copy the runbook ID (or use the Developer Tools method described above).

Back on the workgroup machine, set:

$RunbookGUIDs = @("23B89F9D-58E0-4EF4-DCE1-08DD145A48FE")

Step 9 — Run the Migration Script

Download the helper script: Workgroup-Migrate.ps1

From the same directory as the script, run (in the same elevated PowerShell session that holds your variables):

.\Workgroup-Migrate.ps1 -DomainName $DomainName -ComputerName $env:COMPUTERNAME -RunbookGUIDs $RunbookGUIDs

The script places the translation file in the correct runbook directory and triggers the migration.

Video about the Workgroup Migration process without automation.