Citrix Gateway Connector

Citrix Gateway Connector is a Citrix component which serves as a channel of communication between Cloud services (Citrix Gateway service, ADM, and so on) and on-premises components such as Web servers. It is a virtual appliance compatible with Citrix Hypervisor, VMware ESXi, and Microsoft Hyper-V with a small form factor. Citrix Gateway Connector facilitates the remote access to the Enterprise web apps.

How it works

Citrix Gateway Connector authenticates and encrypts all communication between Citrix Cloud and your resource locations. The communication between the Citrix Gateway Connector and Citrix Cloud is outbound. All connections are established from the Citrix Gateway Connector to the cloud using the standard HTTPS port (443) and the TCP protocol. No incoming connections are accepted. TCP port 443, with the following FQDNs are permitted outbound:

  • *.nssvc.net
  • *.netscalermgmt.net
  • *.citrixworkspacesapi.net
  • *.citrixnetworkapi.net
  • *.citrix.com
  • *.servicebus.windows.net
  • *.adm.cloud.com

Important: If there are SSL intercepting devices in the on-premises data center where the Citrix Gateway Connector must be deployed, the connector registration does not succeed if SSL interception is enabled for these FQDNs. The SSL interception must be disabled for these FQDNs for successful connector registration.

Capabilities of Citrix Gateway Connector

The following are some of the capabilities of Citrix Gateway Connector.

  • Acts as a reverse proxy – Citrix Gateway Connector acts as a reverse proxy to Enterprise Web apps. The required web application ports must be opened from the Gateway Connector to the apps.
  • Enables single sign-on: The Citrix Gateway Connector provides the following single sign-on capabilities with the Citrix Gateway service.
    • Basic SSO
    • Kerberos
    • Form-based
    • SAML
    • No SSO
  • Enables application of optional security policies through Access Control – The Citrix Gateway Connector provides enhanced security capabilities through the Citrix Access Control service. For example,
    • Restrict clipboard access
    • Restrict printing
    • Restrict navigation
    • Restrict downloads
    • Display watermark
    • App protection policies
    • Enforce policy on mobile device

For details, see Support for Enterprise web apps and Support for Software as a Service apps.

System requirements

Citrix Gateway Connector is a virtual appliance. The minimum system requirements for the Citrix Gateway Connector are as follows:

  • Number of vCPUs must be exactly 2.
  • 4 GB RAM minimum.

    Important: The new minimum system requirement for RAM has changed. If you have an existing Citrix Gateway Connector, upgrade the system memory of your virtual machines to match the new requirement of 4 GB RAM.

For details, see Upgrade the system memory of Citrix Gateway Connector virtual machines.

  • 1 Network Adapter (virtual NIC). You can add an extra virtual NIC upon requirement.
  • Firewall:

    • UDP port 53 to DNS server
    • TCP and UDP port 389 to Active Directory Domain Controllers (optional * - * is described at the end of the page)
    • TCP port 636 to Active Directory Domain Controllers (optional *)
    • TCP port 3268 to Active Directory Domain Controllers (optional *)
    • TCP port 3269 to Active Directory Domain Controllers (optional *)
    • TCP port 443, with the following FQDNs are permitted outbound:
      • *.nssvc.net
      • *.netscalermgmt.net
      • *.citrixworkspacesapi.net
      • *.citrixnetworkapi.net
      • *.citrix.com
      • *.servicebus.windows.net
      • *.adm.cloud.com
    • TCP ports (**) to Web servers accessed using Citrix Gateway Connector
    • Open port 8443 inbound for web-based management

      * - Required to perform domain-based single sign-on to Web applications **- Ports determined by the customers’ environment – ports 80 and 443 are typical

Recommended: Network with DHCP enabled to simplify the initial configuration.

Ways to install Citrix Gateway Connector

Citrix Gateway Connector can be installed in one of the following ways.

In both cases, you must create a new virtual machine as described in the following section.

