Citrix Cloud

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

The machines hosting the Cloud Connector must meet the following requirements. At least two Cloud Connectors in each resource location are required to ensure high availability. As a best practice, Citrix recommends using the N+1 redundancy model when deploying Cloud Connectors to maintain a highly available connection with Citrix Cloud.

Hardware requirements

Each Cloud Connector requires of minimum of:

  • 2 vCPU
  • 4 GB memory
  • 20 GB disk space

More vCPU memory enables a Cloud Connector to scale up for larger sites. For recommended configurations, see Scale and size considerations for Cloud Connectors.

Operating systems

The following operating systems are supported:

  • Windows Server 2022
  • Windows Server 2019
  • Windows Server 2016

The Cloud Connector is not supported for use with Windows Server Core.

.NET requirements

Microsoft .NET Framework 4.7.2 or later is required. Download the latest version from the Microsoft website.

Note:

Do not use Microsoft .NET Core with the Cloud Connector. If you use .NET Core instead of .NET Framework, installing the Cloud Connector might fail. Use only .NET Framework with the Cloud Connector.

Server requirements

If you’re using Cloud Connectors with Citrix DaaS (formerly Citrix Virtual Apps and Desktops service), refer to Scale and size considerations for Cloud Connectors for machine configuration guidance.

The following requirements apply to all machines where the Cloud Connector is installed:

  • Use dedicated machines for hosting the Cloud Connector. Do not install any other components on these machines.
  • The machines are not configured as Active Directory domain controllers. Installing the Cloud Connector on a domain controller is not supported.
  • Server clock is set to the correct UTC time.
  • If you are using the graphical installer, you must have a browser installed and the default system browser set.
  • Citrix strongly recommends enabling Windows Update on all machines hosting the Cloud Connector. When configuring Windows Update, configure Windows to automatically download and install updates outside of business hours, but do not allow automatic restarts for at least 4 hours. The Citrix Cloud platform handles machine restarts when it identifies that an update is waiting for a restart, allowing a restart for only one Cloud Connector at a time. You can configure a fallback restart using Group Policy or a system management tool for when the machine must be restarted after an update. For more information, see https://docs.microsoft.com/en-us/windows/deployment/update/waas-restart.

Certificate validation requirements

Cloud Connector binaries and endpoints that the Cloud Connector contacts are protected by X.509 certificates issued by widely respected enterprise certificate authorities (CAs). Certificate verification in Public Key Infrastructure (PKI) includes the Certificate Revocation List (CRL). When a client receives a certificate, the client checks whether it trusts the CA that issued the certificates and whether the certificate is on a CRL. If the certificate is on a CRL, the certificate is revoked and cannot be trusted, even though it appears valid.

The CRL servers use HTTP on port 80 instead of HTTPS on port 443. Cloud Connector components, themselves, do not communicate over external port 80. The need for external port 80 is a byproduct of the certificate verification process that the operating system performs.

The X.509 certificates are verified during the Cloud Connector installation. So, all Cloud Connector machines must be configured to trust these certificates to ensure that the Cloud Connector software can be installed successfully.

Citrix Cloud endpoints are protected by certificates issued by DigiCert or by one of the Root Certificate Authorities used by Azure. For more information on the Root CAs used by Azure, see https://docs.microsoft.com/en-us/azure/security/fundamentals/tls-certificate-changes.

To validate the certificates, each Cloud Connector machine must meet the following requirements:

  • HTTP port 80 is open to the following addresses. This port is used during Cloud Connector installation and during the periodic CRL checks. For more information about how to test for CRL and OCSP connectivity, see https://www.digicert.com/kb/util/utility-test-ocsp-and-crl-access-from-a-server.htm on the DigiCert website.
    • http://cacerts.digicert.com/
    • http://dl.cacerts.digicert.com/
    • http://crl3.digicert.com
    • http://crl4.digicert.com
    • http://ocsp.digicert.com
    • http://www.d-trust.net
    • http://root-c3-ca2-2009.ocsp.d-trust.net
    • http://crl.microsoft.com
    • http://oneocsp.microsoft.com
    • http://ocsp.msocsp.com
  • Communication with the following addresses is enabled:
    • https://*.digicert.com
  • The following root certificates are installed:
    • https://cacerts.digicert.com/DigiCertAssuredIDRootCA.crt
    • https://cacerts.digicert.com/DigiCertGlobalRootG2.crt
    • https://cacerts.digicert.com/DigiCertGlobalRootCA.crt
    • https://cacerts.digicert.com/DigiCertTrustedRootG4.crt
    • https://cacerts.digicert.com/BaltimoreCyberTrustRoot.crt
    • https://www.d-trust.net/cgi-bin/D-TRUST_Root_Class_3_CA_2_2009.crt
    • https://www.microsoft.com/pkiops/certs/Microsoft%20RSA%20Root%20Certificate%20Authority%202017.crt
    • https://www.microsoft.com/pkiops/certs/Microsoft%20EV%20ECC%20Root%20Certificate%20Authority%202017.crt
    • https://www.microsoft.com/pkiops/certs/Microsoft%20ECC%20Root%20Certificate%20Authority%202017.crt
  • The following intermediate certificates are installed:
    • https://cacerts.digicert.com/DigiCertTrustedG4CodeSigningRSA4096SHA3842021CA1.crt
    • https://cacerts.digicert.com/DigiCertSHA2AssuredIDCodeSigningCA.crt

