I work for Receiver for HTML5 and Receiver for Chrome development team. We are starting the blog series explaining the technical internals of Receivers.

This post is the first one in a series focused on how Receiver for HTML5 and Receiver for Chrome connect to the XenApp and XenDesktop backend in various deployments.

Traditionally, native Citrix Receivers (e.g. Windows, Linux, Mac) connect to Storefront/Web Interface/NetScaler Gateway to enumerate resources (App and Desktop), get the .ica file for a particular app/desktop and connect to XA/XD/Gateway for actual HDX connection. Users can also go to Receiver for Web (RfWeb)/Web Interface/NetScaler Gateway URL in a browser and launch native Receiver using browser plugins or protocol handler based communication in SF 3.0

Direct Connections to XenApp and XenDesktop:

Let’s take a look at how direct connections are made to XenApp 6.5 and XenApp/XenDesktop 7.6 environments without going through NetScaler Gateway. (Let’s keep Receiver for Chrome aside for now)

Below diagram shows how native Citrix Receivers like Receiver for Windows connect to XenApp and XenDesktop.

Receiver for Windows and Receiver for Chrome connecting directly to XA/XD.

Receiver for HTML5, on the other hand, uses Receiver for Web for enumeration of apps/desktops. To start an HDX session, Receiver for Web opens Receiver for HTML5 in a new tab and passes .ica file contents. This communication doesn’t involve any plugins or add-ons.

Receiver for HTML5 is a javascript-based engine. HTML, js, css, images and other resources are downloaded first time when users access HTML5 HDX session. Browsers typically cache resources, so that files do not get downloaded multiple times. This means we avoid installation, but also have the benefit of Receiver available for subsequent access. Receiver uses HTML5 APIs provided by the browsers for all the features. What this means for connection is that it can’t use an OS-provided socket API like other native Receivers, meaning it can’t connect directly to 1494 (ICA) or 2598 (CGP) ports.

HTML5 API provided by browsers instead provides a higher level WebSocket API, which abstracts sockets across various browsers (Chrome, Firefox, Safari, IE etc.) and platforms (such as Windows, Mac, Linux, ChromeOS etc) through which Receiver for HTML5 connects to XenApp and XenDesktop. Of course, the downside here is that the backend needs to understand the WebSocket protocol, extract data from it and pass it on to the next layer.

Websocket listener/parser is implemented as part of XTE service in XenApp 6.5 (which also implements CGP and SSL relay). Note that even though WebSockets, CGP and SSL relay are implemented by XTE service, it doesn’t handle CGP/SSL connections over websockets.

Note: Websocket listener support was added in XenApp 6.5 Feature Pack 1. You may want to use latest HRP to get all the latest security updates and other features.

In the case of XenDesktop 7.6, websocket listener, as well as ICA, CGP, SSL/TLS listeners are all handled by a single super transport driver (TdICA). This supports various combinations of protocols. This post explains mainly about XenApp 6.5 and XenApp/XenDesktop 7.6.

Note: In XenDesktop 7.0-7.5 had different transport drivers for ICA, CGP and HTML5 connections. SSL/TLS support was added only in XenApp/XenDesktop 7.6

Receiver for HTML5 connecting directly to XA/XD

WebSocket listeners, which are required for connection from Receiver for HTML5, are disabled by default in XenApp and XenDesktop VDA.

Important step: You need to enable websocket policies to make XenApp and XenDesktop listen over WebSockets. (They are machine policies so would need a reboot or special configuration in case of PVS/MCS).

Security note: Important security impact with Websocket connections is that, when Receiver for HTML5 is hosted on a https site (default and recommended), non SSL/TLS websocket connections are prohibited by browsers.

Internet Explorer never allowed non SSL/TLS websocket connections from HTTPS websites. Chrome used to allow it behind a flag, but after the Chrome 44 update,that will no longer be the case. Firefox allows it behind a flag, but it is not recommended, as it is hard to push config to multiple desktops. This means, going forward, that only secure (SSL/TLS) websocket connections can be made from Receiver for HTML5.

XenApp/XenDesktop 7.6 supports SSL/TLS websocket direct connections. (As noted earlier even though XA 6.5, XTE service supports SSL relay but it doesn’t support SSL/TLS websocket connections)

