Product documentation
Workspace Environment Management
Service Current Release 2311 2308 2305 2303 2212 2209 2206 2203
View PDF

Enroll agents

November 8, 2022
Contributed by: 
C

Introduction

You can enroll Workspace Environment Management (WEM) agents without configuring Citrix Cloud Connectors. Before you do that, consider the following:

This feature requires that you select Skip Configuration when installing the agent and that you do not enable the Discover Citrix Cloud Connector from CVAD service policy.

Enroll agents

You have the flexibility to determine how to enroll your WEM agents. There are two ways:

  • Enroll by invitation. This requires the web console. Users can be invited to participate in the enrollment process.

  • Enroll with the bearer token or API secure client. This doesn’t require the console and doesn’t require users to participate in the enrollment process.

Enroll by invitation

To manage user devices remotely and securely, you enroll user devices in WEM.

A general workflow to enroll by invitation is as follows:

  1. In Manage > Web Console > Enrollment > Invitation, enable Enroll by invitation and then generate an enrollment key.

  2. On the agent machine, install the enrollment key using the enrollment tool.

    1. Open the command prompt as the administrator.

    2. Run the following command.(Replace <enrollment key> with the actual key.)

      • Citrix.Wem.Agent.EnrollmentUtility.exe configenrollmentkey -k <enrollment key>

      Tip:

      • The enrollment tool, Citrix.Wem.Agent.EnrollmentUtility.exe, is available in the agent installation folder. For more information, see Enrollment tool.
      • When preparing a master image, you can install the agent on the master image. Then, you use the master image as a template for creating machines for your users. This way, you don’t need to install the enrollment key for each agent.

  3. In Manage > Web Console > Enrollment > Invitation, send an enrollment invitation to users.

After users receive the invitation, they can enroll their devices using the invitation code. See Enroll the agent with an invitation code.

After a device enrolls, it becomes managed and appears in Manage > Web Console > Enrollment > Enrolled Agents. You can add it to a desired configuration set for precise management. See Manage the enrolled agent.

Enroll the agent with an invitation code

Important:

Enrolling an agent requires local administrator permissions.

As users, you receive the following invitation email:

Invitation email

Enroll your device using the invitation code as follows:

  1. Open your desktop Start menu and select Citrix > WEM Enrollment Registration Utility.

    Tip:

    If the utility is not available in the Start menu, go to the WEM agent installation folder and open Citrix.Wem.Agent.Enrollment.RegUtility.exe.

  2. In Enrollment Registration Utility, verify that the status of the enrollment key is Installed and click Enroll Agent.

    Note:

    If the status of the enrollment key is not Installed, contact your administrator.

  3. In the Enroll Agent window, paste the invitation code (copied from the invitation email) and click Start Enrolling.

If the agent enrolls successfully, you see the following message: The agent was enrolled successfully. You can click Close to return to Enrollment Registration Utility, which shows the following information:

Enrollment registration utility

Note:

Enrolling with the bearer token or API secure client does not require the participation of the enrollment key. If you use the Enrollment Registration Utility to check the enrollment status on an agent machine enrolled with the bearer token or API secure client, the Enrollment key status field appears as Not installed and the Enrollment status field appears as Enrolled.

Enroll with the bearer token or API secure client

To enroll an agent machine, perform the following steps:

  1. Sign in to Citrix Cloud and get a bearer token or an API secure client for authentication to the Citrix API service. For information about how to generate an API secure client and a bearer token, see Get started with Citrix Cloud APIs.

  2. Log on to the machine that has the agent installed.

  3. Open a command prompt window.

    • To enroll the agent with the bearer token, type the following command:

      • Citrix.Wem.Agent.EnrollmentUtility.exe enroll --customer "customerid" --bearer "bearertoken" --url "api.wem.cloud.com"

      Tip:

      When using a bearer token, be aware that the base URL is unique for each region. For more information, see Base URLs. If unspecified, the URL for the US region (api.wem.cloud.com) is used.

    • To enroll the agent with the API secure client, type the following command:

      • Citrix.Wem.Agent.EnrollmentUtility.exe enroll --customer "customerid" --clientid "clientid" --clientsecret "clientsecret" --authurl "api-us.cloud.com" --url "api.wem.cloud.com"

      Tip:

      • When using a secure client, be aware that there are two URLs.
      • The first URL is the authentication URL, which is unique for each region. For more information, see Get started with Citrix Cloud APIs. If unspecified, the URL for the US region (api-us.cloud.com) is used.
      • The second URL is the base URL, which is also unique for each region. For more information, see Base URLs. If unspecified, the URL for the US region (api.wem.cloud.com) is used.