Create a new virtual machine

  1. Sign in to Citrix Cloud.
  2. From the menu in the top-left of the screen, select Resource Locations.
    • If you have no existing resource locations, click Download on the Resource Locations page. When prompted, save the cwcconnector.exe file. For details, see Cloud Connector Installation.
    • If you have a resource location but no Cloud Connectors installed in it, click the Cloud Connectors bar and then click Download. When prompted, save the cwcconnector.exe file.
  3. Click Gateway Connectors.

    Connector new

  4. Select the hypervisor and click Download Image. Import the locally downloaded image to your hypervisor and create a new virtual machine (Citrix Gateway Connector).

    Download image

  5. Click Get Activation Code.

    Get activation code

  6. The activation code is generated as follows.

    Activation code

  7. Once the installation is complete, Click Detect.

    Detect connector

Install Citrix Gateway Connector by using the Citrix Cloud user interface

The following are the steps to set up a resource location and install Citrix Gateway Connector using the Citrix Cloud user interface:

  1. On top left of the Citrix Cloud screen, click the hamburger icon and select Resource Locations. Click the plus icon next to Resource Locations.

    Resource location

  2. Provide a name for the resource location and click Save.

    Location name

  3. Double-click the plus icon next to Citrix Gateway Connectors under the newly created resource location.

    Connector new

  4. Complete the steps as described in Create a new virtual machine.

Install Citrix Gateway Connector while adding an Enterprise Web app

While adding an Enterprise Web app using the Citrix Gateway service user interface, you can set up a new resource location and download connectors. For details on adding an Enterprise Web app, see Support for Enterprise web apps.

To set up a resource location and download connectors, perform the following steps:

  1. In the Web app connectivity section, select the Create New radio button. Provide a name for the resource location and click Save.

    New resource location

  2. Click Install Citrix Gateway Connector.

    Install connector

  3. Complete the steps as described in Create a new virtual machine.

Access the Citrix Gateway Connector user interface by using the URL

You can access the Citrix Gateway Connector user interface by using the URL that is displayed in one of the messages on the newly installed Citrix Gateway Connector VM. You can also log on to the Citrix Gateway Connector CLI as an administrator and run the show ipcommand for viewing the IP address assigned to the Citrix Gateway Connector through DHCP. Then you can open https://<IP address>:8443 on your browser to access the Citrix Gateway Connector admin user interface.

Log on and set up the Citrix Gateway Connector

After the Citrix Gateway Connector installation is complete, look for the following message on the newly installed VM (Citrix Gateway Connector).

After connector installation