Deploying SSL/TLS for each VDA can be simplified using automation/scripting. Wildcards certificates can also help in this context. However enabling SSL/TLS means all Receivers do SSL/TLS when connecting to XenApp and XenDesktop.

What would probably help is having a proxy that can parse out all websocket traffic and convert to ICA/CGP traffic without any need of changes to XA/XD. Netscaler Gateway does exactly this and when a gateway is involved there is no technical restriction on XenApp/XenDesktop version for connections from Receiver for HTML5. Hence this is the recommended secure path for all browsers when using Receiver for HTML5. You can also do end to end SSL/TLS with NetScaler Gateway and XenApp XenDesktop 7.6 for highest security. NetScaler Gateway also doesn’t need any special configuration for listening over websockets. You would need to use 10.1 or higher but 11.0 is recommended to take advantage of all the new features and fixes.

Connections via NetScaler Gateway:

Now that we have learnt how direct connection works, let’s look at how connections via NetScaler gateway are made from Receivers.

When a gateway is involved, the connections are similar in all Receivers. Here, Gateway acts as WebSocket proxy and in-turn opens ICA/CGP/SSL native socket connections to backend XenApp and XenDesktop. This is how it looks with different Receivers:

Receiver for Windows, Receiver for HTML5 and Receiver for Chrome connecting via Gateway.

Connection to Gateway uses CGP protocol wrapped inside SSL/TLS by default. If gateway doesn’t understand CGP, SOCKS protocol is first used in the handshake phase and then ICA protocol is used for the rest of connection. SOCKS and CGP protocols help in proxying the connection from Receiver to Gateway to XenApp/XenDesktop.

Here another point to note is Websocket direct connection also uses Socks in the handshake phase and ICA in the rest of the connection. This is due to historic reasons where websocket listener was implemented as Socks proxy in XTE service. For CGP connections, ICA is wrapped inside CGP. So websocket connections are in some way similar to gateway proxy connections.

Tip: Logging in Receiver for HTML5/Receiver for Chrome would indicate if CGP/Socks/ICA protocol was used for the connection.

What about Receiver for Chrome?

Receiver for Chrome is a superset of Receiver for HTML5 Receiver and contains HTML5 HDX engine in its package so we don’t need to host it on a website. It is available in the Chrome web store or can be packaged and deployed to chromebooks.

Receiver for Chrome uses Receiver for Web (like in the case of Receiver for HTML5) for enumeration of apps/desktops and authentication. However, in Receiver for Chrome you enter the Receiver for web URL in its own embedded webview rather than a browser. ICA file contents are passed by Receiver for Web inside webview to Receiver for Chrome and then a HDX session is launched in a new window. The advantage of using the Chrome-packaged app is that the engine doesn’t need to be downloaded; Receiver can make use of HTML5 APIs as well as Chrome APIs like USB, hardware video/audio acceleration and most importantly in this article native socket API among others.

To support WebInterface or custom web portals developed by our customers, sessions can be launched using ICA files downloaded from the WebInterface/custom portal. WebInterface website URL (not PNAgent xml URL) can also be entered inside Receiver for Chrome and you avoid downloading of ICA file in this case.

Receiver for Chrome, until 1.6 release, used WebSockets for connections, so all the policy configurations were similar to Receiver for HTML5. Since code is not hosted on a https site, but instead embedded in the app, secure WebSocket issues do not apply here.

What we have seen from users is that unless admins have enabled WebSocket policies or have NetScaler Gateway, users couldn’t make connection to XenApp/XenDesktop.

Important note: Receiver for Chrome 1.7 uses standard sockets and connects to XenApp and XenDesktop like other Receivers!

Receiver for Chrome from 1.7 onwards uses Chrome sockets API for HDX connections and this means it can now connect to 1494 (ICA)/ 2598 (CGP) ports. Essentially connection diagram is more like other native Receivers. We no longer need any policies update in backend for connection from Chrome devices as WebSockets are no more required.

Session Reliability:

I have mentioned CGP in all the diagrams above, but Receiver for HTML5 till 1.6 did not support CGP or Session reliability. This meant even with brief network interruptions, users could see error messages and have to relaunch apps/desktops.

