Onboarding Windows 10 Using Command-Line Enrollment: VMware Workspace ONE Operational Tutorial

VMware Workspace ONE UEM 1810 or later

Overview

Introduction

VMware provides this operational tutorial to help you with your VMware Workspace ONE® environment. This tutorial introduces you to command-line provisioning, one of a variety of Windows 10 onboarding methods supported by Workspace ONE UEM.

You have several onboarding options when using command-line enrollment, including staged provisioning, onboarding with a PC Lifecycle Management (PCLM) solution such as SCCM using VMware Workspace ONE® AirLift™, or deploying a script via a group policy object (GPO), such as a logon script. All of these options have one thing in common: using the command-line parameters supported with the VMware Workspace ONE® Intelligent Hub, which streamlines enrollment.

Audience

This operational tutorial is intended for IT professionals and Workspace ONE administrators of existing production environments. Familiarity with networking and storage in a virtual environment is assumed, including Active Directory, identity management, and directory services. Knowledge of additional technologies such as VMware Identity Manager™ and VMware Workspace ONE® UEM, is also helpful.

Enrolling Windows 10 Using Command-Line Enrollment

Introduction

You have several options when using command-line enrollment. This includes staged provisioning, onboarding with a PC Lifecycle Management (PCLM) solution such as SCCM using Workspace ONE AirLift, and deploying a script via a group policy object (GPO), such as a login script. All of these options have one thing in common: using the command-line parameters supported with the Workspace ONE Intelligent Hub, which streamlines enrollment.

The following figure shows the command-line options that you can use to append the required base command:

The following figure shows examples of command lines:

For more information, see Migrating Devices and Users from SCCM in Operational Tutorial for VMware Workspace ONE: Moving Windows 10 to Modern Management.

Additional Command-Line Enrollment Workflows

The procedures and requirements for enabling command-line enrollment depend on the following variables:

  • Client Type – Domain-joined clients have different requirements from Workgroup (non-domain-joined) devices.
  • Enrollment Scenario – Bare metal imaging and in-place upgrade are staging workflows that have distinct enrollment requirements.

These variables lead to three primary command-line enrollment workflows:

  • Command-Line Enrollment for Domain-Joined Devices With or Without Admin Rights (Shown in Operational Tutorial) – You can leverage VMware Workspace ONE AirLift when devices are currently managed by SCCM, for a more streamlined experience. Overall for domain joined devices, you deploy the Workspace ONE Intelligent Hub with the proper command-line parameters to the device to enroll the current logged-on domain user (silently). If end users do not have admin rights, make sure you are executing the Hub install in System Context.
  • Command-Line Enrollment for Workgroup Devices With or Without Admin Rights – Previously, administrators had to pre-register device serial numbers in the Workspace ONE UEM Console to enable device auto-reassignment. But now with the support of the ASSIGNTOLOGGEDINUSER parameter, you can enable this parameter (=Y) and the end user receives a credential prompt from the Hub to complete enrollment. This eliminates the administrative overhead of having to pre-register devices. End users require admin rights unless the Hub install is executed using system context which requires admin rights.
  • Command-Line Enrollment During Imaging/In-Place Upgrades – For the imaging use case, you set the IMAGE parameter to Y. The VMware Workspace ONE Intelligent Hub is pre-installed on the image and waits for a valid enrollment. This decreases the time after enrollment to wait for the Hub to be installed on the device. For In-Place Upgrades, you can set up the Hub using the staging command-line parameters so that enrollment automatically flips to the user account for the next domain user who logs onto the device.   

Command-Line Enrollment Requirements

The following table compares the requirements (left column) of each of the onboarding options (top row).

In this table, Yes indicates that the workflow must meet the listed requirement. Following the same logic, No indicates the workflow does not need to meet the listed requirement. Footnotes provide additional details about the requirements.


Domain Joined Devices 
Workgroup Devices 
Imaging/ In-Place Upgrades
Requirements
Workspace ONE UEM Console 1810 and later

Workspace ONE Intelligent Hub for Windows 1810 and later
Yes Yes Yes
Domain-Joined Client
Yes
No1
N/A
Workspace ONE Intelligent Hub for Windows deployed using System Context in your PCLM solution (such as SCCM)
Yes
Yes
Yes2
Staging Account, with Standard Single User Devices Enabled
Yes
Yes
Yes
Staging Organization Group Yes3
Yes3

Yes
PowerShell Execution Policy Set to Bypass
No
Yes4
No
User Group Mapping Enabled at highest Organization Group5
Yes Yes Yes
Additional Resources
Production Sample