If any certificate is missing, the Cloud Connector installer will download it from http://cacerts.digicert.com.

For complete instructions for downloading and installing the certificates, see CTX223828.

Citrix DaaS

Utilizing the Cloud Connector for connectivity to DaaS resources necessitates the installation of additional certificates and granting access to extended PKI infrastructure. Each Cloud Connector machine is required to fulfill the following requirements:

  • HTTP port 80 is open to the following addresses:
    • crl.*.amazontrust.com
    • ocsp.*.amazontrust.com
    • *.ss2.us
  • Communication with the following addresses is enabled
    • https://*.amazontrust.com
    • https://*.ss2.us
  • The following root certificates are installed:
    • https://www.amazontrust.com/repository/AmazonRootCA1.cer
    • https://www.amazontrust.com/repository/AmazonRootCA2.cer
    • https://www.amazontrust.com/repository/AmazonRootCA3.cer
    • https://www.amazontrust.com/repository/AmazonRootCA4.cer
    • https://www.amazontrust.com/repository/SFSRootCAG2.cer
  • The following intermediate certificates are installed:
    • https://www.amazontrust.com/repository/G2-RootCA4.orig.cer
    • https://www.amazontrust.com/repository/R3-ServerCA3A.cer
    • https://www.amazontrust.com/repository/SFC2CA-SFSRootCAG2.cer
    • https://www.amazontrust.com/repository/SFC2CA-SFSRootCAG2.v2.cer
    • https://www.amazontrust.com/repository/G2-RootCA1.orig.cer
    • https://www.amazontrust.com/repository/R1-ServerCA1A.cer
    • https://www.amazontrust.com/repository/G2-RootCA3.cer
    • https://www.amazontrust.com/repository/R3-ServerCA3A.orig.cer
    • https://www.amazontrust.com/repository/G2-RootCA2.orig.cer
    • https://www.amazontrust.com/repository/G2-RootCA4.cer
    • https://www.amazontrust.com/repository/R2-ServerCA2A.cer
    • https://www.amazontrust.com/repository/R4-ServerCA4A.cer
    • https://www.amazontrust.com/repository/R1-ServerCA1A.orig.cer
    • https://www.amazontrust.com/repository/G2-RootCA1.cer
    • https://www.amazontrust.com/repository/G2-RootCA2.cer
    • https://www.amazontrust.com/repository/G2-RootCA3.orig.cer
    • https://www.amazontrust.com/repository/R4-ServerCA4A.orig.cer
    • https://www.amazontrust.com/repository/G2-ServerCA0A.cer
    • https://www.amazontrust.com/repository/G2-ServerCA0A.orig.cer
    • https://www.amazontrust.com/repository/SFSRootCA-SFSRootCAG2.cer

If any certificate is missing, the Cloud Connector will download it from https://www.amazontrust.com

For complete instructions for downloading and installing the certificates, see CTX223828.

Active Directory requirements

  • Joined to an Active Directory domain that contains the resources and users that you use to create offerings for your users. For multi-domain environments, see Deployment scenarios for Cloud Connectors in Active Directory in this article.
  • Each Active Directory forest you plan to use with Citrix Cloud must always be reachable by two Cloud Connectors.
  • The Cloud Connector must be able to reach domain controllers in both the forest root domain and in the domains that you intend to use with Citrix Cloud. For more information, see the following Microsoft support articles:
  • Use universal security groups instead of global security groups. This configuration ensures that user group membership can be obtained from any domain controller in the forest.

Network requirements

Supported Active Directory functional levels

The Citrix Cloud Connector supports the following forest and domain functional levels in Active Directory.