With the 1.7 update, both Receiver for HTML5 and Receiver for Chrome now support CGP based connections on which the Session reliability feature is built; brief network interruptions (< 3mins) should let you resume sessions smoothly. Please use XenApp 7.6 Feature Pack 2 or NetScaler gateway 11.0 version as they contain important bug fixes for this feature along with many other features.

Important tip: For Receiver for HTML5 when session reliability is enabled, since connections are via WebSockets, backend requirements are XenApp/XenDesktop 7.6 for direct connection without NetScaler or using NetScaler Gateway 11.0 for any supported version of XenApp or XenDesktop. In case of Receiver for Chrome CGP protocol work with XenApp 6.5 as well as all supported XenApp/XenDesktop 7.x versions.

Troubleshooting Connections:

In cases where you are not able to connect some of the following points might help in finding out the problem. They also can be used while opening support case or seeking help in forums:

1) Logging: Basic connection related logs are logged by Receiver for HTML5 and Receiver for Chrome.

2) Browser console logs: Browsers would show errors related to certificates or network related failures here.

  • Receiver for HTML5: Open developer tools for HDX session browser tab. Tip: In Windows, use F12 shortcut in address bar of session page.
  • Receiver for Chrome: Go to chrome://inspect, click on Apps on left side. Click on inspect for Citrix Receiver pages (Main.html, SessionWindow.html etc)

3) Certificates: If certificates are not trusted by your browser, then connections would fail. In enterprise typically domain based server certificates are used for internal connections. In Windows domain joined machines, these are automatically handled for Internet Explorer and Chrome. On Chromebooks, you need to import root CA certificate to the device.

  • In chromebooks use advanced security settings, go to ssl certificates and import domain root certificate authorities.
  • For Firefox check out advanced preferences and certificates section.
  • Also keep in mind that neither Receiver for HTML5 nor Receiver for Chrome support User cert based authentication via Gateway today. So if you have configured your gateway to use cert based authentication then connections may fail or not use client certificate authentication.


One important topic to mention is secure ICA. Receiver for HTML5 and Receiver for Chrome do not support SecureICA.

Instead the recommendation for secure connections is SSL/TLS which is more secure than SecureICA.

For secure connections the following points explain the behavior in more detail:

  • Receiver for HTML5 supports secure direct SSL/TLS connections with XenApp/XenDesktop 7.6.
  • Receiver for Chrome as it uses native sockets supports SSL relay with XenApp 6.5 (TLS 1.0 only) and direct SSL/TLS with XenApp/XenDesktop 7.6 (TLS 1.0, 1.1, 1.2)
  • Receiver for HTML5 and Receiver for Chrome support SSL/TLS connections via NetScaler Gateway to all supported versions of XenApp and XenDesktop.
  • Browsers handle all SSL/TLS traffic and this also means TLS 1.0/1.1 and 1.2 are supported by Receiver for HTML5 and Receiver for Chrome
  • As mentioned earlier for SSL direct connections you need to manage/install certificate on every VDA. So using a NetScaler Gateway would help here for ease of deployment. Connection to gateway is SSL/TLS and gateway to XenApp/XenDesktop is ICA/CGP. If you have XenApp and XenDesktop direct SSL configured then it can give end to end SSL for highest level of security.
  • Also in some cases you may not want all Receivers to connect via NetScaler gateway internally. One way to have this deployment is to create a different store for Receiver for HTML5/Chrome, use Gateway (VPX) to act as ICA proxy and make all internal connections go through it. Other Receivers can use regular store without NetScaler Gateway.
  • You can deploy NetScaler Gateway in double hop mode as well so that even external common gateway connects to internal gateway and you get SSL/TLS up to internal network of XenApp/XenDesktop.

This table shows protocol is in use when using different supported versions:

Ports and protocols used by Receiver for HTML5 and Receiver for Chrome

+When TLS 1.0 is in use, CGP works well with NetScaler Gateway 11.0 only and connection might fallback to ICA with older gateways.

This concludes the connection mechanism when using Receiver for HTML5 and Receiver for Chrome and hopefully helps resolve issues in your deployment. Share your feedback in comments below as that will help us improve the connection experience further.

In future blogs of this technical blog series we will look at other features in Citrix Receiver.