Windows device lifecycle. Hands-off reprovisioning with Workspace ONE.

There are multiple options available for onboarding a Windows desktop into Workspace ONE UEM. Different options are available depending on if the device is a Greenfield device (brand new out-of-the-box device) or a Brownfield device (currently used device, possible under a legacy device management system). But what about device recycling? How do you enroll a device that has been returned to IT? Typically, this is a hands-on approach and will involve multiple steps that will look something like:

• Re-imaging the device, via USB or Windows Deployment Services (WDS).
• Logging in as the staging account.
• Downloading Intelligent Hub.
• Enrolling as the staging user.
• Logging out.
• Handing the device off to the final end user, or placing it back into stock.
• Workspace ONE Tunnel (or other pre-auth VPN) if the device is to be domain joined.
• If testing using a VM, ensure that the VM has been assigned a serial number

What if there was a better way? What if you could deploy a new image to a device and have the image deployment process automatically enroll the device? Well, this is possible with Workspace ONE UEM. Read on if you want to know how you can set this up.

Workspace ONE Drop Ship Provisioning (Online)

Drop Ship Provisioning (Online), or DSP (Online) as its typically shortened to, is a process that allows a devices serial number to registered into a specific Workspace ONE UEM instance, similar to the way that Apple devices are enrolled into Apple Business Manager. This registration can be done either by a device OEM for new devices, or by a UEM administrator directly into the console for already owned devices. When the devices serial number is registered, the Dropship Provisioning package can be applied to the device during audit mode which will then install Intelligent Hub and automatically enroll the device into the associated Workspace ONE UEM tenant. This process can also domain join a device and when using the Workspace ONE Tunnel, allow a user to login to a device using their domain credentials without the device ever being connected to the corporate domain. 

I'm not going to go into the Drop Ship provisioning process in this post, but it is very straight forward to setup and the documentation is available here. Instead, I am going to describe how to include DSP provisioning in the device rebuild process so all that is needed is to start the imaging process on the device.

Requirements:

• Windows 10/11 ISO image
• Utility to write the ISO to a USB drive if not using WDS (my preferred is Rufus)
• WDS server, if using WDS
• Dropship-GenericPPKG-ProvTool3 package, available for download from my.workspaceone.com here
• Offline domain join configured, if the device needs to join to a domain

Step 1: Create oAuth credentials

The device registration process uses the Workspace ONE UEM API's which require authentication. Follow the steps here to create an account and note down the Client ID and Client Secret.

Step 2: Prepare the ISO image.

Download the ISO image from Microsoft and apply the image to a USB drive. If using WDS, extract the contents of the ISO file to a folder. We will be working directly on the files that are contained as part of the Windows install media.

Step 3: Obtain the Windows Edition Index from the install media.

A windows ISO typically contains multiple windows editions. We need to identity the index of the image that we want to use. To do this, run the following command from a command line specifying the location of the install.wim on the install media (either the USB drive or the extracted ISO image). In the example, the install.wim is located on the D drive which is a USB drive and has in Index of 3

Dism /Get-WimInfo /WimFile:d:\Sources\install.wim

Step 4: Extract the contents of install.wim

Using the index of the required windows edition, use the following command to extract the .wim file to the specified folder. In this example the files contents is being extracted to c:\Mount. Create the folder if it does not exist

Dism /Mount-Image /ImageFile:D:\Sources\install.wim /Index:3 /MountDir:C:\Mount

Step 5: Update the Windows image.

The install.wim file contains a mirror image of all the files that make up the Windows O/S file system. We are going to make some changes to this so that when Windows is installed, it kicks off the enrollment process.

5(a). Create a file called unattend.xml in Windows\Panther folder in the extracted file location and add the XML shown below. Example, c:\Mount\Windows\Panther. The Panther folder may or may not exist, if it does not exist, create it. This file will cause the device to enter audit mode at first boot, register the devices serial number and trigger the DropShip provisioing process.

Unattend.xml contents:

<?xml version="1.0" encoding="utf-8"?>

<unattend xmlns="urn:schemas-microsoft-com:unattend">

    <settings pass="oobeSystem">

        <component name="Microsoft-Windows-Deployment" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS" xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

            <Reseal>

                <Mode>Audit</Mode>

            </Reseal>

        </component>

    </settings>

    <settings pass="auditUser">

        <component name="Microsoft-Windows-Deployment" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS" xmlns:wcm="http://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

            <RunAsynchronous>

                <RunAsynchronousCommand wcm:action="add">

                    <Order>1</Order>

                    <Path>powershell.exe -NoLogo -NoExit -W Maximized -EP Bypass -File C:\WorkspaceONE\DSP_Register.ps1</Path>

                    <Description>Register the device with DSP</Description>

                </RunAsynchronousCommand>

                <RunAsynchronousCommand wcm:action="add">

                    <Order>2</Order>

                    <Description>Initiate DSP Enrollment</Description>

                    <Path>C:\WorkspaceONE\RunPPKGandXML.bat</Path>

                </RunAsynchronousCommand>

            </RunAsynchronous>

        </component>

    </settings>

    <cpi:offlineImage cpi:source="wim:c:/users/admin/desktop/install.wim#Windows 11 Enterprise" xmlns:cpi="urn:schemas-microsoft-com:cpi" />

