Windows Autopilot deployment for existing devices

Modern desktop deployment with Windows Autopilot helps you easily deploy the latest version of Windows to existing devices. The process can automatically install apps used by your organization. If you manage Windows user data with OneDrive for work or school, data synchronizes so users can resume working right away.

Windows Autopilot for existing devices allows you to reimage and provision a Windows device for Windows Autopilot user-driven mode by using a single, native Configuration Manager task sequence. The existing device can be on-premises domain-joined. The result is a Windows device that is either Microsoft Entra joined or Microsoft Entra hybrid joined.

Note

The JSON file for Windows Autopilot for existing devices only supports user-driven Microsoft Entra ID and user-driven hybrid Microsoft Entra Windows Autopilot profiles. Self-deploying and pre-provisioning Windows Autopilot profiles aren't supported with JSON files because these scenarios require TPM attestation.

However, during the Windows Autopilot for existing devices deployment, if the following conditions are true:

  • Device is already a Windows Autopilot device before the deployment begins
  • Device has a Windows Autopilot profile assigned to it

then the assigned Windows Autopilot profile takes precedence over the JSON file installed by the task sequence. In this scenario, if the assigned Windows Autopilot profile is either a self-deploying or pre-provisioning Windows Autopilot profile, the self-deploying and pre-provisioning scenarios are supported.

Tip

You can use Windows Autopilot for existing devices as a method to convert existing hybrid Microsoft Entra devices into Microsoft Entra devices. Using the setting Convert all targeted devices to Autopilot in the Windows Autopilot profile doesn't automatically convert existing hybrid Microsoft Entra devices in the assigned groups into Microsoft Entra devices. The setting only registers the devices in the assigned groups for the Windows Autopilot service.

Requirements

  • A currently supported version of Microsoft Configuration Manager current branch.

  • Assigned Microsoft Intune licenses.

  • Microsoft Entra ID P1 or P2.

  • A supported version of Windows imported into Configuration Manager as an OS image.

  • Enrollment restrictions aren't configured to block personal devices. For more information, see What are enrollment restrictions?: Blocking personal Windows devices.

    Important

    Any devices registered by using a .json file during a hybrid join scenario are normally enrolled as a Corporate device.

Configure the Enrollment Status Page (optional)

If desired, set up an enrollment status page (ESP) for Windows Autopilot by using Intune.

  1. Open the Microsoft Intune admin center.

  2. Go to Devices > Device onboarding | Enrollment. Ensure Windows is selected at the top.

  3. Under Windows Autopilot, select Enrollment Status Page and Set up the Enrollment Status Page.

  4. Go to Microsoft Entra ID > Manage | Mobility (MDM and WIP) > Microsoft Intune and enable Windows automatic enrollment. Configure the MDM user scope for users.

Install required modules

Note

The PowerShell code snippets in this section were updated in July of 2023 to use the Microsoft Graph PowerShell modules instead of the deprecated AzureAD Graph PowerShell modules. The Microsoft Graph PowerShell modules might require approval of additional permissions in Microsoft Entra ID when they're first used. It was also updated to force using an updated version of the WindowsAutoPilot module. For more information, see AzureAD and Important: Azure AD Graph Retirement and PowerShell Module Deprecation.

  1. On an internet-connected Windows PC or server, open an elevated Windows PowerShell command window.

  2. Enter the following commands to install and import the necessary modules:

    Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
Install-Module -Name WindowsAutopilotIntune -MinimumVersion 5.4.0 -Force
Install-Module -Name Microsoft.Graph.Groups -Force
Install-Module -Name Microsoft.Graph.Authentication -Force
Install-Module -Name Microsoft.Graph.Identity.DirectoryManagement -Force

