Citrix Cloud Connector™ Technical Details
The Citrix Cloud™ Connector is a component that establishes a connection between Citrix Cloud and your resource locations. This article describes deployment requirements and scenarios, Active Directory and FIPS support, and troubleshooting options.
System requirements
See System requirements.
Cloud Connector installed services
This section describes the services that are installed with the Cloud Connector and their system privileges.
During installation, the Citrix Cloud Connector executable installs and sets the necessary service configuration to the default settings required to function. If the default configuration is manually altered, the Cloud Connector might not perform as expected. In this case, the configuration resets to the default state when the next Cloud Connector update occurs, assuming the services that handle the update process can still function. At times, services are released in a ‘disabled’ state to support the addition or removal of services.
Citrix Cloud Agent System facilitates all elevated calls necessary for the other Cloud Connector services to function and does not communicate on the network directly. When a service on the Cloud Connector needs to perform an action requiring Local System permissions, it does so through a predefined set of operations that the Citrix Cloud Agent System can perform.
| Service Name | Description | Runs As |
|---|---|---|
| Citrix Cloud Agent System | Handles the system calls necessary for the on-premises agents. Includes installation, reboots, and registry access. Can only be called by Citrix Cloud Services Agent WatchDog. | Local System |
| Citrix Cloud Services Agent WatchDog | Monitors and upgrades the on-premises agents (evergreen). | Network Service |
| Citrix Cloud Services Agent Logger | Provides a support logging framework for the Citrix Cloud Connector services. | Network Service |
| Citrix Cloud Services AD Provider | Enables Citrix Cloud to facilitate management of resources associated with the Active Directory domain accounts in which it is installed. | Network Service |
| Citrix Cloud Services Agent Discovery | Enables Citrix Cloud to facilitate management of XenApp and XenDesktop® legacy on-premises Citrix products. | Network Service |
| Citrix Cloud Services Credential Provider | Handles storage and retrieval of encrypted data. | Network Service |
| Citrix Cloud Services WebRelay Provider | Enables HTTP Requests received from WebRelay Cloud service to be forwarded to On-Premises Web Servers. | Network Service |
| Citrix CDF Capture Service | Captures CDF traces from all configured products and components. | Network Service |
| Citrix Config Synchronizer Service | Copies brokering configuration locally for high availability mode. | Network Service |
| Citrix Connection Lease Exchange Service | Enables Connection Lease files to be exchanged between Workspace app and Cloud Connector for Service Continuity for Citrix® StoreFront Cloud | Network Service |
| Citrix High Availability Service | Provides continuity of service during outage of central site. | Network Service |
| Citrix ITSM Adapter Provider | Automates provisioning and management of virtual apps and desktops. | Network Service |
| Citrix NetScaler® CloudGateway | Provides Internet connectivity to on-premises desktops and applications without the need to open in-bound firewall rules or deploying components in the DMZ. | Network Service |
| Citrix Remote Broker Provider | Enables communication to a remote Broker Service from local VDAs and StoreFront™ servers. | Network Service |
| Citrix Remote HCL Server | Proxies communications between the Delivery Controller™ and the Hypervisors. | Network Service |
| Citrix WEM Cloud Authentication Service | Provides authentication service for Citrix WEM agents to connect to cloud infrastructure servers. | Network Service |
| Citrix WEM Cloud Messaging Service | Provides service for Citrix WEM cloud service to receive messages from cloud infrastructure servers. | Network Service |
| Citrix Secure Private Access™ | Zero Trust Network Access to all enterprise applications | Network Service |
| Citrix Cloud Services Message Broker | Handles messages between Citrix Cloud providers and Citrix Cloud services | Network Service |
| Citrix Secure Ticketing Authority Service | Provides secure ticketing authority for Citrix Cloud services | Network Service |
| Citrix Monitor Service | Enables Citrix Monitor cloud service to monitor and communicate with on-premises Citrix components | Network Service |
Deployment scenarios for Cloud Connectors in Active Directory
You can use both Cloud Connector and Connector Appliance to connect to Active Directory controllers. The type of connector to use depends on your deployment.
For more information about using Connector Appliances with Active Directory, see Deployment scenarios for Connector Appliances in Active Directory
Install Cloud Connector within your secure, internal network.
If you have a single domain in a single forest, installing Cloud Connectors in that domain is all you need to establish a resource location. If you have multiple domains in your environment, you must consider where to install the Cloud Connectors so your users can access the resources you make available.
If the trust between the domains is not Parent/Child, you might have to install Cloud Connectors for each separate domain or forest. This configuration might be required to handle resource enumeration when using security groups to assign resources or for registrations for VDAs from either domain.
Note:
The below resource locations form a blueprint that you might have to repeat in other physical locations depending on where your resources are hosted.
Single domain in a single forest with a single set of Cloud Connectors
In this scenario, a single domain contains all the resource and user objects (forest1.local). One set of Cloud Connectors is deployed within a single resource location and joined to the forest1.local domain.
- Trust relationship: None - single domain
- Domains listed in Identity and Access Management: forest1.local
- User logons to cloud stores: Supported for all users
- User logons to on-premises stores: Supported for all users
Note:
If you have a hypervisor instance in a separate domain, you can still deploy a single set of Cloud Connectors as long as the hypervisor instance and the Cloud Connectors are reachable through the same network. Citrix Cloud uses the hosting connection and an available network to establish communication with the hypervisor. So, even though the hypervisor resides in a different domain, you don’t need to deploy another set of Cloud Connectors in that domain to ensure that Citrix Cloud can communicate with the hypervisor.
Parent and child domains in a single forest with a single set of Cloud Connectors
In this scenario, a parent domain (forest1.local) and its child domain (user.forest1.local) reside within a single forest. The parent domain acts as the resource domain and the child domain is the user domain. One set of Cloud Connectors is deployed within a single resource location and joined to the forest1.local domain.
- Trust relationship: Parent/child domain trust
- Domains listed in Identity and Access Management: forest1.local, user.forest1.local
- User logons to cloud stores: Supported for all users
- User logons to on-premises stores: Supported for all users
Note:
You might need to restart the Cloud Connectors to ensure Citrix Cloud registers the child domain.
Users and resources in separate forests (with trust) with a single set of Cloud Connectors
In this scenario, one forest (forest1.local) contains your resource domain and one forest (forest2.local) contains your user domain. A one-way trust exists where the forest containing the resource domain trusts the forest containing the user domain. One set of Cloud Connectors is deployed in a single resource location and joined to the forest1.local domain.
- Trust relationship: One-way forest trust
- Domains listed in Identity and Access Management: forest1.local
- User logons to cloud stores: Supported for forest1.local users only
- User logons to on-premises stores: Supported for all users
Note:
The trust relationship between the two forests needs to permit the user in the user forest to be able to log on to machines in the resource forest.
Because Cloud Connectors can’t traverse forest-level trusts, the forest2.local domain is not displayed on the Identity and Access Management page in the Citrix Cloud console and can’t be used by any cloud-side functionality. This carries the following limitations:
- Resources can only be published to users and groups located in forest1.local in Citrix Cloud. However, if you’re using on-premises stores, forest2.local users may be nested into forest1.local security groups to mitigate this issue.
- Cloud stores can’t authenticate users from the forest2.local domain.
- The Monitor console in Citrix DaaS can’t enumerate the users from the forest2.local domain.
To work around these limitations, deploy the Cloud Connectors as described in Users and resources in separate forests (with trust) with a set of Cloud Connectors in each forest.
Users and resources in separate forests (with trust) with a set of Cloud Connectors in each forest
In this scenario, one forest (forest1.local) contains your resource domain and one forest (forest2.local) contains your user domain. A one-way trust exists where the forest containing the resource domain trusts the forest containing the user domain. One set of Cloud Connectors is deployed within the forest1.local domain and a second set is deployed within the forest2.local domain.
- Trust relationship: One-way forest trust
- Domains listed in Identity and Access Management: forest1.local, forest2.local
- User logons to cloud stores: Supported for all users
- User logons to on-premises store: Supported for all users
In this scenario Connector Appliances can been used in place of Cloud Connectors in user forests with no resources to reduce cost and management overheads, particularly if there are multiple user forests. For more information see Users and resources in separate forests (with trust) with a single set of Connector Appliances for all forests
View the health of the Cloud Connector
The Resource Locations page in Citrix Cloud displays the health status of all the Cloud Connectors in your resource locations. You can also view advanced health check data for each individual Cloud Connector. For more information, see Cloud Connector advanced health checks.
Windows event logs
The Cloud Connector generates certain Windows event logs that you can view through the Windows Event Viewer. If you want to enable your preferred monitoring software to look for these logs, you can download them as a ZIP archive. The ZIP download includes these logs in the following XML files:
- Citrix.CloudServices.Agent.Core.dll.xml (Connector Agent Provider)
- Citrix.CloudServices.AgentWatchDog.Core.dll.xml (Connector AgentWatchDog Provider)
Citrix.CloudSerivces.AgentWatchDog
During normal operations, the following events can occur:
| Event ID | Event | Description |
|---|---|---|
| 10000 | ConnectedToMessagingService | This event is raised when the Connector establishes its long-lived, outbound websocket connection with Citrix Cloud, allowing a two-way communication with Citrix Cloud. |
| 10001 | ConnectedToMessagingServiceWithWebProxy | Connected to messaging service through web proxy with address “{0}”. The websocket connection was set up using the configured proxy. |
| 10002 | UnableToConnectToMessagingService | Unable to connect to messaging service “{0}”. The Cloud Connector was unable to establish its websocket to Citrix Cloud. |
| 10003 | UnableToConnectToMessagingServiceWithWebProxy | Unable to connect to messaging service through web proxy with address “{0}”. The Cloud Connector was unable to establish its websocket to Citrix Cloud when using the configured proxy. |
| 10004 | ClockOutOfSyncError | There was a problem communicating with Citrix Cloud. Ensure that the clock on this machine has the correct time and timezone (UTC). You might need to restart the machine to resolve the issue. |
| 10005 | ConnectivityCheckHealthyToFailedStatus | The Cloud Connector’s hourly health check reported a failure after previously being healthy. |
| 10006 | ConnectivityCheckFailedStatus | The Cloud Connector’s hourly health check reported a failure, having also experienced a failure in the past. |
| 10007 | ConnectivityCheckFailedToHealthyStatus | The Cloud Connector’s hourly health check reported a healthy status after previously experiencing a failure. |
| 10008 | ConnectivityCheckHealthyStatus | The Cloud Connector’s hourly health check reported a healthy status after previously being healthy. |
Citrix.CloudServices.Agent
During normal operations, the following events can occur:
| 10100 | ConnectedToForest | Connected to the forest with a domain controller. |
| 10101 | UnableToConnectToForest | Unable to connect to the forest. Ensure that the host computer is joined to a domain and has network connectivity. |
| 10102 | UnableToConnectToForestWithDomainName | Unable to connect to the forest associated with the domain. |
| 10103 | ClockOutOfSyncError | There was a problem communicating with Citrix Cloud. Ensure that the clock on this machine has the correct time and timezone (UTC). You might need to restart the machine to resolve the issue. |
For more information on Broker or LHC event logs, see Event logs
Download Cloud Connector event messages.
Connector log files
By default, event logs are located in the C:\ProgramData\Citrix\WorkspaceCloud\Logs directory of the machine hosting the Cloud Connector.
Troubleshooting
The first step in diagnosing any issues with the Cloud Connector is to check the event messages and event logs. If you don’t see the Cloud Connector listed in your resource location or it is “not in contact,” the event logs provide some initial information.
Cloud Connector connectivity
If the Cloud Connector is “disconnected,” the Cloud Connector Advanced Connectivity Check Tool can help verify that the Cloud Connector can reach Citrix Cloud and its related services.
For more information, see Cloud Connector Advanced Connectivity Check Tool.
Installation
If the Cloud Connector is in an “error” state, there might be a problem hosting the Cloud Connector. Install the Cloud Connector on a new machine. If the issue persists, contact Citrix Support. To troubleshoot common issues with installing or using the Cloud Connector, see CTX221535.