Type the mentioned URL in a browser to access the Citrix Gateway Connector user interface. You can also log on to the Citrix Gateway Connector CLI as an administrator and run the show ipcommand. The command displays the IP address assigned to the Citrix Gateway Connector through DHCP. Then open <https://IP address:8443> on your browser to access the Citrix Gateway Connector admin user interface.

  1. The user name and password for the following screen is administrator for the first time user.

    logon credentials

  2. Change the password by providing a password of your choice in the Set administrator password section and click Continue.

  3. Enter the following configuration details in the System settings section and click Continue.
    • Connector IP Address – IP address of Gateway Connector.
    • Subnet Mask – Subnet mask of the Gateway Connector IP address.
    • Default Gateway – IP address of the default gateway.
    • DNS Server – IP address of the DNS server. Starting from Citrix Gateway Connector release 13.0, there is a change in the DNS server configuration. For details, see the section Changes to the DNS server settings.
    • Proxy IP – Your internal proxy server IP address.
    • Proxy Port – Port of the proxy server.

    System settings

    Changes to the DNS server settings:

    Starting from Citrix Gateway Connector 13.0.400.xxx, the DNS configuration for both UDP and TCP protocol on the connector appliance is updated automatically when it is set in the System Settings section. However if you upgrade your connector from earlier versions, you have to manually delete the DNS setting and read it again. To do so, perform the following.

    1. Navigate to the Citrix Gateway Connector dashboard > Edit Settings.
    2. Click the delete icon next to the first DNS Server field and click Continue.
    3. Navigate to the Edit Settings page, read the same DNS server, and click Continue.
    4. Repeat the steps for the second DNS server. Note:
      • You do not have to perform these steps for new instances of the 13.0 Citrix Gateway Connector.
      • You need not perform the earlier mentioned steps immediately after the upgrade. There is no loss of functionality if this is not done. These steps must be performed for enterprise customers who require DNS over TCP Functionality to make Enterprise Web apps to function correctly.
  4. In the Single sign on section, check Enable Kerberos Single Sign On for capabilities beyond the basic authentication. You can validate the Kerberos details by two ways, realm-only mode and full Kerberos constrained delegation.

    You can use the Test option for debugging purposes. For example, if the Kerberos details are not correctly set and if an app is added, SSO to the app fails.

    1. For realm-only mode, select Enable Kerberos Single Sign On, enter the following details, and then click Test Kerberos.
      • Active Directory Domain – Active Directory domain for the users to be granted access.
      • Service FQDN - FQDN of the service (the service FQDN that the user must access through configuring Web apps).
      • Username – User name of the logged on user.
      • Password – Password of the logged on user.

      No kerberos validation

    2. For full Kerberos constrained delegation, select Kerberos Constrained Delegation, enter the following details, and then click Test Kerberos.
      • Active Directory Domain – Active Directory domain for the users to be granted access.
      • Service Account Username – Service account user name used for delegation.
      • Service Account Password – Password for the service account user name used for delegation.
      • Service FQDN - FQDN of the service (the service FQDN that the user must access through configuring Web apps).
      • Username - User name of the logged on user.

      Kerberos validation

    In both cases, based on whether the validation is successful or not, the respective message appear. The following figure displays a sample validation error message. Kerberos validation failure message

  5. Enter the activation code to register the connector with Citrix Cloud. Click Save and Finish.

  6. Click Connectivity Test. (This step is optional)

    Test connectivity

    The Connectivity Test option enables you to confirm that there are no errors in the Gateway Connector configuration and the Gateway Connector is able to connect to the URLs. This step is optional. You can skip this step and proceed with activating the Gateway Connector.

    • When you click Connectivity Test, a set of URLs is run in the back end to ensure that the connector is able to connect to those URLs. If all the URLs are successfully run, the connectivity test success message appears. The following FQDNs are run when you click Connectivity Test.

      • agent.netscalermgmt.net
      • agent.netscalermgmt.net
      • trust.citrixnetworkapi.net
      • download.citrixnetworkapi.net
      • web-reg.c.nssvc.net
      • agent.adm.cloud.com
      • anse.agent.adm.cloud.com
      • railay.agent.adm.cloud.com
      • agent.netscalermgmt.net
      • evergreen.citrixnetworkapi.net
      • agenthub.citrixworkspacesapi.net
      • callhome.citrix.com
    • If any of these URLs do not respond, an error message appears and the corresponding URL is displayed. The error messages are classified under three categories.

      • DNS error
      • Server error
      • SSL exception

    The following images display sample error messages.

    Test connectivity message1

    Test connectivity message2

  7. Finally enter the activation code to register the connector with Citrix Cloud and click Save and Finish.

    For details on how to get the activation code, see Create a new virtual machine.

Save and Finish

Troubleshoot Citrix Gateway Connector registration issues

You can use the Trace feature and the Download Logs feature to troubleshoot Citrix Gateway Connector registration issues

Trace feature

While registering Citrix Gateway Connector, you might come across issues because of which the registration might not be successful. To troubleshoot these issues, you can use the Trace Info link that appears the first time you register the connector. You can download the trace files and share it with the administrators for troubleshooting. Trace files are in an encrypted format. The Trace Info link is also available in the Gateway Connector dashboard even after the registration. You can also capture and download trace files from the dashboard for debugging issues.

