Optimization for Microsoft Teams

Note:

This feature depends on a future Microsoft Teams release. We will update this description as information about the version and release date become available.

Citrix delivers optimization for desktop-based Microsoft Teams using Citrix Virtual Apps and Desktops and Citrix Workspace app. By default, we bundle all the necessary components into Citrix Workspace app and the Virtual Delivery Agent (VDA).

Our optimization for Microsoft Teams contains VDA-side HDX services and API to interface with the Microsoft Teams hosted app to receive commands. These components open a control virtual channel to the Citrix Workspace app-side media engine. The endpoint decodes and renders the multimedia locally. Reverse seamless snaps-in the local Citrix Workspace app window back into the hosted Microsoft Teams app.

Authentication and signaling occurs natively on the Microsoft Teams-hosted app, just like the other Microsoft Teams services (for example chat or collaboration). Audio/video redirection doesn’t affect them.

Only Client-fetch/client-render is available.

This video demo gives you an idea of how Microsoft Teams works in a Citrix virtual environment.

Optimization for Microsoft Teams demo

Call establishment and media flow paths

When possible, the HDX media engine in the Citrix Workspace app (HdxTeams.exe) tries to establish a direct network SRTP connection over User Datagram Protocol (UDP) in a peer-to-peer call. If the UDP ports are blocked, the media engine falls back to TCP 443.

The HDX media engine supports ICE, Session Traversal Utilities for NAT (STUN), and Traversal Using Relays around NAT (TURN) for candidate discovery and connection establishment. If there is no direct path between the peers, or if the user is joining a multi-party call or a meeting, HdxTeams.exe uses a Microsoft Teams transport relay server in Azure. The user’s client machine must have access to several Azure IP address ranges. For more information, see the Architecture diagram in the “Call setup” section further down and Office 365 URLs and IP address ranges ID 11.

HdxTeams.exe contacts the Microsoft Teams transport relay cloud using anycast IP and port 3478–3481 UDP (different UDP ports per workload, though multiplexing can happen) and 443 TCP. Call quality depends on the underlying network protocol. Because UDP is always recommended over TCP, we advise you to design your networks to accommodate UDP traffic. Most call setup failures are ICE failures. Check that first when a call cannot be completed. For more information about the ICE candidate gathering process, see “Collecting logs” in the Support section.

Note:

If the endpoints do not have internet access, it might still be possible for the user to make a peer-to-peer call only (Meetings fail). In this case, there is a 30 second timeout before the call setup begins.

Call setup

Use this architecture diagram as a visual reference for the call flow sequence. The corresponding steps are indicated in the diagram.

Architecture:

How optimization for Microsoft Teams works

  1. Launch Microsoft Teams.
  2. Teams authenticates to O365. Tenant policies are pushed down to the Teams client, and relevant TURN and signaling channel information is relayed to the app.
  3. Teams detects that it is running in a VDA and makes API calls to the Citrix JavaScript API, which is embedded in Teams.
  4. Citrix JavaScript in Teams opens a secure WebSocket connection to WebSocketService.exe running on the VDA (127.0.0.1:9002). WebSocketService.exe runs as a Local System account on session 0. WebSocketService.exe performs TLS termination and user session mapping, and spawns WebSocketAgent.exe, which now runs inside the user session.
  5. WebSocketAgent.exe instantiates a generic virtual channel by calling into the Citrix HDX Browser Redirection Service (CtxSvcHost.exe).
  6. Citrix Workspace app’s wfica32.exe (HDX engine) spawns a new process called HdxTeams.exe, which is the new WebRTC engine used for Teams optimization.
  7. HdxTeams.exe and Teams.exe have a 2-way virtual channel path and can start processing multimedia requests.

    —–User calls——

  8. Peer A clicks the call button. Teams.exe communicates with the Teams services in Azure establishing an end-to-end signaling path with Peer B. Teams asks HdxTeams for a series of supported call parameters (codecs, resolutions, and so forth, which is known as a Session Description Protocol (SDP) offer). These call parameters are then relayed using the signaling path to the Teams services in Azure and from there to the other peer.
  9. The SDP offer/answer (single-pass negotiation) and the Interactive Connectivity Establishment (ICE) connectivity checks (NAT and Firewall traversal using Session Traversal Utilities for NAT (STUN) bind requests) complete. Then, Secure Real-time Transport Protocol (SRTP) media flows directly between HdxTeams.exe and the other peer (or O365 conference servers if it is a Meeting).

