How to deploy Autopilot Device Preparation Policies with PowerShell

Device Preparation Policies in Microsoft Intune allow you to deliver the Autopilot device configuration during the user authentication stage of the OOBE (out-of-the-box) experience on new devices. Unlike standard Autopilot profiles where the device hash needs to be pre-uploaded to the Autopilot service, this is not required with Device preparation policies as it targets the user and not the device.

If you want to learn more about Autopilot device preparation, read the following articles:

Autopilot and the Sundance Device Preparation by Rudy Ooms
Overview of Windows Autopilot device preparation by Microsoft

In this article, I demonstrate how you can use Microsoft Graph PowerShell to programmatically deploy Device Preparation Profiles to your Microsoft Intune tenant.

Page Contents

Requirements

The scripts in this article use the Microsoft Graph PowerShell modules to interact with the Graph API. For this, you must install the latest version of the Microsoft Graph PowerShell modules. Use the below link to learn how:

How To Install the Microsoft Graph PowerShell Module

You will then need to connect to Microsoft Graph using the following command. When prompted, you must sign in as a Global Administrator to consent to the required permissions for the scripts.

Connect-MgGraph -Scopes "DeviceManagementConfiguration.ReadWrite.All", "Group.readwrite.all"

Add 'Intune Autopilot ConfidentialClient' as a device group owner

A requirement for Device Preparation Policies are to have a device group ready for which the devices will be added to during provisioning. If you don’t already have a security group created in Microsoft Entra for your devices, create one now.

Once your device group is created, the Intune Autopilot ConfidentialClient enterprise application in Microsoft Entra must be added as a group owner. Without this, the AutoPilot service cannot update the group membership during provisioning (as this is not done in the user’s context).

Use the below example to add the Intune Autopilot ConfidentialClient Enterprise application as an owner of your device group.

On the first line, change the DevicePrepGroup, to the name of your group.

$Groupid = Get-MgBetaGroup -Filter "DisplayName eq 'DevicePrepGroup'" | Select -ExpandProperty Id

$newGroupOwner =@{
  "@odata.id"= "https://graph.microsoft.com/beta/directoryObjects/4f3a0917-f3b9-4246-ab2c-9619869ca013"
}

New-MgBetaGroupOwnerByRef -GroupId $Groupid -BodyParameter $newGroupOwner

Create a new Device Preparation Policy

While this article will not go into detail on the intricacies of Device Preparation, I will show you the different options you can select when using Microsoft Graph PowerShell to deploy your policies in your tenant.

The body of the request is structured as such, with all your desired settings within the square brackets next to Settings, these represent an array.

$body = @"
{
  "name": "Device Prep Policy 3",
  "description": "",
  "settings": [
    # Here will be your desired settings
  ],
  "roleScopeTagIds": [
    "0"
  ],
  "platforms": "windows10",
  "technologies": "enrollment",
  "templateReference": {
    "templateId": "80d33118-b7b4-40d8-b15f-81be745e053f_1"
  }
}
"@

Below I will highlight the available options when deploying your Device Preparation Policy.

Deployment mode

enrollment_autopilot_dpp_deploymentmode_0 sets the deployment mode as Single user. This is the only available mode.

{
      "@odata.type": "#microsoft.graph.deviceManagementConfigurationSetting",
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance",
        "choiceSettingValue": {
          "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingValue",
          "children": [],
          "settingValueTemplateReference": {
            "settingValueTemplateId": "5874c2f6-bcf1-463b-a9eb-bee64e2f2d82"
          },
          "value": "enrollment_autopilot_dpp_deploymentmode_0"
        },
        "settingDefinitionId": "enrollment_autopilot_dpp_deploymentmode",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "5180aeab-886e-4589-97d4-40855c646315"
        }
      }
    }

Deployment type

enrollment_autopilot_dpp_deploymenttype_0 sets the deployment type as User driven. This is the only available type.