Forest Functional Level Domain Functional Level Supported Domain Controllers
Windows Server 2008 R2 Windows Server 2008 R2 Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server 2016
Windows Server 2008 R2 Windows Server 2012 Windows Server 2012, Windows Server 2012 R2, Windows Server 2016
Windows Server 2008 R2 Windows Server 2012 R2 Windows Server 2012 R2, Windows Server 2016
Windows Server 2008 R2 Windows Server 2016 Windows Server 2016
Windows Server 2012 Windows Server 2012 Windows Server 2012, Windows Server 2012 R2, Windows Server 2016
Windows Server 2012 Windows Server 2012 R2 Windows Server 2012 R2, Windows Server 2016
Windows Server 2012 Windows Server 2016 Windows Server 2016
Windows Server 2012 R2 Windows Server 2012 R2 Windows Server 2012 R2, Windows Server 2016
Windows Server 2012 R2 Windows Server 2016 Windows Server 2016
Windows Server 2016 Windows Server 2016 Windows Server 2016, Windows Server 2019, Windows Server 2022

Federal Information Processing Standard (FIPS) support

The Cloud Connector currently supports the FIPS-validated cryptographic algorithms that are used on FIPS-enabled machines. Only the latest version of the Cloud Connector software available in Citrix Cloud includes this support. If you have existing Cloud Connector machines in your environment (installed before November 2018) and you want to enable FIPS mode on these machines, perform the following actions:

  1. Uninstall the Cloud Connector software on each machine in your resource location.
  2. Enable FIPS mode on each machine.
  3. Install the latest version of the Cloud Connector on each FIPS-enabled machine.

Important:

  • Do not attempt to upgrade existing Cloud Connector installations to the latest version. Always uninstall the old Cloud Connector first and then install the newer one.
  • Do not enable FIPS mode on a machine hosting an older Cloud Connector version. Cloud Connectors older than Version 5.102 do not support FIPS mode. Enabling FIPS mode on a machine with an older Cloud Connector installed prevents Citrix Cloud from performing regular maintenance updates for the Cloud Connector.

For instructions to download the latest version of the Cloud Connector, see Where to obtain the Cloud Connector.

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.

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 Workspace 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

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 Citrix Workspace: Supported for all users
  • User logons to an on-premises StoreFront: 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 Citrix Workspace: Supported for all users
  • User logons to an on-premises StoreFront: 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 Citrix Workspace: Supported for forest1.local users only
  • User logons to an on-premises StoreFront: 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 StoreFront stores, forest2.local users may be nested into forest1.local security groups to mitigate this issue.
  • Citrix Workspace 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 Citrix Workspace: Supported for all users
  • User logons to an on-premises StoreFront: 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.

Event messages

The Cloud Connector generates certain event messages that you can view through the Windows Event Viewer. If you want to enable your preferred monitoring software to look for these messages, you can download them as a ZIP archive. The ZIP download includes these messages in the following XML files:

  • Citrix.CloudServices.Agent.Core.dll.xml (Connector Agent Provider)
  • Citrix.CloudServices.AgentWatchDog.Core.dll.xml (Connector AgentWatchDog Provider)

Download Cloud Connector event messages.

Event logs

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 Connectivity Check Utility can help you verify that the Cloud Connector can reach Citrix Cloud and its related services.

The Cloud Connector Connectivity Check Utility runs on the machine hosting the Cloud Connector. If you use a proxy server in your environment, the utility can help you verify connectivity through your proxy server by tunneling all connectivity checks. If needed, the utility can also add any missing Citrix trusted sites to the Trusted Sites zone in Internet Explorer.

For more information about downloading and using this utility, see CTX260337 in the Citrix Support Knowledge Center.

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.

Deploying Cloud Connectors as Secure Ticket Authority servers

If using multiple Cloud Connectors as Secure Ticket Authority (STA) servers with Citrix ADC, the ID for each STA server might be displayed as CWSSTA in both the ADC management console and the ICA file for application and desktop launches. As a result, STA tickets are not routed correctly and launching sessions fails. This issue can occur if the Cloud Connectors are deployed under separate Citrix Cloud accounts with different customer IDs. In this scenario, a ticketing mismatch occurs between the separate accounts that prevents sessions from being created.

To resolve this issue, ensure the Cloud Connectors that you bind as STA servers belong to the same Citrix Cloud account with the same customer ID. If you need to support multiple customer accounts from the same ADC deployment, create a Gateway virtual server for each account. For more information, refer to the following articles:

Citrix Cloud Connector Technical Details