Network requirements

Microsoft Teams relies on Transport Relay servers in Azure for meetings, multiparty calls, and scenarios where two peers in a point-to-point call do not have direct connectivity. Therefore, the network health between the peer and the Office 365 cloud determines the performance of the call.

We recommend evaluating your environment to identify any risks and requirements that can influence your overall cloud voice and video deployment. Use the Skype for Business Network Assessment Tool to test if your network is ready for Microsoft Teams. For support information, see Support section.

Metric Endpoint to Office 365
Latency (one way) < 50 msec
Latency (RTT) < 100 msec
Packet Loss <1% during any 15s interval
Packet inter-arrival jitter <30ms during any 15s interval

For more information, see Prepare your organization’s network for Microsoft Teams.

In terms of bandwidth requirements, optimization for Microsoft Teams can use a wide variety of codecs for audio (G.722/OPUS/PCM) and video (H264/VP9). The peers negotiate these codecs during the call establishment process using the Session Description Protocol (SDP) Offer/Answer. Citrix minimum recommendations are:

Type Bandwidth Codec
Audio (each way) ~ 90 kbps G.722
Video (each way) ~ 700 kbps H264 360p @ 30 fps 16:9
Video (each way) ~ 2500 kbps H264 720p @ 30 fps 16:9
Screen sharing ~ 300 kbps H264 1080p @ 15 fps

System requirements

Minimum version - Virtual Delivery Agents (VDAs) 1906:

Supported operating systems:

  • Windows 10 64-bit, minimum versions 1607 up to 1903.
  • Windows Server 2019, 2016, and 2012 R2 (Standard and Datacenter Editions).

Requirements:

The installer automatically installs the following items, which are available on the Citrix installation media in the Support folders:

  • Microsoft .NET Framework 4.7.1 or later is installed automatically if it is not already installed.
  • Microsoft Visual C++ 2013 and 2015 Runtimes, 32-bit and 64-bit.
  • BCR_x64.msi - the MSI that contains the Microsoft Teams optimization code and starts automatically from the GUI. If you’re using the command line interface for the VDA installation, don’t exclude it.

For Windows Server, if you didn’t install and enable the Remote Desktop Services roles, the installer automatically installs and enables those roles.

Minimum version - Citrix Workspace app 1905 for Windows:

  • Windows 7, 8, and 10 (32-bit and 64-bit editions, including Embedded editions)
  • Endpoint requirement: Approximately 1.8–2.0 GHz quad core CPU that can support 360p nHD resolution during a peer-to-peer video conference call.
  • Citrix Workspace app requires a minimum of 600 MB free disk space and 1 GB RAM.
  • Microsoft .NET Framework minimum requirement is version 4.6.2. Citrix Workspace app automatically downloads and installs .NET Framework if it is not present in the system.
  • This version of Citrix Workspace app supports Audio and Video redirection (peer-to-peer or conference) and incoming screen sharing. Outgoing screen sharing is not supported with Citrix Workspace app 1905 for Windows. Versions 1907 and later support outgoing screen sharing.

Enable optimization of Microsoft Teams

To enable optimization for Microsoft Teams, use the Studio policy described in Microsoft Teams redirection policy. In addition to this policy being enabled, HDX checks to verify that the version of Citrix Workspace app is equal to or greater than the minimum required version. If the policy is enabled and the version of Citrix Workspace app is supported, the HKEY_CURRENT_USER\Software\Citrix\HDXMediaStream\MSTeamsRedirSupport registry key is set to 1 automatically on the VDA. The Microsoft Teams application reads the key to load in VDI mode.

Peripherals in Microsoft Teams

When optimization for Microsoft Teams is active, Citrix Workspace app accesses the peripherals (headset, microphone, cameras, speakers, and so forth). Then the peripherals are properly enumerated in the Microsoft Teams UI (Settings > Devices).

Optimization mode for Microsoft Teams