Import-Module -Name WindowsAutopilotIntune -MinimumVersion 5.4
Import-Module -Name Microsoft.Graph.Groups
Import-Module -Name Microsoft.Graph.Authentication
Import-Module -Name Microsoft.Graph.Identity.DirectoryManagement

  3. Enter the following commands and provide Intune administrative credentials:

    Ensure the specified user account has sufficient administrative rights.

    Connect-MgGraph -Scopes "Device.ReadWrite.All", "DeviceManagementManagedDevices.ReadWrite.All", "DeviceManagementServiceConfig.ReadWrite.All", "Domain.ReadWrite.All", "Group.ReadWrite.All", "GroupMember.ReadWrite.All", "User.Read"

    Windows requests the username and password for the account by using a standard Microsoft Entra ID form. Type the username and password, and then select Sign in.

    Screenshot shows the Windows form to sign in to a Microsoft Entra account.

    The first time you use Intune Graph APIs on a device, they prompt you to enable Microsoft Intune PowerShell read and write permissions. To enable these permissions, select Consent on behalf of your organization and then Accept.

Get Windows Autopilot profiles for existing devices

Get all the Windows Autopilot profiles available in the Intune tenant, and display them in JSON format:

Get-AutopilotProfile | ConvertTo-AutopilotConfigurationJSON

See the following sample output:

PS C:\> Get-AutopilotProfile | ConvertTo-AutopilotConfigurationJSON
{
    "CloudAssignedTenantId": "1537de22-988c-4e93-b8a5-83890f34a69b",
    "CloudAssignedForcedEnrollment": 1,
    "Version": 2049,
    "Comment_File": "Profile Autopilot Profile",
    "CloudAssignedAadServerData": "{\"ZeroTouchConfig\":{\"CloudAssignedTenantUpn\":\"\",\"ForcedEnrollment\":1,\"CloudAssignedTenantDomain\":\"M365x373186.onmicrosoft.com\"}}",
    "CloudAssignedTenantDomain": "M365x373186.onmicrosoft.com",
    "CloudAssignedDomainJoinMethod": 0,
    "CloudAssignedOobeConfig": 28,
    "ZtdCorrelationId": "7F9E6025-1E13-45F3-BF82-A3E8C5B59EAC"
}

Each profile is encapsulated within braces ({ }). The previous example displays a single profile.

JSON file properties

Property Type Required Description
Version Number Optional The version number that identifies the format of the JSON file.
CloudAssignedTenantId GUID Required The Microsoft Entra tenant ID that should be used. This property is the GUID for the tenant, and you can find it in the properties of the tenant. The value shouldn't include braces.
CloudAssignedTenantDomain String Required The Microsoft Entra tenant name that should be used. For example: tenant.onmicrosoft.com.
CloudAssignedOobeConfig Number Required This property is a bitmap that shows which Windows Autopilot settings were configured.

  • 1: SkipCortanaOptIn
  • 2: OobeUserNotLocalAdmin
  • 4: SkipExpressSettings
  • 8: SkipOemRegistration
  • 16: SkipEula
CloudAssignedDomainJoinMethod Number Required This property specifies whether the device should join Microsoft Entra ID or Active Directory (Microsoft Entra hybrid join).

  • 0: Microsoft Entra joined
  • 1: Microsoft Entra hybrid joined
CloudAssignedForcedEnrollment Number Required Specifies that the device should require Microsoft Entra join and MDM enrollment.

  • 0: Not required
  • 1: required
ZtdCorrelationId GUID Required A unique GUID (without braces) provided to Intune as part of the registration process. This ID is included in the enrollment message as the OfflineAutopilotEnrollmentCorrelator. This attribute is present only if enrollment happens on a device registered with Zero Touch Provisioning by using offline registration.
CloudAssignedAadServerData Encoded JSON string Required An embedded JSON string used for branding. It requires enabling Microsoft Entra organization branding. For example:

"CloudAssignedAadServerData": "{\"ZeroTouchConfig\":{\"CloudAssignedTenantUpn\":\"\",\"CloudAssignedTenantDomain\":\"tenant.onmicrosoft.com\"}}
CloudAssignedDeviceName String Optional The name automatically assigned to the computer. This name follows the naming pattern convention configured in the Intune Windows Autopilot profile. You can also specify an explicit name.

