Optimize connectivity to workspaces with Direct Workload Connection

With Direct Workload Connection in Citrix Cloud, you can optimize internal traffic to the apps and desktops you make available to subscribers’ workspaces to make HDX sessions faster. Ordinarily, users on both internal and external networks have to connect to VDAs through an external gateway. While this is expected for external users, internal users experience slower connections to virtual resources. Direct Workload Connection allows internal users to bypass the gateway and connect to the VDAs directly, reducing latency for internal network traffic.

To set up Direct Workload Connection, you configure network locations that correspond to the VDAs in your environment with the Network Location Service. To configure these locations, you use a PowerShell module that Citrix provides. These network locations correspond to the public IP ranges of the networks where your internal users will be connecting from (for example, your office or branch locations). When subscribers launch Virtual Apps and Desktops sessions from their workspace, Citrix Cloud detects whether subscribers are internal or external to the company network based on the public IP address of the network from which they’re connecting. If a subscriber connects from the internal network, Citrix Cloud routes the connection directly to the VDA, bypassing Citrix Gateway. If a subscriber connects externally, Citrix Cloud routes the subscriber through Citrix Gateway as expected and then redirects the subscriber through the Citrix Cloud Connector to the VDA in the internal network.

Supported products

Direct Workload Connection is supported for Virtual Apps and Desktops service and Citrix SD-WAN only. Support for Citrix Virtual Apps and Desktops Standard for Azure (formerly Citrix Managed Desktops) is in Limited Release.

Important:

If your environment includes Citrix Virtual Apps and Desktops Standard for Azure alongside on-premises VDAs, configuring Direct Workload Connection causes Citrix Virtual Apps and Desktops Standard launches from the internal network to fail.

Launches of Secure Browser, Citrix Virtual Apps Essentials, and Citrix Virtual Desktops Essentials are always routed through the gateway. So, these launches do not realize any performance improvements from configuring Direct Workload Connection.

Requirements

Network requirements

  • If you have a corporate network and a guest Wifi network, these networks must have separate public IP addresses. If your corporate and guest networks share the same public IP address, users on the guest network can’t launch Virtual Apps and Desktops sessions.
  • You must use the public IP address ranges of the networks where your internal users will be connecting from. Internal users on these networks must have a direct connection to the VDAs. Otherwise, launches of virtual resources will fail as Workspace will attempt to route internal users directly to the VDA, which will not be possible.

TLS requirements

TLS 1.2 must be enabled in PowerShell when configuring your network locations. To force PowerShell to use TLS 1.2, use the following command before using the PowerShell module:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Workspace requirements

  • You have a workspace configured in Citrix Cloud.
  • The Virtual Apps and Desktops service is enabled in Workspace Configuration > Service Integrations.
  • You are using on-premises VDAs to deliver virtual resources to workspace subscribers.

Enable TLS for Workspace app for HTML5 connections

If your subscribers use Citrix Workspace app for HTML5 to launch apps and desktops, Citrix recommends you have TLS enabled on the VDAs in your internal network to ensure direct connections to those VDAs. If VDAs don’t have TLS enabled, app and desktop launches are routed through the Gateway when subscribers use Workspace app for HTML5. Launches using the desktop viewer are not affected. For more information about securing direct VDA connections with TLS, see CTX134123 in the Citrix Support Knowledge Center.

Configuration overview

To configure Direct Workload Connection, perform the following tasks:

  1. Determine the public IP address ranges of each branch location that your internal users will be connecting from.
  2. Download the PowerShell module.
  3. Create a secure API client in Citrix Cloud and make a note of the Client ID and secret.
  4. Import the PowerShell module and connect to the Network Location Service with your API client details.
  5. Create NLS sites for each of your branch locations with the public IP address ranges that you previously determined. Direct Workload Connection is automatically enabled for any launches that come from the internal network locations you’ve specified.
  6. Launch an app or desktop from a device on your internal network and verify that the connection goes directly to the VDA, bypassing the Gateway.