Alternatively, in Step 3, create a configuration file in JSON format and use the file with the following command:

  • Citrix.Wem.Agent.EnrollmentUtility.exe enroll --config "configfilepath"

Note:

We recommend that you delete the configuration file after the enrollment because the file contains sensitive information.

The format of the configuration file is as follows:

Tip:

When using a bearer token or secure client, you can leave the corresponding fields empty.

    {

    "CustomerId": The Citrix Cloud customer ID,

    "ClientId": The secure client ID of the Citrix Cloud API client,

    "ClientSecret": The secure client secret of the Citrix Cloud API client,

    "AuthUrl": The base URL of the Citrix Cloud API used to get the bearer
    token,

    "BearerToken": The Citrix Cloud bearer token,

    "BaseUrl": The base URL of the WEM RESTful APIs

    }

<!--NeedCopy-->

Example output:

Example output

Manage the enrolled agent

After enrolling an agent, use the management console to bind it to a desired configuration set for precise management.

Note:

  • After you add an enrolled non-domain-joined machine, the agent first registers with the Default Site configuration set or the Unbound Agents configuration set (if enabled). After the agent is registered, you can add the machine to other configuration sets.

Key creation and rotation

A service key is created in the cloud when an agent enrolls into WEM successfully. Consider the following rules:

  • The key expires in 90 days. After it expires, the agent must connect to the WEM service to rotate the key. By default, the agent automatically connects to rotate the key 14 days before the expiration.
  • The expired key is kept for 180 days. The agent must rotate the key within 180 days. After that, the key will be deleted.
  • If the key is deleted, the agent using the key can no longer connect to the WEM service. The agent must be reenrolled.

Note:

An identity change can cause a mismatch between the service key and the agent identity. An identity change can occur, for example, when an agent machine joins or leaves a domain. In that case, you must let the agent connect to the WEM service when the key is still valid so that the agent can rotate the key.

Enrollment tool

The agent enrollment tool, Citrix.Wem.Agent.EnrollmentUtility.exe, is available in the WEM agent installation folder. By default, the agent is installed in the following default folder.

  • C:\Program Files (x86)\Citrix\Workspace Environment Management Agent (on 64-bit OS)
  • C:\Program Files\Citrix\Workspace Environment Management Agent (on 32-bit OS)

Command-line options with the enrollment tool

The tool has the following options:

Parameter Description
status Displays the current enrollment status of the agent machine.
enroll Enrolls the agent machine with the Citrix Workspace Environment Management service.
configenrollmentkey Configures the enrollment key.
help Displays more information on a specific command.
version Displays version information for the tool.

For example, to display agent enrollment status, type the following command:

  • Citrix.Wem.Agent.EnrollmentUtility.exe status

The tool provides the following options for enrollment:

Parameter Description
–config Reads configurations from a configuration file in JSON format.
-c, –customer The Citrix Cloud customer ID.
-b, –bearer The Citrix Cloud bearer token.
–clientid The secure client ID of the Citrix Cloud API client.
–clientsecret The secure client secret of the Citrix Cloud API client.
–authurl The base URL of the Citrix Cloud API used to get the bearer token. Default: api-us.cloud.com.
-u, –url The base URL of the WEM RESTful APIs. Default: api.wem.cloud.com.
-f, –force Enrolls the agent machine regardless of its current enrollment status. Default: false.
-k, –key Sets the enrollment key.
-f, –file Reads the enrollment key from a file and sets the enrollment key.
-s, –status Shows the current status of the enrollment key.
–help Displays cmdlet help.
–version Displays version information for the tool.

Return codes

The tool can return the following codes:

Code Description
0 No error
1 Invalid arguments
2 Insufficient permissions
3 Agent host service not ready
4 Error while calling remote APIs
100 Unhandled exception
1000 Agent not enrolled
1001 Agent currently enrolled. When enrolling the agent, the operation is skipped unless the –force option is specified.
2000 Enrollment key not installed
2001 Enrollment key installed

Unenroll the agent

To unenroll the agent, use the agent installer when uninstalling the agent, with the following command:

  • citrix_wem_agent_bundle.exe /uninstall Disenroll=1

After uninstalling the agent, the following registry key is removed:

  • HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\WEM\Agent\EnrollmentData
Enroll agents
November 8, 2022
Contributed by: 
C
November 8, 2022
Contributed by: 
C

In this article

Site feedback | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.