{
      "@odata.type": "#microsoft.graph.deviceManagementConfigurationSetting",
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance",
        "choiceSettingValue": {
          "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingValue",
          "children": [],
          "settingValueTemplateReference": {
            "settingValueTemplateId": "e0af022f-37f3-4a40-916d-1ab7281c88d9"
          },
          "value": "enrollment_autopilot_dpp_deploymenttype_0"
        },
        "settingDefinitionId": "enrollment_autopilot_dpp_deploymenttype",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "f4184296-fa9f-4b67-8b12-1723b3f8456b"
        }
      }
    }

Directory join type

enrollment_autopilot_dpp_jointype_0 sets the join type as Microsoft Entra Joined. This is the only available join type.

 {
      "@odata.type": "#microsoft.graph.deviceManagementConfigurationSetting",
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance",
        "choiceSettingValue": {
          "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingValue",
          "children": [],
          "settingValueTemplateReference": {
            "settingValueTemplateId": "1fa84eb3-fcfa-4ed6-9687-0f3d486402c4"
          },
          "value": "enrollment_autopilot_dpp_jointype_0"
        },
        "settingDefinitionId": "enrollment_autopilot_dpp_jointype",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "6310e95d-6cfa-4d2f-aae0-1e7af12e2182"
        }
      }
    }

User account type

enrollment_autopilot_dpp_accountype_1 sets the user account type as a standard user.
enrollment_autopilot_dpp_accountype_0 sets the user account type as a local administrator.

{
      "@odata.type": "#microsoft.graph.deviceManagementConfigurationSetting",
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance",
        "choiceSettingValue": {
          "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingValue",
          "children": [],
          "settingValueTemplateReference": {
            "settingValueTemplateId": "bf13bb47-69ef-4e06-97c1-50c2859a49c2"
          },
          "value": "enrollment_autopilot_dpp_accountype_1" 
        },
        "settingDefinitionId": "enrollment_autopilot_dpp_accountype",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "d4f2a840-86d5-4162-9a08-fa8cc608b94e"
        }
      }
    }

Minutes allowed before showing installation error

The number value 30, sets the Minutes allowed before showing installation error to 30 minutes. This can be set between 15 and 720.

{
      "@odata.type": "#microsoft.graph.deviceManagementConfigurationSetting",
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationSimpleSettingInstance",
        "settingDefinitionId": "enrollment_autopilot_dpp_timeout",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "6dec0657-dfb8-4906-a7ee-3ac6ee1edecb"
        },
        "simpleSettingValue": {
          "@odata.type": "#microsoft.graph.deviceManagementConfigurationIntegerSettingValue",
          "settingValueTemplateReference": {
            "settingValueTemplateId": "0bbcce5b-a55a-4e05-821a-94bf576d6cc8"
          },
          "value": 30
        }
      }
    }

Custom error message

You can define a custom error message should an issue occur or if the deployment times out. Configure this next to Value below.

{
      "@odata.type": "#microsoft.graph.deviceManagementConfigurationSetting",
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationSimpleSettingInstance",
        "settingDefinitionId": "enrollment_autopilot_dpp_customerrormessage",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "2ddf0619-2b7a-46de-b29b-c6191e9dda6e"
        },
        "simpleSettingValue": {
          "@odata.type": "#microsoft.graph.deviceManagementConfigurationStringSettingValue",
          "settingValueTemplateReference": {
            "settingValueTemplateId": "fe5002d5-fbe9-4920-9e2d-26bfc4b4cc97"
          },
          "value": "Contact your oganization's support person for help."
        }
      }
    }

Allow users to skip setup after multiple attempts

enrollment_autopilot_dpp_allowskip_1 allows users to skip an error should they retry deployment more than once.
enrollment_autopilot_dpp_allowskip_2 will not allow the user to skip an erroe.

{
      "@odata.type": "#microsoft.graph.deviceManagementConfigurationSetting",
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance",
        "choiceSettingValue": {
          "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingValue",
          "children": [],
          "settingValueTemplateReference": {
            "settingValueTemplateId": "a2323e5e-ac56-4517-8847-b0a6fdb467e7"
          },
          "value": "enrollment_autopilot_dpp_allowskip_1"
        },
        "settingDefinitionId": "enrollment_autopilot_dpp_allowskip",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "2a71dc89-0f17-4ba9-bb27-af2521d34710"
        }
      }
    },