Blog

  1. The mismatch between the local account and the domain users in the Workspace ONE UEM Console causes auto-reassignment to fail for Workgroup devices. After auto-reassignment fails, the system prompts for a username and password.
  2. Your PCLM solution (such as SCCM) only — this requirement does not apply to MDT.
  3. Required only if SAML is enabled in your Workspace ONE UEM environment. No longer required starting in Workspace ONE UEM 1811.
  4. In the SCCM Console, navigate to Administration > Client Settings > Default Settings > Computer Agent. Scroll down to Powershell execution policy and set it to Bypass.
  5. User Group Organization Group or Fixed Organization Group enabled so that end users are not prompted for a Group ID. To configure this setting, navigate to Settings > Devices & Users > General > Shared Device.

Prerequisites

Before you can perform the procedures in this tutorial, verify that your system meets the following prerequisites:

  • Workspace ONE UEM 1810 or later
  • Workspace ONE UEM admin account
  • Credentials for a staging user account (this account has permission to stage the device on behalf of the user)
  • Uses login scripts
  • A domain-joined device

Configuring Command-Line Enrollment: Basic Sample Using GPO

This activity guides you through a basic command-line enrollment using GPO. The provided files are samples. Your parameter values will differ.

1. Download the Workspace ONE Intelligent Hub

  1. On the Windows 10 device to enroll and provision, navigate to https://getwsone.com.
  2. Download the latest VMware Workspace ONE Intelligent Hub.

2. Create a *.BAT File

Create a script to check for enrollment and if not already enrolled, perform the enrollment with the parameters for your given use-case. The following batch script is a sample script.

REM Check if device is already registered with Workspace ONE, if not then proceed with installing Workspace ONE Intelligent Hub
for /f "delims=" %%i in ('reg query HKLM\SOFTWARE\Microsoft\Provisioning\OMADM\Accounts /s') do set status=%%i
if not defined status goto INSTALL
:INSTALL
REM Run the Workspace ONE Intelligent Hub Installer to Register Device with Staging Account
REM msiexec /i “<PATH>\AirwatchAgent.msi” /quiet ENROLL=Y SERVER=<DS URL>
LGName=<GROUP ID> USERNAME=<STAGING USERNAME> PASSWORD=<STAGING PASSWORD> ASSIGNTOLOGGEDINUSER=Y DOWNLOADWSBUNDLE=True /log <PATH TO LOG>
msiexec /i “\\192.168.6.87\AirWatchAgent.msi” /q ENROLL=Y SERVER=ds135.awmdm.com LGName=techzone USERNAME=stagingtechzone PASSWORD=P@ssw0rd ASSIGNTOLOGGEDINUSER=Y DOWNLOADWSBUNDLE=TRUE /LOG %temp%\WorkspaceONE.log

3. Revise the Script

Revise the script command example so that it uses the correct information for your deployment. The REM portion of the script explains the syntax, as follows:

  • For <PATH>, enter the path to the Hub that you downloaded to the device.
  • For <DS URL>, enter the enrollment (Device Services) URL.
  • For <GROUP ID>, enter the short name (Group ID) of the organization group.
  • For <STAGING USERNAME> and <STAGING PASSWORD>, enter the credentials of the staging user account that has permission to stage the device on behalf of the user.

4. Create a Group Policy Object

On the domain controller, open Group Policy Management, create a new Group Policy Object and link it to your devices and users.

Note: For domain-joined devices, you can do the following to deploy this script using a Group Policy Object (GPO):

  • If you are using a PCLM tool, you can leverage your PCLM to push out the Workspace ONE Intelligent Hub with command parameters.
  • If you are using Microsoft SCCM, use Workspace ONE AirLift.

6. Log In to Device

On the device, log in as the staging admin.

Workspace ONE UEM onboards and provisions the device profiles.

7. Ship the Device to the End User

  1. When provisioning is completed, shut down the device.
  2. Provide the device to the end user.

When the end user logs into the device, the Hub listener reads the User Principal Name (UPN) from the device registry and sends the information to the Workspace ONE UEM Console. The device registry is updated to register the device to the user.

Configuring Command-Line Enrollment for Non-Admin AD Users

Introduction

Because most Active Directory (AD) users don’t have permissions to install MSI’s, we can leverage Active Directory software distribution to push out the Workspace ONE Intelligent Hub. There is a significant limitation to this feature; installation parameters are not supported. The installation parameters are required because the installation of the Workspace ONE Intelligent Hub should be done using environment specific information as described in detail in the Introduction section.

