Enroll agents
Introduction
You can enroll Workspace Environment Management (WEM) agents without configuring Citrix Cloud Connectors. Before doing so, consider the following:
- The enrollment applies to both domain-joined and non-domain-joined machines.
- For Citrix DaaS managed VMs, we recommend using the same method to connect the agent to Citrix Cloud as you do for the VDA — through the Cloud Connector or the non-domain-joined method. See Determine which setup method to use.
- To ensure that persistent VMs enroll properly:
- Remove machine-specific information by generalizing a VM before creating an image. For information about using Sysprep to generalize a VM, see the Microsoft product documentation: https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/sysprep--generalize--a-windows-installation?view=windows-11.
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:
-
In Manage > Web Console > Enrollment > Invitation, enable Enroll by invitation and then generate an enrollment key.
-
On the agent machine, install the enrollment key using the enrollment tool.
- Open the command prompt as the administrator.
-
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.
-
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:
Enroll your device using the invitation code as follows:
-
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.
-
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.
-
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:
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:
-
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.
-
Log on to the machine that has the agent installed.
-
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:
Manage the enrolled agent
After enrolling an agent, use the management console to bind it to a desired configuration set for precise management.
- In the web console, go to Directory Objects and then add the agent machine to a configuration set. See Directory Objects.
- In the legacy console, go to Active Directory Objects > Machines and then add the agent machine to a configuration set. See Active Directory Objects.
- For information about adding non-domain-joined machines, see Manage non-domain-joined machines.
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