Show a link to diagnostics

enrollment_autopilot_dpp_allowdiagnostics_1 will show a link to obtain diagnostics should an error occur during the Device Preparation process.
enrollment_autopilot_dpp_allowdiagnostics_0 will not show a link to obtain diagnostics.

 {
      "@odata.type": "#microsoft.graph.deviceManagementConfigurationSetting",
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance",
        "choiceSettingValue": {
          "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingValue",
          "children": [],
          "settingValueTemplateReference": {
            "settingValueTemplateId": "c59d26fd-3460-4b26-b47a-f7e202e7d5a3"
          },
          "value": "enrollment_autopilot_dpp_allowdiagnostics_1"
        },
        "settingDefinitionId": "enrollment_autopilot_dpp_allowdiagnostics",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "e2b7a81b-f243-4abd-bce3-c1856345f405"
        }
      }
    },

Deploy managed apps

Applications made available in Microsoft Intune can be selected for deployment during the Device Preparation process. The simpleSettingCollectionValue array defines each app to be deployed (up to 10). To define an app, modify the id and type for the app you wish to download.

{
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationSimpleSettingCollectionInstance",
        "settingDefinitionId": "enrollment_autopilot_dpp_allowedappids",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "70d22a8a-a03c-4f62-b8df-dded3e327639"
        },
        "simpleSettingCollectionValue": [
          {
            "@odata.type": "#microsoft.graph.deviceManagementConfigurationStringSettingValue",
            "value": "{\"id\":\"ba1a199d-a83e-4298-84c2-d68bbcc87850\",\"type\":\"#microsoft.graph.winGetApp\"}"
          },
          {
            "@odata.type": "#microsoft.graph.deviceManagementConfigurationStringSettingValue",
            "value": "{\"id\":\"744985ff-a511-4359-a892-678d65afb713\",\"type\":\"#microsoft.graph.win32LobApp\"}"
          }
        ]
      }
    },

To automatically obtain the necessary information for the apps you want to deploy, use the below example and change the display name of your desired app in the filter.

$app1 = Get-MgBetaDeviceAppManagementMobileApp -Filter "DisplayName eq 'Company Portal'" | Select

The values can then be added to the collection like so:

{
    "@odata.type": "#microsoft.graph.deviceManagementConfigurationStringSettingValue",
    "value": "{\"id\":\"$($app1.Id)\",\"type\":\"$($app1.AdditionalProperties['@odata.type'])\"}"
}

Deploy managed PowerShell scripts

PowerShell scripts can be run on devices during the Device Preparation process. Each script must be uploaded to Microsoft Intune under Devices > Windows > Scripts. Then in the simpleSettingCollectionValue array, you must reference the ID for each script.

{
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationSimpleSettingCollectionInstance",
        "settingDefinitionId": "enrollment_autopilot_dpp_allowedscriptids",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "1bc67702-800c-4271-8fd9-609351cc19cf"
        },
        "simpleSettingCollectionValue": [
          {
            "@odata.type": "#microsoft.graph.deviceManagementConfigurationStringSettingValue",
            "value": "148dbe00-6d47-4800-84e8-cd36da56f8af"
          }
        ]
      }
    }

To obtain the ID for any script you wish to deploy, use the below example and change the display name of your target script:

$Script1 = Get-MgBetaDeviceManagementScript -Filter "displayName eq 'MyScript'"

The script ID can then be added to the example above like so:

 {
    "@odata.type": "#microsoft.graph.deviceManagementConfigurationStringSettingValue",
    "value": "$($Script1.id)"
}

Device Preparation script example

$app1  = Get-MgBetaDeviceAppManagementMobileApp -Filter "DisplayName eq 'Company Portal'" | Select 
$script1 = Get-MgBetaDeviceManagementScript -Filter "displayName eq 'MyScriptt'"

$uri = "https://graph.microsoft.com/beta/deviceManagement/configurationPolicies"

