Skip to content

Deployment Guide

This guide will walk you through setting up the Intune Device Migration tool for migrating a Windows PC in the following scenarios:

  • Source Intune tenant to a Destination
  • Domain/Hybrid join state to Cloud native
  • Comanaged to Intune managed

Warning

WAIT: Make sure you read through the Requirements before proceeding

Click on any image below to enlarge

Download migration solution

Step 1 - Download

Start by downloading the migration tool from GitHub and extract the files.

download solution

Step 2 - Extract

For this example, I am extracting to C:\Intune-Device-Migration-V7-main on my local PC

extract to path

Step 3 - Open in VS Code

Navigate to the extracted folder, right-click and select Open with code** from the context menu.

open with code

App registration

Step 1 - Sign in

Sign in to entra.microsoft.com with your Global Administrator credentials.

sign in

Step 2 - New registration

Navigate to Applications > App registrations and click + New registration

new app reg

Enter a name for the application (this can be whatever you'd like). Leave all other options as default and click Register.

name and register

Step 3 - Save client ID

Once the application page loads, find the Application (client) ID and copy the value.

copy client ID

Switch over to Visual Studio Code where you have the solution open. Navigate to the config.json file and paste the value into sourceTenant: clientId:

paste client ID

Step 4 - Add permissions

Back at the app page in Entra, navigate to API permissions and click +Add a permission.

click add permission

On the Request API permissions page, select Microsoft Graph

select graph

For type of permission select Application permissions

app permissions

Type device into the search field, and add the following permissions in each category:

  • Device
    • Device.ReadWrite.All
  • DeviceManagementManagedDevices
    • DeviceManagementManagedDevices.ReadWrite.All
  • DeviceManagementServiceConfig
    • DeviceManagementServiceConfig.ReadWrite.All

device permissions

Type user into the search field, and add the following user permission:

  • User
    • User.Read.All

Click Add permissions

user permission

On the API permissions page, click Grant admin consent for TENANT NAME. Click Yes at the Grant admin consent confirmation popup.

grant

All permissions should now have the granted status.

granted

Step 5 - New secret

Navigate to Certificates & secrets > Client secrets and click +New client secret

new secret

Enter a name in Description (whatever you want). Under the Expires dropdown, you can choose any amount of time. I will stick with the Recommended: 180 days (6 months) option. Click Add.

secret time

Step 6 - Save secret value

Find the Value of the secret and copy to the clipboard.

Warning

This is the only time you can get the secret value, so make sure you copy it before navigating away from this page.

copy secret

Go back to Visual Studio Code to the config.json file. Paste the secret value into sourceTenant: clientSecret:

paste secret

Info

IMPORTANT: If migrating to a new tenant, repeat steps 1 through 6 in the destination tenant.

Client ID and Secret value are pasted into targetTenant: in config.json:

target values

Info

If not migrating tenants, remove targetTenant code block from config.json

remove target

Provisioning package

Step 1 - Download WCD

Download the Windows Configuration Designer (WCD) tool from here.

download wcd

Launch the WCD from the Windows start menu.

launch wcd

Step 2 - New package

When the WCD opens, select Provision desktop devices under the Create menu.

create package

In the New project pop-up window, enter a name for the package and click Finish.

name package

Step 3 - Device settings

In the Set up device menu, enter a naming template for your PC. Click Next.

setup device

On the Set up network menu, set Connect device to a Wi-Fi network togle to Off. Click Next.

turn off wifi

Step 4 - Bulk AAD token

On the Account Management menu, choose Enroll in Azure AD under Manage Organization/School Accounts and toggle Refresh AAD credentials to Yes*.

enroll in add

Ensure Bulk Token Expiry date is set to the maximum (6 months). Click Get Bulk Token.

bulk token

You will be prompted to sign in.

Info

If you are migrating to a new tenant, use your destination credentials here. If this is just domain to cloud, sign in with source credentials.

If this is the first time you are using the WCD tool, you will be asked to consent to the permissions. Click Consent on behalf of your organization and click Accept

  • pic
  • pic

When prompted on the Stay signed in to all your apps screen, uncheck the box for Allow my organization to manage my device and click No, sign in to this app only. You should then see the Bulk Token was fetched successfully.

  • pic
  • pic

Step 5 - Complete the package

If you want, you can create a local admin account on the PC by entering a Username and Password. Click Next.

admin account

Click Next on both the Add applications and Add certificates pages. On the Summary page, ensure everything is correct and click Create.

summary create

Below the Create button, you will see the link to the path where the package was created.

package link

Click on the link to open the file explorer. Copy the "YourPackageName.ppkg" files.

copy package

In Visual Studio Code, where you have the solution open, past the package to the Device Migration root directory.

vs code package

Configuration file

Step 1 - Tenant name

Go to Visual Studio Code, where the migration solution should be open and navigate to the config.json file. Modify the following properties:

  • sourceTenant: "NameOfYourSourceTenant.com"
  • targetTenant: "NameOfYourDestinationTenant.com" (if migrating to a new tenant)

tenant name

Step 2 - Group tag

Group tags are used both for Autopilot registration and to place the PC in a dynamic device group after migration.

Info

If you are migrating to a new tenant and the PC is already registered in the source tenant's Autopilot with a group tag, you can leave this field blank and the migration script will attempt to retrieve the current tag from the source.

To set a group tag manually, enter the name of your tag in the groupTag: field.

group tag

Step 3 - BitLocker

The migration solution can handle BitLocker encryption keys in two different ways.

  1. Migrate: The current BitLocker key will be collected and escrowed to the destination Entra ID tenant.
  2. Decrypt: The drive will be decrypted and will rely on Intune policy post migration to start BitLocker encryption

To set a value for how to handle BitLocker, type either "migrate" or "decrypt" into the bitlockerMethod: field.

bitlocker

Step 4 - SCCM

If you are using Microsoft Endpoint Configuration Manager (MECM/SCCM), the migration solution can automatically uninstall the configuration client before enrolling in Intune.

To uninstall, set the SCCM: value to true.

sccm

Success

The configuration is now complete.

Intune Win32 application (.intunewin)

Step 1 - Create the .intunewin file

With the configuration complete, open the Device Migration directory in File Explorer.

Right click on the IntuneWinAppUtil.exe file and select Run as administrator.

right click intunewinapputil

A cmd prompt windows will open. Set the following values:

  • Please specify the source folder: .\
  • Please specify the setup file: startMigrate.ps1
  • Please specify the output folder: .\
  • Do you want to specify the catalog folder (Y/N): n

cmd

When the cmd is finished running, you should have the startMigrate.intunewin file in the directory.

intunewin file

Step 2 - Upload to Intune

Log in to intune.microsoft.com with at least Intune administrator privileges.

Navigate to Apps > Windows.

windows apps

Click +Add. In the Select app type menu, choose Windows app (Win32) from the app type drop-down menu and click Select.

app type

Select Select app package file and click in the App package file field. Choose the startMigrate.intunewin file you created in the previous step and then click OK.

upload

Step 3 - Configure

In the App information menu, only three fields are required: Name, Description, and Publisher. Fill them out as you see fit.

You may also want to add some kind of logo for the app so users can identify it easier.

Click Next when you're done editing.

app info

On the Program menu, we need to complete the Install command and Uninstall command fields.

Use the following values:

  • Install command: %windir%\sysnative\WindowsPowerShell\v1.0\powershell.exe -executionpolicy bypass .\startMigrate.ps1
  • Uninstall command: *

Click Next.

program

For Requirements, set the following mandatory fields:

  • Operating system architecture: 64-bit
  • Minimum operating system: Windows 10 22H2

Click Next

requirements

At the Detection rules page, select Manually configure detection rules from the Rules format drop-down menu.

Click +Add

detection add

For Rule type select File. Complete the following fields:

  • Path: C:\ProgramData\IntuneMigration
  • File or folder: install.tag
  • Detection method: File or folder exists

Click OK and then Next.

  • detection rule
  • next

You can also click Next on the Dependencies, Supersedence, and Scope tags pages.

Step 4 - Assign and verify

You can assign the migration app as either Required or Available. I'm going to use the Available option so the app can be installed by the user from the Company Portal app.

Click the +Add group button and select the user group you want to deploy the app to.

Click Next

assign

Warning

For the application to be available in the company portal, ensure the users included in the assignment groups are listed as the Primary user for the Intune device as seen below:

Primary user

To verify that the assignment worked, log into an Intune managed PC as a user in the assigned group. Launch Company Portal and select Apps.

Look for the app amongst the rest of your catalog. To begin testing, simply click Install.

  • company portal
  • install

Success

Congrats! The migration app is ready.