Powershell module and configuration

Download the PowerShell module

Before you set up your network locations, download the Citrix-provided PowerShell module (nls.psm1) from the Citrix Github repository. Using this module, you can set up as many network locations as needed for your VDAs.

  1. In a web browser, go to https://github.com/citrix/sample-scripts/blob/master/workspace/nls.psm1.
  2. Press ALT while clicking the Raw button. Github file view with Raw button highlighted
  3. Select a location on your computer and click Save.

Required configuration details

To set up your network locations, you need the following required information:

  • Citrix Cloud secure client customer ID, client ID, and client secret. To obtain these values, see Create a secure client in this article.
  • Public IP address ranges for the networks where your internal users will be connecting from. For more information about these public IP address ranges, see Requirements in this article.

Create a secure client

  1. Sign in to Citrix Cloud at https://citrix.cloud.com.
  2. From the Citrix Cloud menu, select Identity and Access Management and then select API Access.
  3. On the Secure Clients tab, note your customer ID. Secure Client console with Customer ID highlighted
  4. Enter a name for the client and then select Create Client.
  5. Copy the client ID and client secret. Secure Client ID and Secret dialog

Configure network locations

  1. Open a PowerShell command window and navigate to the same directory where you saved the PowerShell module.
  2. Import the module: Import-Module .\nls.psm1 -Force
  3. Set the required variables with your secure client information from Create a secure client:
    • $clientId = "YourSecureClientID"
    • $customer = "YourCustomerID"
    • $clientSecret = "YourSecureClientSecret"
  4. Connect to the Network Location Service with your secure client credentials:

    Connect-NLS -clientId $clientId -clientSecret $clientSecret -customer $customer
    
  5. Create a network location, replacing the parameter values with the values that correspond to the internal network where your internal users will be directly connecting from:

    New-NLSSite -name "YourSiteName" -tags @("YourTags") -ipv4Ranges @("PublicIpsOfYourNetworkSites") -longitude 12.3456 -latitude 12.3456
    

    To specify a single IP address instead of a range, add /32 to the end of the IP address. For example:

    New-NLSSite -name "YourSiteName" -tags @("YourTags") -ipv4Ranges @("PublicIpOfYourNetworkSite/32") -longitude 12.3456 -latitude 12.3456
    

    Important:

    When using the New-NLSSite command, include at least one value for each parameter. If you run this command without any command-line arguments, PowerShell prompts you to enter appropriate values for each parameter, one at a time. When entering values for the -tags parameter, press ENTER after entering each tag value. When you’re finished entering tags, press ENTER again to proceed to the next parameter.

    When the network location is created successfully, the command window displays the details of the network location.

  6. Repeat Step 5 for all your network locations where users will be connecting from.
  7. Run the command Get-NLSSite to return a list of all the sites you’ve configured with NLS and verify that their details are correct.

Verify internal launches are routed correctly

To verify internal launches are accessing VDAs directly, use one of the following methods:

  • View VDA connections through Virtual Apps and Desktops console.
  • Use ICA file logging to verify the correct addressing of the client connection.

Virtual Apps and Desktops service console

Select Manage > Monitor and then search for a user with an active session. In the Session Details section of the console, direct VDA connections display as UDP connections while gateway connections display as TCP connections.

ICA file logging

Enable ICA file logging on the client computer as described in To enable logging of the launch.ica file. After launching sessions, examine the Address and SSLProxyHost entries in the log file.

For direct VDA connections, the Address property contains the VDA’s IP address and port and the SSLProxyHost property contains the VDA’s FQDN and port.

For gateway connections, the Address property contains the STA ticket and the SSLProxyHost property contains the gateway’s FQDN and port.

Modify network locations