How to download trace files

  1. Click Trace Info.

    Trace info link

  2. In the Trace dialog box, select the duration that you want to run the trace and then click Start. The Trace dialog box displays the progress.

    Trace dialog

  3. You can stop the trace that is in progress before it is complete. You can then download the trace files by clicking the Download button. You can also start a new trace from the dialog box.

    Download trace

Note: For debugging registration failures, first start a trace with a given pre-set interval, enter the activation code, and submit for registration.

  • If the registration fails, you can click the Trace info link to bring up the Trace dialog again, stop the trace, and then download the trace files.
  • If the registration succeeds, then the Dashboard console comes up and the trace stops automatically in the background.

IMPORTANT:

  • Closing the Trace window before the trace is complete does not stop the trace. The trace keeps running in the background until it is completed.
  • If you refresh or close the browser when the trace is in progress, you must manually stop the trace by clicking the Trace Info link to prevent the trace from running indefinitely. In this scenario, the Trace Info link displays only the Stop button and does not display the Download button. Therefore, you cannot download the captured trace. To capture the trace again, click Start new trace.

Download logs

Download logs option is available in Gateway Connector from version 401.251. If you are on an earlier version of the connector and you upgrade the connector to version 401.251, you still cannot download the logs even though the Download Logs link is available.

How to download logs

  1. Click Download Logs.

    The Download Logs link is available even during the first time use to help setup the connector.

    A log file is generated. Generation of the log file takes some time. Once the log file if generated, a message with the link to the download file appears.

  2. Click Download. A .tgz file is downloaded.

All files in the download folder are in an encrypted format. Contact the Citrix Cloud support team for help.

Delete a Citrix Gateway Connector

Perform the following to delete a Citrix Gateway Connector.

  1. Sign in to Citrix Cloud.

  2. Select Resource Locations from the menu in the top-left of the screen.

  3. In the Resource Locations page, click Gateway Connectors for a specific resource location.

    Resource location - select connector

  4. Select the Gateway Connector that you want to delete and click the ellipsis menu.

    Delete connector

  5. Select Remove Connector.

    A confirmation dialog box appears.

  6. Click OK.

    Note: It might take a couple of minutes for the gateway Connector to be removed from the Resource Locations page. Also, it might take sometime for the Gateway Connector to unregister from the gateway controller.

Upgrade the system memory of Citrix Gateway Connector virtual machines

Gateway connector RAM size is 2 GB, by default. Therefore, it is recommended that you increase the RAM size to 4 GB for optimal performance. This recommendation is applicable for new or existing connector installations.

If you have two connectors per resource location for high availability, perform the following to upgrade the connector virtual machines.

  1. From the hypervisor, shut down one of the connector virtual machines.
  2. Edit the hardware configuration or settings of the virtual machine depending on the type of hypervisor.
  3. Navigate to Memory tab.
  4. If the RAM size is 2,048 MB, increase it to 4,096 MB and save the configuration.
  5. Power up the virtual machine.
  6. Repeat these steps on the second connector virtual machine as well.

IMPORTANT: Ensure that you upgrade one connector at a time to avoid any outages.

Continuous availability of the Citrix Gateway Connector

As long as you ensure continuous availability of the Citrix Gateway Connector in each resource location, you can manage the machines where they are installed one at a time to avoid outage periods.

For continuous availability, install multiple Citrix Gateway Connectors in each of your resource locations. Citrix recommends at least two (2) Citrix Gateway Connectors in each resource location. If one Citrix Gateway Connector is unavailable for any time, the other Citrix Gateway Connectors can maintain the connection. As long as there is one Citrix Gateway Connector available, there is no loss in communication with Citrix Cloud. Citrix Gateway Connectors can be restricted to upgrade during a specified maintenance window every 24 hour, controlled per Resource Location.

Load management

Manage load by installing multiple Citrix Gateway Connectors in each resource location. Since each Citrix Gateway Connector is stateless, the load can be distributed across all available Citrix Gateway Connectors. There is no need to configure this load balancing function. It is automated.