$body = @"
{
  "name": "Device Prep Policy 5",
  "description": "",
  "settings": [
    {
      "@odata.type": "#microsoft.graph.deviceManagementConfigurationSetting",
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance",
        "choiceSettingValue": {
          "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingValue",
          "children": [],
          "settingValueTemplateReference": {
            "settingValueTemplateId": "5874c2f6-bcf1-463b-a9eb-bee64e2f2d82"
          },
          "value": "enrollment_autopilot_dpp_deploymentmode_0"
        },
        "settingDefinitionId": "enrollment_autopilot_dpp_deploymentmode",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "5180aeab-886e-4589-97d4-40855c646315"
        }
      }
    },
    {
      "@odata.type": "#microsoft.graph.deviceManagementConfigurationSetting",
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance",
        "choiceSettingValue": {
          "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingValue",
          "children": [],
          "settingValueTemplateReference": {
            "settingValueTemplateId": "e0af022f-37f3-4a40-916d-1ab7281c88d9"
          },
          "value": "enrollment_autopilot_dpp_deploymenttype_0"
        },
        "settingDefinitionId": "enrollment_autopilot_dpp_deploymenttype",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "f4184296-fa9f-4b67-8b12-1723b3f8456b"
        }
      }
    },
    {
      "@odata.type": "#microsoft.graph.deviceManagementConfigurationSetting",
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance",
        "choiceSettingValue": {
          "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingValue",
          "children": [],
          "settingValueTemplateReference": {
            "settingValueTemplateId": "1fa84eb3-fcfa-4ed6-9687-0f3d486402c4"
          },
          "value": "enrollment_autopilot_dpp_jointype_0"
        },
        "settingDefinitionId": "enrollment_autopilot_dpp_jointype",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "6310e95d-6cfa-4d2f-aae0-1e7af12e2182"
        }
      }
    },
    {
      "@odata.type": "#microsoft.graph.deviceManagementConfigurationSetting",
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance",
        "choiceSettingValue": {
          "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingValue",
          "children": [],
          "settingValueTemplateReference": {
            "settingValueTemplateId": "bf13bb47-69ef-4e06-97c1-50c2859a49c2"
          },
          "value": "enrollment_autopilot_dpp_accountype_1" 
        },
        "settingDefinitionId": "enrollment_autopilot_dpp_accountype",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "d4f2a840-86d5-4162-9a08-fa8cc608b94e"
        }
      }
    },
    {
      "@odata.type": "#microsoft.graph.deviceManagementConfigurationSetting",
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationSimpleSettingInstance",
        "settingDefinitionId": "enrollment_autopilot_dpp_timeout",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "6dec0657-dfb8-4906-a7ee-3ac6ee1edecb"
        },
        "simpleSettingValue": {
          "@odata.type": "#microsoft.graph.deviceManagementConfigurationIntegerSettingValue",
          "settingValueTemplateReference": {
            "settingValueTemplateId": "0bbcce5b-a55a-4e05-821a-94bf576d6cc8"
          },
          "value": 30
        }
      }
    },
    {
      "@odata.type": "#microsoft.graph.deviceManagementConfigurationSetting",
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationSimpleSettingInstance",
        "settingDefinitionId": "enrollment_autopilot_dpp_customerrormessage",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "2ddf0619-2b7a-46de-b29b-c6191e9dda6e"
        },
        "simpleSettingValue": {
          "@odata.type": "#microsoft.graph.deviceManagementConfigurationStringSettingValue",
          "settingValueTemplateReference": {
            "settingValueTemplateId": "fe5002d5-fbe9-4920-9e2d-26bfc4b4cc97"
          },
          "value": "Contact your oganization's support person for help."
        }
      }
    },
    {
      "@odata.type": "#microsoft.graph.deviceManagementConfigurationSetting",
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance",
        "choiceSettingValue": {
          "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingValue",
          "children": [],
          "settingValueTemplateReference": {
            "settingValueTemplateId": "a2323e5e-ac56-4517-8847-b0a6fdb467e7"
          },
          "value": "enrollment_autopilot_dpp_allowskip_1"
        },
        "settingDefinitionId": "enrollment_autopilot_dpp_allowskip",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "2a71dc89-0f17-4ba9-bb27-af2521d34710"
        }
      }
    },
    {
      "@odata.type": "#microsoft.graph.deviceManagementConfigurationSetting",
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingInstance",
        "choiceSettingValue": {
          "@odata.type": "#microsoft.graph.deviceManagementConfigurationChoiceSettingValue",
          "children": [],
          "settingValueTemplateReference": {
            "settingValueTemplateId": "c59d26fd-3460-4b26-b47a-f7e202e7d5a3"
          },
          "value": "enrollment_autopilot_dpp_allowdiagnostics_1"
        },
        "settingDefinitionId": "enrollment_autopilot_dpp_allowdiagnostics",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "e2b7a81b-f243-4abd-bce3-c1856345f405"
        }
      }
    },
    {
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationSimpleSettingCollectionInstance",
        "settingDefinitionId": "enrollment_autopilot_dpp_allowedappids",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "70d22a8a-a03c-4f62-b8df-dded3e327639"
        },
        "simpleSettingCollectionValue": [
          {
            "@odata.type": "#microsoft.graph.deviceManagementConfigurationStringSettingValue",
            "value": "{\"id\":\"$($app1.Id)\",\"type\":\"$($app1.AdditionalProperties['@odata.type'])\"}"
          }
        ]
      }
    },
    {
      "settingInstance": {
        "@odata.type": "#microsoft.graph.deviceManagementConfigurationSimpleSettingCollectionInstance",
        "settingDefinitionId": "enrollment_autopilot_dpp_allowedscriptids",
        "settingInstanceTemplateReference": {
          "settingInstanceTemplateId": "1bc67702-800c-4271-8fd9-609351cc19cf"
        },
        "simpleSettingCollectionValue": [
          {
            "@odata.type": "#microsoft.graph.deviceManagementConfigurationStringSettingValue",
            "value": "$($Script1.id)"
          }
        ]
      }
    }
  ],
  "roleScopeTagIds": [
    "0"
  ],
  "platforms": "windows10",
  "technologies": "enrollment",
  "templateReference": {
    "templateId": "80d33118-b7b4-40d8-b15f-81be745e053f_1"
  }
}
"@