Microsoft Teams does not access the devices directly. Instead, it relies on HdxTeams.exe for acquiring, capturing, and processing the media. Microsoft Teams lists the devices for the user to select.

Note:

We recommend:

  • Microsoft Teams certified headsets with built-in echo cancellation. In setups with multiple peripherals, where microphone and speakers are on separate devices (for example, a webcam with a built-in microphone, and a monitor with speakers) an echo might be present. When using external speakers, place them as far as possible from the microphone and from any surface that might refract the sound into the microphone.

  • Microsoft Teams certified cameras, although Skype for Business certified peripherals are compatible with Microsoft Teams.

HdxTeams.exe cannot take advantage of CPU offloading with webcams that perform on-board H.264 encoding -UVC 1.1 and 1.5.

The HDX technologies can use either of these methods for mapping peripherals:

  • Optimization for Microsoft Teams (recommended mode).
  • If Microsoft Teams fails to load in optimized VDI mode, the VDA uses legacy HDX technologies like Webcam redirection and client Audio and Microphone redirection. In the unoptimized mode, the peripherals are mapped to the VDA. The peripherals appear to the Microsoft Teams app as if they were locally attached to the virtual desktop.

    The most significant difference is the camera name. If Microsoft Teams loaded in unoptimized mode, legacy HDX technologies launch and the webcam name has the Citrix HDX suffix as shown in the following graphic. The speaker and microphone device names might be slightly different when compared to the optimized mode.

Unoptimization mode for Microsoft Teams

When legacy HDX technologies are used, Microsoft Teams doesn’t offload audio, video, and screen sharing processing to the endpoint’s Citrix Workspace app WebRTC media engine. Instead, HDX technologies use server-side rendering. Expect high CPU consumption on the VDA when you turn on video. Real time audio performance might not be optimal.

Troubleshoot

This section provides troubleshooting tips for issues that you might encounter when using optimization for Microsoft Teams. Further information can be found in CTX253754.

On the Virtual Delivery Agent

There are four services installed by BCR_x64.msi. Only two are responsible for Microsoft Teams redirection in the VDA.

Four services installed by browser content redirection

  • Citrix HDX Teams Redirection Service establishes the virtual channel used in Microsoft Teams. The service relies on CtxSvcHost.exe.

  • Citrix HDX HTML5 Video Redirection Service runs as WebSocketService.exe listening on 127.0.0.1:9002 TCP. WebSocketService.exe performs two main functions:

    i. TLS termination for secure WebSockets receives a secure WebSocket connection from vdiCitrixPeerConnection.js, which is a component inside the Microsoft Teams app. You can track it with the Process Monitor. For more information about certificates, see the section “TLS and HTML5 video redirection, and browser content redirection” under Communication between Controller and VDA.

    Process Monitor

    ii. User session mapping. When the Microsoft Teams application starts, WebSocketService.exe starts the WebSocketAgent.exe process in the user’s session in the VDA. WebSocketService.exe runs in Session 0 as a LocalSystem account.

    WebSocketAgent.exe service

    You can use netstat to check if the WebSocketService.exe service is in an active listening state in the VDA.

    Run netstat -anob -p tcp from an elevated command prompt window:

    Run netstat example

    On a successful connection, the state changes to ESTABLISHED:

    Successful netstat example

Important:

WebSocketService.exe listens in two TCP sockets, 127.0.0.1:9001 and 127.0.0.1:9002. Port 9001 is used for browser content redirection and HTML5 video redirection. Port 9002 is used for Microsoft Teams redirection. Ensure that you don’t have any proxy configurations in the Windows OS of the VDA that can prevent a direct communication between Teams.exe and WebSocketService.exe. Sometimes, when you configure an explicit proxy in Internet Explorer 11 (Internet Options > Connections > LAN settings > Proxy Server), connections might flow through an assigned proxy server. Verify that Bypass proxy server for local addresses is checked when using a manual and explicit proxy setting.

Services locations and descriptions