Create the JSON file

Save the Windows Autopilot profile as a JSON file in ASCII or ANSI format. Windows PowerShell defaults to Unicode format. If you redirect output of the commands to a file, specify the file format. The following PowerShell example saves the file in ASCII format.

The Windows Autopilot profiles appear in a subfolder under the folder specified by the $targetDirectory variable. By default, the $targetDirectory variable is C:\AutoPilot, but you can change it to another location. The folder uses the name of the Windows Autopilot profile from Intune. If there are multiple Windows Autopilot profiles, each profile has its own subfolder. In each folder, there's a JSON file named AutopilotConfigurationFile.json.

Connect-MgGraph -Scopes "Device.ReadWrite.All", "DeviceManagementManagedDevices.ReadWrite.All", "DeviceManagementServiceConfig.ReadWrite.All", "Domain.ReadWrite.All", "Group.ReadWrite.All", "GroupMember.ReadWrite.All", "User.Read"
$AutopilotProfile = Get-AutopilotProfile
$targetDirectory = "C:\Autopilot"
$AutopilotProfile | ForEach-Object {
    New-Item -ItemType Directory -Path "$targetDirectory\$($_.displayName)"
    $_ | ConvertTo-AutopilotConfigurationJSON | Set-Content -Encoding Ascii "$targetDirectory\$($_.displayName)\AutopilotConfigurationFile.json"
}

Tip

When you use the PowerShell cmdlet Out-File to redirect the JSON output to a file, it uses Unicode encoding by default. This cmdlet might also truncate long lines. Use the Set-Content cmdlet with the -Encoding ASCII parameter to set the proper text encoding.

Important

The file name must be AutopilotConfigurationFile.json and encoded as ASCII or ANSI.

You can also save the profile to a text file and edit it in Notepad. In Notepad, when you choose Save as, select the save as type: All Files, and then select ANSI for the Encoding.

Screenshot shows the option to save as ANSI encoding in Notepad.

After you save the file, move it to a location for a Microsoft Configuration Manager package source.

Important

The configuration file can only contain one profile. You can use multiple JSON profile files, but each one must be named AutopilotConfigurationFile.json. This requirement is for OOBE to follow the Windows Autopilot experience. To use more than one Windows Autopilot profile, create separate Configuration Manager packages.

Windows OOBE doesn't follow the Windows Autopilot experience if you save the file with one of the following criteria:

  • Unicode encoding
  • UTF-8 encoding
  • A file name other than AutopilotConfigurationFile.json

Create a package containing the JSON file

  1. In the Configuration Manager console, go to the Software Library workspace, expand Application Management, and select the Packages node.

  2. On the ribbon, select Create Package.

  3. In the Create Package and Program Wizard, enter the following details for the package:

    • Name: Windows Autopilot for existing devices config
    • Select This package contains source files
    • Source folder: Specify the UNC network path that contains the AutopilotConfigurationFile.json file

    For more information, see Packages and programs in Configuration Manager.

  4. For the program, select the Program Type: Don't create a program.

  5. Complete the wizard.

Note

If you change the user-driven Windows Autopilot profile settings in Intune, recreate and update the JSON file. After updating the JSON file, redistribute the associated Configuration Manager package.

Create a target collection

  1. In the Configuration Manager console, go to the Assets and Compliance workspace, and select the Device Collections node.

  2. On the ribbon, select Create, and then select Create Device Collection. You can also use an existing collection. If you use an existing collection, proceed to the Create a task sequence section.

  3. In the Create Device Collection Wizard, enter the following General details:

    • Name: Windows Autopilot for existing devices collection
    • Comment: Add an optional comment to further describe the collection
    • Limiting collection: All Systems or if desired, an alternate collection.

  4. On the Membership Rules page, select Add Rule. Specify either a direct or query-based collection rule to add the target Windows devices to the new collection.

    For example, if the hostname of the computer to wipe and reload is PC-01, and Name is the attribute:

    1. Select Add Rule, select Direct Rule to open the Create Direct Membership Rule Wizard, and select Next on the Welcome page.

    2. On the Search for Resources page, enter PC-01 as the Value.

    3. Select Next, and select PC-01 in the Resources.

  5. Complete the wizard with the default settings.