This activity explores the two different methods to accomplish this; select the option which works best for your organization.  

  • The first option describes how to use a script to change the Workspace ONE Intelligent Hub MSI (AirWatchAgent.msi) automatically and then describes how to configure a GPO to install the MSI.
  • The second option describes how to manually create a Transform (MST) to configure the corresponding installation parameters for the Workspace ONE Intelligent Hub MSI and how to configure a GPO to install the Workspace ONE Intelligent Hub MSI (AirWatchAgent.msi) using this Transform file.

Prerequisites

Before you can perform the procedures in this tutorial, verify that your system meets the following prerequisites:

  • Workspace ONE UEM 1810 or later
  • Workspace ONE UEM admin account
  • Uses login scripts
  • A domain-joined device

Option 1: Using a Script to Modify Workspace ONE Intelligent Hub

In this activity, you use a script to change the AirwatchAgent.msi automatically. This option does not use a Transform (*.MST) file, therefore the AD GPO is easier to configure.

1. Download the Workspace ONE Intelligent Hub

  1. On the Windows 10 device to enroll and provision, navigate to https://getwsone.com.
  2. Download the latest VMware Workspace ONE Intelligent Hub.

2. Update the Workspace ONE Intelligent Hub MSI

The most straightforward way to update the AirwatchAgent.msi with the correct installation parameters is to use the sample script hosted on VMware {code} Sample Exchange.  

This script alters the AirwatchAgent.msi to include the arguments and parameters for command line enrollment. This altered MSI can be deployed with an Active Directory Software installation GPO for silent enrollment into Workspace ONE UEM.

  1. Download the sample script.
  2. Update the four placeholders 'SERVER', 'LGNAME', 'USERNAME', and 'PASSWORD' in the script to the correct values for your Workspace ONE UEM environment.
  3. Run this script with the name of the AirwatchAgent.msi as an argument and the MSI file is updated.
  4. Store the AirwatchAgent.msi on a file share (for example, \\server\share) so every Active Directory user can access the file by using a UNC path.
  5. You can validate if the change to the MSI was successful by manually installing the MSI with this installation command and see if the device gets enrolled.
msiexec.exe /i \\server\share\AirwatchAgent.msi /q /log %temp%\AWagent.log

3. Create a Group Policy Object to Install the Workspace ONE Intelligent Hub

The next step is to create an Active Directory Group Policy Object (GPO) to install the Workspace ONE Intelligent Hub and enroll Windows 10 devices. This example uses a User GPO because the software installation should be triggered at user logon.

  1. Open the Active Directory Group Policy Editor.
  2. Create a new GPO and link it to the Active Directory OU that contains the users that need to get enrolled.
  3. Edit the GPO and navigate to User Configuration > Policies > Software Settings > Software Installation.
  4. Select New > Package and browse to \\server\share\AirwatchAgent.msi (requires UNC path).
  1. Select Assigned to allow automatic installation of the AirwatchAgent.msi.
  1. On the Deployment tab, select the following options:
    • Deployment Type – Assigned
    • Deployment Options – Install this application at logon
    • Installation User Interface Options – Basic

The GPO is now created, and you can start the enrollment. Log in to a device with a standard AD user to test the enrollment.

Option 2: Using a Transform File to Modify Workspace ONE Intelligent Hub

If you do not want to use the script, there is an alternative, manual solution. Microsoft provides a free tool to create Transforms, called Orca. This tool is part of the Windows 10 SDK. This option allows you to update the Workspace ONE Intelligent Hub manually—it allows you to use a Transform (.MST) file, as opposed to changing the MSI directly.

In this activity, you create and configure the Transform file and then you create a GPO to install the Workspace ONE Intelligent Hub using that Transform file.

1. Create the Transform File

Perform the following steps on a Windows 10 device.

  1. Download the Windows 10 SDK installer winsdksetup.exe and run it.
    • Only select the MSI Tools option
  2. After the Windows 10 SDK installation has completed, install Orca using the Orca installer which is located in:
C:\Program Files (x86)\Windows Kits\10\bin\10.0.#####.0\x86\Orca-x86_en-us.msi
  1. Run the Orca tool by clicking C:\Program Files (x86)\Orca\Orca.exe 
  2. Download the latest Workspace ONE Intelligent Hub MSI from https://getwsone.com
  3. Using Orca, select File, then Open (Ctrl+O) and browse to the downloaded AirwatchAgent.msi.
  4. Create a new Transform by selecting Transform, then New Transform.
  1. On the left, select the Property table and add the following new rows by clicking Tables, then Add Row (Ctrl+R).
    • SERVER – Enter the URL of your Workspace ONE environment. For example, as###.awmdm.com.
    • LGNAME – Enter the Group ID of the enrollment Organization Group. For example, techzone.
    • USERNAME – Enter the staging account username. For example, stagingtechzone@techzone.com.
    • PASSWORD – Enter the staging account password. For example, S3cr3t.
    • ENROLL – Enter Y. This value triggers the enrollment into Workspace ONE.
    • ASSIGNTOLOGGEDINUSER – Enter Y. This value automatically assigns the device in the Workspace ONE UEM console to the logged in AD user.
    • (Optional) DOWNLOADWSBUNDLE – Enter True. This setting downloads the Workspace ONE app during enrollment.
  2. Save the changes to the Transform by clicking Transform, then Generate Transform. Save the file as WS1_AD_Enroll.mst, for example.
  3. Store both files (WS1_AD_Enroll.mst and AirwatchAgent.msi) on a file share accessible to every AD user using a UNC path.