Use the steps in this section if you need to make changes to an existing network location.

  1. From a PowerShell command window, list all existing network locations: Get-NLSSite
  2. To modify the IP range for a specific network location, type

    (Get-NLSSite)[N] -ipv4Ranges @("1.2.3.4/32","4.3.2.1/32") | Set-NLSSite

    where [N] is the number corresponding to the location in the list (starting with zero) and "1.2.3.4/32","4.3.2.1/32" are the comma-separated IP ranges you want to use. For example, to modify the first listed location, you type the following command:

    (Get-NLSSite)[0] -ipv4Ranges @("98.0.0.1/32","141.43.0.0/24") | Set-NLSSite

Remove network locations

Use the steps in this section if you need to remove network locations that you no longer want to use.

  1. From a PowerShell command window, list all existing network locations: Get-NLSSite
  2. To remove all network locations, type Get-NLSSite | Remove-NLSSite
  3. To remove specific network locations, type (Get-NLSSite)[N] | Remove-NLSSite, where [N] is the number corresponding to the location in the list. For example, to remove the first listed location, you type (Get-NLSSite)[0] | Remove-NLSSite.

Example script

The example script includes all commands that you might need to add, modify, and remove the public IP address ranges for your branch locations. However, you don’t need to run all commands to perform any single function. For the script to run, always include the first 10 lines, from Import-Module through Connect-NLS. Afterward, you can include only the commands for the functions you want to perform.

Import-Module .\nls.psm1 -Force

$clientId = "XXXX" #Replace with your clientId
$clientSecret = "YYY"    #Replace with your clientSecret
$customer = "CCCCCC"  #Replace with your customerid

# Connect to Network Location Service
Connect-NLS -clientId $clientId -clientSecret $clientSecret -customer $customer

# Create a new Network Location Service Site (Replace with details corresponding to your branch locations)
New-NLSSite -name "New York" -tags @("EastCoast") -ipv4Ranges @("1.2.3.0/24") -longitude 40.7128 -latitude -74.0060

# Get the existing Network Location Service Sites (optional)
Get-NLSSite

# Update the IP Address ranges of your first Network Location Service Site (optional)
$s = (Get-NLSSite)[0]
$s.ipv4Ranges = @("1.2.3.4/32","4.3.2.1/32")
$s | Set-NLSSite

# Remove all Network Location Service Sites (optional)
Get-NLSSite | Remove-NLSSite

# Remove your third site (optional)
(Get-NLSSite)[2] | Remove-NLSSite

Troubleshooting

VDA launch failures

If VDA sessions are failing to launch, verify you are using public IP address ranges from the correct network. When configuring your network locations, you must use the public IP address ranges of the network where your internal users are connecting from. For more information, see Requirements in this article.

To verify a VDA’s public IP address, log on to each VDA machine, visit https://google.com, and enter “what is my ip” in the search bar.

Internal VDA launches still routed through the gateway

If VDA sessions launched internally are still being routed through the gateway as if they were external sessions, verify you are using the correct IP address ranges for the networks where your internal users are connecting from. These are generally the public IP address ranges that correspond to the networks where your VDAs reside, although your users might access the VDAs through a VPN. Do not use the local IP addresses of the VDAs. For more information, see Requirements in this article.

To verify a VDA’s public IP address, log on to each VDA machine, visit https://google.com, and enter “what is my ip” in the search bar.

Errors when running PowerShell cmdlets on non-Windows platforms

If you experience errors when running cmdlets with the correct parameters on PowerShell Core, verify that the operation was carried out successfully. For example, if you experience errors when running the New-NLSSite cmdlet, run Get-NLSSite to verify the site was created. Running these cmdlets on MacOS or Linux platforms using PowerShell Core could result in an error even though the operation was executed successfully.

If you experience this issue when running cmdlets with the correct parameters on a Windows platform using PowerShell, ensure you are using the latest version of the PowerShell module. With the latest version of the PowerShell module, this issue does not occur on Windows platforms.

Additional help and support

For troubleshooting help or questions, contact your Citrix sales representative or Citrix Support.