For more information, see How to create collections in Configuration Manager.

Create a task sequence

  1. In the Configuration Manager console, go to the Software Library workspace, expand Operating Systems, and select the Task Sequences node.

  2. In the Home ribbon, select Create Task Sequence.

  3. In Create new task sequence, select the option to Deploy Windows Autopilot for existing devices.

  4. In Task sequence information, specify the following information:

    • A name for the task sequence. For example, Windows Autopilot for existing devices.
    • Optionally add a description to better describe the task sequence.
    • Select a boot image. For more information on supported boot image versions, see Support for the Windows ADK in Configuration Manager.

  5. In Install Windows, select the Windows Image package. Then configure the following settings:

    • Image index: Select either Enterprise, Education, or Professional, as required by the organization.

    • Enable the option to Partition and format the target computer before installing the operating system.

    • Configure task sequence for use with Bitlocker: If you enable this option, the task sequence includes the steps necessary to enable BitLocker.

    • Product key: If you need to specify a product key for Windows activation, enter it here.

    • Select one of the following options to configure the local administrator account in Windows:

      • Randomly generate the local administrator password and disable the account on all support platforms (recommended)
      • Enable the account and specify the local administrator password

  6. In Install the Configuration Manager client, add any necessary Configuration Manager client installation properties for the environment.

    For example, since the device is a workgroup device and not domain joined during the Windows Autopilot for existing devices task sequence, you might need the SMSMP or SMSMPLIST parameters to run certain tasks such as the Install Application or Install Software Updates tasks.

  7. In Include updates, select the option to Do not install any software updates.

  8. In Install applications, optionally select applications to install during the task sequence. However, to mirror the signature image approach with this scenario, Microsoft recommends applying all applications and configurations from Microsoft Intune or Configuration Manager co-management after the device provisions with Windows Autopilot. This process provides a consistent experience between users receiving new devices and those using Windows Autopilot for existing devices.

  9. In System Preparation, select the package that includes the Windows Autopilot configuration file. By default, the task sequence restarts the computer after it runs Windows Sysprep. You can also select the option to Shutdown computer after this task sequence completes. This option allows you to prepare a device and then deliver it to a user for a consistent Windows Autopilot experience.

  10. Complete the wizard.

The Windows Autopilot for existing devices task sequence results in a device joined to Microsoft Entra ID.

Note

For Windows Autopilot for existing devices task sequence, the Create Task Sequence Wizard purposely skips configuring and adding the Apply Network Settings task. If you don't specify the Apply Network Settings task in a task sequence, it uses Windows default behavior, which is to join a workgroup.

The Windows Autopilot for existing devices task sequence runs the Prepare Windows for capture step, which uses the Windows System Preparation Tool (Sysprep). If the device is joined to a domain, Sysprep fails, so the Windows Autopilot for existing devices task sequence joins a workgroup. For this reason, it isn't necessary to add the Apply Network Settings task to a Windows Autopilot for existing devices task sequence.

For more information on creating the task sequence, including information on other wizard options, see Create a task sequence to install an OS.

If you view the task sequence, it's similar to the default task sequence to apply an existing OS image. This task sequence includes the following extra steps:

  • Apply Windows Autopilot configuration: This step applies the Windows Autopilot configuration file from the specified package. It's not a new type of step. It's a Run Command Line step to copy the file.

  • Prepare Windows for Capture: This step runs Windows Sysprep, and has the setting to Shutdown the computer after running this action. For more information, see Prepare Windows for Capture.

For more information on editing the task sequence, see Use the task sequence editor and Task sequence steps.

Note