The following video provides a detailed demonstration of this procedure:

2. Create a Group Policy Object to Install the Agent Using a Transform File

For this manual method, the GPO must be created with the option to apply a Transforms file. The following steps explain how to create an Active Directory Group Policy Object (GPO) to install the Workspace ONE Intelligent HUB with the Transform and enroll Windows 10 devices. This example uses a User GPO because the software installation should be triggered at user logon.

  1. Open the Active Directory Group Policy Editor.
  2. Create a new GPO and link it to the Active Directory OU that contains the users that require enrollment. 
  3. Edit the GPO and navigate to User Configuration > Policies > Software Settings > Software Installation.
  4. Select New > Package and browse to \\server\share\AirwatchAgent.msi (requires UNC path).
  1. Select Advanced to allow adding the created Transform (MST).
  1. On the Deployment tab, select the following options:
    • Deployment Type – Assigned
    • Deployment Options – Install this application at logon
    • Installation User Interface Options – Basic
  1. On the Modifications tab, click Add and select the Transform file \\server\share\WS1_AD_Enroll.mst.
  2. Click OK to create the software deployment task.

The GPO is now created and you can start the enrollment. Log in to a device with a standard AD user to test the enrollment.

The following video provides a detailed demonstration of this procedure:

Command-Line Enrollment Best Practices

This section contains some best practices to follow when enabling command-line enrollment.

  • Enable detailed installation status for end users so they know what is going on when they logon to their device. You can enable the computer GPO Display Highly Detailed Status Messages, to see progress messages during user logon as shown in the screenshot.
  • Ensure your Active Directory is correctly synchronized with Workspace ONE UEM. If you are using the MSI and MST files, ensure they are hosted on a UNC file share and that the AD users have proper access to them during enrollment.
  • Link the GPO to an OU that contains the user accounts. If you want to link the GPO to an OU that contains Computer accounts, make sure to enable Loopback Processing. For more information see, Loopback processing of Group Policy.

Summary and Additional Resources

Conclusion

This tutorial introduces you to the command-line enrollment functionality of Workspace ONE UEM, and explains how to use this functionality to enroll Windows 10 devices before delivery. A set of exercises describe how to configure this workflow method on your system. The end result is your ability to manage the Windows 10 device enrollment before the device ever reaches the end user, or to enroll a Windows 10 device silently to devices already out in the field being managed by the domain, SCCM, or another PLCM solution.

Appendix: Deploying the Integration Client

If you are using SCCM, you can leverage

1. Download the Integration Client

  1. From

2. Install the Client

  1. In a production environment, use your PCLM solution (such as SCCM) or domain group policies to push the MSI file to managed devices and install the client.
    Note: For more information about SCCM, see Microsoft support and documentation.
  2. After installation, end users can enroll Windows 10 devices using any onboarding method.

Terminology Used in This Tutorial

The following terms are used in this tutorial:

Term Description
adaptive access
The ability to control access and authentication methods to sensitive apps based on a device’s managed status.
additive
Includes only changes developed after the latest version of the application or the last additive patch.
app dependencies
Applications required by the environment and devices to run the Win32 application.
app patches
Files that apply additive or cumulative fixes, updates, or new features to applications.
app transforms
Files that control application installation and can add or prevent components, configurations, and processes during the process.
app uninstall process
Scripts that instruct the system to uninstall an application under specific circumstances.
application store A user interface (UI) framework that provides access to a self-service catalog, public examples of which include the Apple App Store, the Google Play Store, and the Microsoft Store.
auto-enrollment Auto-enrollment simplifies the enrollment process by automatically enrolling registered devices following the Out-of-Box-Experience.
BitLocker Full disk encryption available for Windows, focused on addressing data leakage or data theft scenarios from stolen, lost, or incorrectly decommissioned devices.
bring your own device (BYOD) The process of providing secure access to corporate data, apps, and content on an employee-owned device without invading employee privacy to their personal data, apps, or content.
business mobility The concept of being able to provide secure access to your business services, infrastructure, and content to enable your workforce to work remotely.
catalog A user interface (UI) that displays a personalized set of virtual desktops and applications to users and administrators. These resources are available to be launched upon selection.
cloud Asset of securely accessed, network-based services and applications. A cloud can also host data storage. Clouds can be private or public, as well as hybrid, which is both private and public.
conditional access To provision access to a resource or service, based on user entitlements or roles.
container The separation of corporate and personal data on employee-owned devices, allowing IT administrators to manage corporate applications and profiles without invading employee privacy or personal apps and content.
cumulative Includes the entire application, including any changes since the latest version of the application, or the last patches.
data leakage protection Software-controlled policies that determine how and where data can be transferred or shared to.
device enrollment The process of installing the mobile device management agent on an authorized device. This allows access to VMware products with application stores, such as VMware Identity Manager.
Device Health Attestation Module that gathers device health measurements and reports these measurements to the Health Attestation Service for evaluation.
enrollment The process of allowing your device to be managed by the software-defined policies of the chosen enterprise mobility management provider.
enterprise mobility management The concept of using software and policies to both secure and provide access controls for mobile devices.
files and actions The combination of the files delivered to a device and the actions that file performs on the device. Files and actions cannot be assigned directly to a device. Instead, assign files and actions to a product, which then provisions to devices.
Health Attestation Services Cloud service that evaluates health measurements from the device to determine the health state.
identity-as-a-service Identity and access management services through the cloud to provide SSO identity federation and user-access provisioning.
identity provider (IdP) A mechanism used in a single-sign-on (SSO) framework to automatically give a user access to a resource based on their authentication to a different resource.
mobile application management The concept of managing access, deployment, and restrictions of mobile applications using software and services.
mobile device management
(MDM) agent
The concept of managing mobile devices using software installed on an authorized device to monitor, manage, and secure end-user access to enterprise resources.
multi-factor authentication Access control process that requires users to authenticate using more than one method of authentication by providing something the user knows (a password) and something the user has, such as a hardware token, smartcard, or phone, or something the user is, such as a fingerprint or retina.
one-touch login A mechanism that provides single sign-on (SSO) from an authorized device to enterprise resources.
per-app VPN Policies that allow individual apps to access VPN configurations without granting device-wide access to the VPN connection.
public app stores Portals where users can access and obtain publically published applications, such as the iOS App Store and Google Play Store.
service provider (SP)
A host that offers resources, tools, and applications to users and devices.
smart groups Groups that control which devices get which product, based on how the group is created.
step-up authentication Restricting applications or services to require a stronger authentication method, depending on the sensitivity or severity of the resource.
unified endpoint management A single platform that allows organizations to manage and secure every endpoint, any app, and content across deployment use cases.
virtual desktop The user interface of a virtual machine that is made available to an end user.
virtual machine A software-based computer, running an operating system or application environment, that is located in the data center and backed by the resources of a physical computer.
Windows Information Protection Formerly Enterprise Data Protection (EDP), a Windows solution to assist in preventing data leakage without impeding the user experience.

Additional Resources

Searching for More Information

When looking for more VMware documentation, you can focus the search using the Advanced Search option.

  1. In the VMware Workspace ONE Documentation window, select the gear icon to start an advanced search.
  2. Enter words or phrases to start the search.
    Example: To search for an article that you think is called Compliance Profile Overview, you might include just the key words, in case the article now has a different name.
  3. Narrow the results by selecting specific criteria.
    Example: The search is limited to the specific product and version.
  4. Click Advanced Search.
  5. In the resulting hit list, you can select a hit. Or you can either apply Sort By filters, or narrow the results further by clicking Advanced Search.

About the Authors

This tutorial was written by:

  • Josué Negrón, EUC Staff Architect, End-User-Computing Technical Marketing, VMware
  • Hannah Horton, EUC Technical Marketing Manager, End-User-Computing Technical Marketing, VMware

Considerable contributions were made by the following subject matter experts:

  • Varun Murthy, Product Line Manager, VMware
  • Brooks Peppin, Sr. Product Manager, VMware
  • Darren Weatherly, Specialist Systems Engineer, VMware
  • Mike Nelson, Sr. Solutions Architect, VMware
  • Pim van de Vis, Sr. Solutions Architect, VMware
  • Rob Kelley, Sr. Solutions Architect, VMware

Feedback

The purpose of this tutorial is to assist you. Your feedback is valuable. To comment on this tutorial, contact VMware End-User-Computing Technical Marketing at euc_tech_content_feedback@vmware.com.