Service Path to executable Log on as Description
Citrix HTML5 Video Redirection Service “C:\Program Files (x86)\Citrix\System32\WebSocketService.exe” /service Local System account Provides multiple HDX Multimedia services with the initial framework required to perform media redirection between the virtual desktop and the endpoint device.
Citrix HDX Browser Redirection Service “C:\Program Files (x86)\Citrix\System32\CtxSvcHost.exe” -g BrowserRedirSvcs This account (local service) Provides browser content redirection between the endpoint device and the virtual desktop.
Citrix Port Forwarding Service “C:\Program Files (x86)\Citrix\System32\CtxSvcHost.exe” -g PortFwdSvcs This account (local service) Provides port forwarding between the endpoint device and the virtual desktop for browser content redirection.
Citrix HDX Teams Redirection Service “C:\Program Files (x86)\Citrix\System32\CtxSvcHost.exe” -g TeamsSvcs Local System account Provides Microsoft Teams redirection between the endpoint device and the virtual desktop.

Citrix Workspace app

On the user’s endpoint, Citrix Workspace app for Windows instantiates a new service called HdxTeams.exe. It does so when Microsoft Teams launches in the VDA and the user tries to call or access peripherals in self-preview. If you don’t see this service, check the following:

  1. Ensure that you installed as a minimum the Workspace App version 1905 for Windows. Do you see HdxTeams.exe and the webrpc.dll binaries in the Workspace app installation path?
  2. If you validated step1, do the following to check if HdxTeams.exe is getting launched.
    1. Exit Microsoft Teams on the VDA.
    2. Start services.msc on VDA.
    3. Stop the Citrix HDX Teams Redirection Service.
    4. Disconnect the ICA session.
    5. Connect the ICA session.
    6. Start the Citrix HDX Teams Redirection Service.
    7. Restart the Citrix HDX HTML5 Video Redirection Service.
    8. Launch Microsoft Teams on the VDA.
  3. If you still don’t see HdxTeams.exe being launched on the client endpoint, do the following:
    1. Restart the VDA.
    2. Restart the client endpoint.

Support

Citrix and Microsoft jointly support the delivery of Microsoft Teams from Citrix Virtual Apps and Desktops using optimization for Microsoft Teams. This joint support is the result of close collaboration between the two companies. If you have valid support contracts and you experience an issue with this solution, open a support ticket with the vendor whose code you suspect to be causing the issue. That is, Microsoft for Teams or Citrix for the optimization components.

Citrix or Microsoft receives the ticket, triages the issue, and escalates as appropriate. There is no need for you to contact each company’s support team.

Collecting logs

HDXTeams.exe logs can be found on the user’s machine at %TEMP% inside the HDXTeams folder (AppData/Local/Temp/HDXTeams). Look for a .txt file called webrpc_Day_Month_timestamp_Year.txt.

In the HdxTeams.exe logs, the following entries are the relevant Interactive Connectivity Establishment (ICE) entries. These entries must be there for a call set-up to succeed (see this sample snippet):

RPCStubs Info: -> device id = \\?\display#int3470#4&1835d135&0&uid13424#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\{bf89b5a5-61f7-4127-a279-e187013d7caf} label = Microsoft Camera Front groupId =

RTCPeerConnection::createOffer. audio = 1 video = 1
RTCPeerConnection::OnSignalingChange. signaling state = HaveLocalOffer
video_element::connectTo
RTCPeerConnection::OnIceGatheringChange. state = Gathering

[…]
candidate:840548147 1 udp 2122194687 10.108.124.215 56927 typ host generation 0 ufrag oVk6 network-id 1
[…]
candidate:4271145120 1 udp 1685987071 66.165.176.60 55839 typ srflx raddr 10.108.124.215 rport 55839 generation 0 ufrag uAVH network-id 1
[…]

RTCPeerConnection::OnIceGatheringChange. state = Complete
RTCPeerConnection::setRemoteDescription

RTCPeerConnection::OnSignalingChange. signaling state = HaveRemoteOffer

If you encounter an issue and can reproduce it consistently, we recommend capturing CDF traces before contacting Support. For more information, see the Knowledge Center article CDFcontrol.

For recommendations for collecting CDF Traces, see the Knowledge Center article Recommendations for Collecting the CDF Traces.

VDA side CDF traces - Enable the following CDF trace providers:

VDA side CDF traces

Workspace App side CDF traces - Enable the following CDF trace providers:

Workspace App side CDF traces