The Prepare Windows for Capture step deletes the AutopilotConfigurationFile.json file. For more information and a workaround, see Modify the task sequence to account for Sysprep command line configuration and Windows Autopilot - known issues: Windows Autopilot for existing devices doesn't work.

To ensure the user's data is backed up before the Windows upgrade, use OneDrive for work or school known folder move.

Distribute content to distribution points

Next, distribute all content required for the task sequence to distribution points.

  1. Select the Windows Autopilot for existing devices task sequence. In the ribbon, select Distribute Content.

  2. On the Specify the content destination page, select Add to specify either a Distribution Point or Distribution Point Group.

  3. Specify content destinations that let the devices get the content.

  4. After specifying content distribution, complete the wizard.

For more information, see Manage task sequences to automate tasks.

Deploy the Windows Autopilot task sequence

  1. Select the Windows Autopilot for existing devices task sequence. In the ribbon, select Deploy.

  2. In the Deploy Software Wizard, specify the following details:

    • General

      • Task Sequence: Windows Autopilot for existing devices

      • Collection: Windows Autopilot for existing devices collection

    • Deployment Settings

      • Action: Install.

      • Purpose: Available.

      • Make available to the following: Only Configuration Manager Clients.

        Note

        Select the option that's relevant for the context of testing. If the target client doesn't have the Configuration Manager agent or Windows installed, you need to start the task sequence by using PXE or Boot Media.

    • Scheduling

      • Set a time for when this deployment becomes available.

    • User Experience

      • Select Show Task Sequence progress.

    • Distribution Points

      • Deployment options: Download content locally when needed by the running task sequence.

  3. Complete the wizard.

Complete the deployment process

  1. On the target Windows device, go to the Start menu, enter Software Center, and open it.

  2. In the Software Library, under Operating Systems, select Windows Autopilot for existing devices, and then select Install.

The task sequence runs and does the following actions:

  1. Downloads content.

  2. Restarts the device into WinPE.

  3. Formats the drive.

  4. Installs Windows from the specified OS image.

  5. Prepares for Windows Autopilot.

  6. After the task sequence completes, the device boots into OOBE for the Windows Autopilot experience:

Note

If devices need to be joined to Active Directory as part of a Microsoft Entra hybrid join scenario, don't use the task sequence and the Apply Network Settings task. Instead, create a Domain Join device configuration profile. Because there's no Microsoft Entra device object for the computer to do group-based targeting, target the profile to All Devices. For more information, see User-driven mode for Microsoft Entra hybrid join.

Register the device for Windows Autopilot

Devices provisioned with Windows Autopilot only receive the guided OOBE Windows Autopilot experience on first boot.

After Windows is updated on an existing device, make sure to register the device so it has the Windows Autopilot experience when the PC resets. Automatic registration can be enabled for a device by using the Convert all targeted devices to Autopilot setting in the Windows Autopilot profile that is assigned to a group that the device is a member of. For more information, see Create a Windows Autopilot deployment profile.

Also see Adding devices to Windows Autopilot.

Note

  • Typically, the target device isn't registered with the Windows Autopilot service. If the device is already registered, the assigned profile takes precedence. The Windows Autopilot for existing devices profile only applies if the online profile times out.

  • When the assigned profile is applied, the enrollmentProfileName property of the device object in Microsoft Intune and Microsoft Entra ID match the Windows Autopilot profile name.

  • When the Windows Autopilot for existing devices profile is applied, the enrollmentProfileName property of the device object in Microsoft Intune and Microsoft Entra ID are OffilineAutoPilotProfile-<ZtdCorrelationId>.

How to speed up the deployment process

To speed up the deployment process, see Windows Autopilot deployment for existing devices: Speed up the deployment process section of the Windows Autopilot Tutorial.

Tutorial

For a detailed tutorial on configuring Windows Autopilot for existing devices, see Step by step tutorial for Windows Autopilot deployment for existing devices in Intune and Configuration Manager.

Related content

  • Last updated on