$policy = Invoke-MgGraphRequest -Method POST -Uri $uri -Body $body

Assign the Just-In-Time Configuration Device Group

Now that the configuration has been created, we must ensure each group is assigned to the policy, starting with the device group. Note that when you created the policy, we saved the output to $policy. This allows us to obtain the ID of the policy to save into the $uri below.

$uri = "https://graph.microsoft.com/beta/deviceManagement/configurationPolicies('$($policy.id)')/assignJustInTimeConfiguration"

$body = @"
{
  "justInTimeAssignments": {
    "targetType": "entraSecurityGroup",
    "target": [
      "$groupid"
    ]
  }
}
"@

Invoke-MgGraphRequest -Method POST -Uri $uri -Body $body

Assign the Device Preparation Policy to users

The last step is to assign the Device Preparation Policy to your target user group. For this, you are going to re-use the $policy variable saved earlier and you will also obtain the ID of the target user group using a new command.

$uri = "https://graph.microsoft.com/beta/deviceManagement/configurationPolicies('$($policy.id)')/assign"
$usergroupid = Get-MgBetaGroup -Filter "DisplayName eq 'SomeUsers'" | Select -ExpandProperty Id

$body = @"
{
  "assignments": [
    {
      "id": "",
      "source": "direct",
      "target": {
        "groupId": "$Groupid",
        "@odata.type": "#microsoft.graph.groupAssignmentTarget",
        "deviceAndAppManagementAssignmentFilterType": "none"
      }
    }
  ]
} 
"@

Invoke-MgGraphRequest -Method POST -Uri $uri -Body $body

Once you have completed all the steps in this article you will have successfully deployed a Device Preparation Policy using PowerShell.