</unattend>

5(b). Create a folder called WorkspaceONE in the root of the mount folder, example c:\mount\WorkspaceONE and extract the DSP provisioning package (Dropship-GenericPPKG-ProvTool3) here. 

5(c). Edit RunPPKGandXML.bat and change the -s switch to a -r. This will trigger a device reboot allowing the process to continue rather than a shutdown:

5(d). Add the DSP registration PowerShell script shown below to this same folder. Ensure this script is called DSP_Register.ps1 (or update the unattend.xml file above with the actual filename). Ensure to update the script with the correct values for client_id, client_secret, oguuid, tag name, ownership and apiserver. See steps as the end of this guide for how to obtain the oguuid and apiserver values needed.

DSP_Register.ps1

$client_id = "[Client ID]" 

$client_secret = "[Client Secret]"

$OGUUID = "1234AAAA-1122-CCDD-9900-0123456789AB"

$tag = "DSPOnline1"

$ownership = "CorporateDedicated"

$acces_token_url = "https://na.uemauth.vmwservices.com/connect/token"

$apiServer = "[API Server name eg: as1234]"

try

{

$oAuthbody = @{ 

    grant_type = "client_credentials" 

    client_id = $client_id 

    client_secret = $client_secret 

}

   $response = Invoke-WebRequest -Method Post -Uri $acces_token_url -Body $oAuthbody -UseBasicParsing

   $oAuthToken = $response | ConvertFrom-Json 

   $oAuthToken = $oAuthToken.access_token

   #Get local device information

   $win32_bios = Get-WmiObject win32_bios

   $win32_computersystem = Get-WmiObject win32_computersystem

   $friendly_name = $win32_computersystem.Name

   $serial_number = $win32_bios.SerialNumber

   $model_number = $win32_computersystem.Model

   $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"

   $headers.Add("Authorization", "Bearer $oAuthToken")

   $headers.Add("Accept", 'application/json;version=3')

   $headers.Add("Content-Type", "application/json")

   $body = @"

   {

      "friendly_name": "$friendly_name",

      "serial_number": "$serial_number",

      "model_number": "$model_number",

      "organization_group_uuid": "$OGUUID",

      "tags": [{name: "$tag"}],

      "ownership_type": "$ownership"

   }

"@

   #Register the device serial

   $URI = "https://$apiServer.awmdm.com/api/mdm/enrollment-tokens"

   $response = Invoke-WebRequest -Uri $URI -Headers $headers -Method POST -Body $body -UseBasicParsing

   $response.Content | ConvertFrom-Json

   #Sync the device

   $URI = "https://$apiServer.awmdm.com/API/mdm/dropship-action/organization-group/$OGUUID/sync-devices"

   $response = Invoke-WebRequest -Uri $URI -Headers $headers -Method POST -UseBasicParsing

   $response.StatusDescription

}

catch

{

   Write-Host "StatusCode: $_.Exception.Response.StatusCode.value__ "

   Write-Host "StatusDescription: $_.Exception.Response.StatusDescription"

   Write-Host $_.Exception.message

}

Step 6: Apply changes to install.wim

Use the following command to apply the changes (unattend.xml, and WorkspaceONE folder) to the install.wim image:

dism /Unmount-Image /MountDir:C:\Mount /Commit

Step 7: (Optional) Specify the Windows Edition to automatically install (USB drive only)

Instead of manually selecting the Windows Edition during the Windows setup process, the installer can be configured to install a specified edition. Edit the D:\Sources\ei.cfg and specify the name of the edition to install (enterprise in the example). Update the Channel as appropriate with either Volume, OEM or Retail.

[EditionID]

Enterprise

[Channel]

Volume (or OEM or RETAIL)

[VL]

0

Step 8: Eject the USB drive or add the updated install.wim to WDS

Step 9. Boot the device with the USB drive or install the updated wim to the device via WDS

The Windows installer will install the O/S, Once complete, the device will automatically reboot into audit mode and make the API call to register the device with the Workspace ONE UEM tenant. The device will reboot out of audit mode and then install Intelligent Hub and enroll the device as well as joining the device to the domain as the last step in the deployment process. Once complete, the device can be shut down and delivered to the end user.

Obtaining apiserver and oguuid

The apiserver value is the name of the server that hosts the Workspace ONE UEM API code. This can be found from within the UEM Console. Go to Groups & Settings > All Settings > System > Advanced > Site URLs. The server name will be listed under Rest API URL and typically starts with "as" followed by some numbers. e.g. as135. 

The easiest way to obtain oguuid is by using Intelligence. Log into Intelligence, go to Reports > Add > Custom Report. Select Category > Workspace ONE UEM > Devices. Click the Blue + button on the right of the Report Preview table and add the Organization Group GUID and Device Organization Group Name columns. Refresh the report preview and the value shown under Organization Group GUID is the oguuid value. Cross reference this with the Organization Group name where DSP (Online) is configured shown under the Device Organization Group Name column.