We use optional cookies to improve your experience on our websites, such as through social media connections, and to display

personalized advertising based on your online activity. If you reject optional cookies, only cookies necessary to provide you the services will be used.
You may change your selection by clicking “Manage Cookies” at the bottom of the page. Privacy Statement Third-Party Cookies
Accept Reject Manage cookies

Microsoft Build AI has disrupted the industry. Join us as we disrupt it some more. Register now Ｔ
May 21–23, 2024

Learn Discover Ｓ Product documentation Ｓ Development languages Ｓ Topics Ｓ  Sign in

Windows Server Get started Failover clustering Management Identity and access Networking Troubleshooting Related products Ｓ

 Filter by title Learn / Windows Server / Remote desktop services /  ／  Additional resources

Set up the Remote Desktop web client for your

Remote Desktop Services
Ｔ Get started  Events
Ｔ Plan and design

Build and deploy

users Migrate to Innovate - Be AI Ready, Be Secure
Ｔ

Apr 16, 6 PM - Apr 16, 8 PM

Build and deploy Article • 09/28/2023 • 15 contributors  Feedback
Join us on April 16 to learn how migrating Windows Server and
Deploy a proof-of-concept RDS environment with ARM and SQL Server to Azure fuels innovation.

Azure Marketplace In this article Join now

Migrate your Remote Desktop Services deployments to What you'll need to set up the web client
Windows Server 2016 How to publish the Remote Desktop web client
 Training
Migrate your Remote Desktop Services Client Access How to update the Remote Desktop web client
Licenses (RDS CALs) Module
How to uninstall the Remote Desktop web client
Employ remote management - Training
Ｔ Upgrade your Remote Desktop Services deployments to Show 5 more This module demonstrates the various tools for connecting
Windows Server 2016 remotely to a Windows client.

Deploy a Remote Desktop Services infrastructure The Remote Desktop web client lets users access your organization's Remote Desktop infrastructure through a
Certification
Create and deploy a Remote Desktop Services collection
compatible web browser. They'll be able to interact with remote apps or desktops like they would with a local PC no Microsoft Certified: Azure Virtual Desktop Specialty -
matter where they are. Once you set up your Remote Desktop web client, all your users need to get started is the URL Certifications
Configure the RD Gateway role
where they can access the client, their credentials, and a supported web browser. Plan, deliver, manage, and monitor virtual desktop experiences
Set up the Remote Desktop web client for your users and remote apps on Microsoft Azure for any device.
Disable Automatic Reconnection
） Important
Set up email discovery for your users
 Documentation
Fair Share technologies The web client does support using Microsoft Entra application proxy but does not support Web Application Proxy at
Ｔ License your Remote Desktop deployment
all. See Using RDS with application proxy services for details. Deploy Remote Desktop Gateway role for Remote Desktop
Services
Ｔ Integrate Azure services
How to deploy the Remote Desktop Gateway role for Remote
Extend your RDS environment for high availability Desktop Services.
What you'll need to set up the web client
Ｔ

Ｔ Set up disaster recovery for your RDS environment

Deploy your Remote Desktop environment
Ｔ Run and tune
Before getting started, keep the following things in mind: Basic steps to deploy a Remote Desktop environment.
Ｔ Access your Remote Desktop resources
Make sure your Remote Desktop deployment has an RD Gateway, an RD Connection Broker, and RD Web Access Create a Remote Desktop Services collection
running on Windows Server 2016 or 2019. Learn how to create a Remote Desktop Services session
collection.
Make sure your deployment is configured for per-user client access licenses (CALs) instead of per-device, otherwise
Show 3 more
all licenses will be consumed.

Install the Windows 10 KB4025334 update on the RD Gateway. Later cumulative updates may already contain this
KB.

Make sure public trusted certificates are configured for the RD Gateway and RD Web Access roles.

Make sure that any computers your users connect to are running one of the following OS versions:
Windows 10 or later
Windows Server 2016 or later

Your users will see better performance connecting to Windows Server 2016 (or later) and Windows 10 (version 1611 or
later).

 Download PDF
） Important

If you used the web client during the preview period and installed a version prior to 1.0.0, you must first uninstall
the old client before moving to the new version. If you receive an error that says "The web client was installed using
an older version of RDWebClientManagement and must first be removed before deploying the new version," follow
these steps:

1. Open an elevated PowerShell prompt.

2. Run Uninstall-Module RDWebClientManagement to uninstall the new module.
3. Close and reopen the elevated PowerShell prompt.
4. Run Install-Module RDWebClientManagement -RequiredVersion <old version> to install the old module.
5. Run Uninstall-RDWebClient to uninstall the old web client.
6. Run Uninstall-Module RDWebClientManagement to uninstall the old module.
7. Close and reopen the elevated PowerShell prompt.
8. Proceed with the normal installation steps as follows.

How to publish the Remote Desktop web client

To install the web client for the first time, follow these steps:

1. On the RD Connection Broker server, obtain the certificate used for Remote Desktop connections and export it as a
.cer file. Copy the .cer file from the RD Connection Broker to the server running the RD Web role.

2. On the RD Web Access server, open an elevated PowerShell prompt.

3. On Windows Server 2016, update the PowerShellGet module since the inbox version doesn't support installing the
web client management module. To update PowerShellGet, run the following cmdlet:

PowerShell ＝ Copy

Install-Module -Name PowerShellGet -Force

７ Note

To access the PowerShell Gallery, Transport Layer Security (TLS) 1.2 or higher is required. Use the following
command to enable TLS 1.2 in your PowerShell session:

PowerShell ＝ Copy

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

） Important

You'll need to restart PowerShell before the update can take effect, otherwise the module may not work.

4. Install the Remote Desktop web client management PowerShell module from the PowerShell gallery with this
cmdlet:

PowerShell ＝ Copy

Install-Module -Name RDWebClientManagement

5. After that, run the following cmdlet to download the latest version of the Remote Desktop web client:

PowerShell ＝ Copy

Install-RDWebClientPackage

6. Next, run this cmdlet with the bracketed value replaced with the path of the .cer file that you copied from the RD
Broker:

PowerShell ＝ Copy

Import-RDWebClientBrokerCert <.cer file path>

7. Finally, run this cmdlet to publish the Remote Desktop web client:

PowerShell ＝ Copy

Publish-RDWebClientPackage -Type Production -Latest

Make sure you can access the web client at the web client URL with your server name, formatted as
https://server_FQDN/RDWeb/webclient/index.html . It's important to use the server name that matches the RD Web

Access public certificate in the URL (typically the server FQDN).

７ Note

When running the Publish-RDWebClientPackage cmdlet, you may see a warning that says per-device CALs
are not supported, even if your deployment is configured for per-user CALs. If your deployment uses per-user
CALs, you can ignore this warning. We display it to make sure you're aware of the configuration limitation.

8. When you're ready for users to access the web client, just send them the web client URL you created.

７ Note

To see a list of all supported cmdlets for the RDWebClientManagement module, run the following cmdlet in
PowerShell:

PowerShell ＝ Copy

Get-Command -Module RDWebClientManagement

How to update the Remote Desktop web client

When a new version of the Remote Desktop web client is available, follow these steps to update the deployment with
the new client:

1. Open an elevated PowerShell prompt on the RD Web Access server and run the following cmdlet to download the
latest available version of the web client:

PowerShell ＝ Copy

Install-RDWebClientPackage

2. Optionally, you can publish the client for testing before official release by running this cmdlet:

PowerShell ＝ Copy

Publish-RDWebClientPackage -Type Test -Latest

The client should appear on the test URL that corresponds to your web client URL (for example,
<https://server_FQDN/RDWeb/webclient-test/index.html> ).

3. Publish the client for users by running the following cmdlet:

PowerShell ＝ Copy

Publish-RDWebClientPackage -Type Production -Latest

This replaces the client for all users when they relaunch the web page.

How to uninstall the Remote Desktop web client

To remove all traces of the web client, follow these steps:

1. On the RD Web Access server, open an elevated PowerShell prompt.

2. Unpublish the Test and Production clients, uninstall all local packages and remove the web client settings:

PowerShell ＝ Copy

Uninstall-RDWebClient

3. Uninstall the Remote Desktop web client management PowerShell module:

PowerShell ＝ Copy

Uninstall-Module -Name RDWebClientManagement

How to install the Remote Desktop web client without

an internet connection
Follow these steps to deploy the web client to an RD Web Access server that doesn't have an internet connection.

７ Note

Installing without an internet connection is available in version 1.0.1 and above of the RDWebClientManagement
PowerShell module.

７ Note

You still need an admin PC with internet access to download the necessary files before transferring them to the
offline server.

７ Note

The end-user PC needs an internet connection for now. This will be addressed in a future release of the client to
provide a complete offline scenario.

From a device with internet access

1. Open a PowerShell prompt.

2. Import the Remote Desktop web client management PowerShell module from the PowerShell gallery:

PowerShell ＝ Copy

Import-Module -Name RDWebClientManagement

3. Download the latest version of the Remote Desktop web client for installation on a different device:

PowerShell ＝ Copy

Save-RDWebClientPackage "C:\WebClient\"

4. Download the latest version of the RDWebClientManagement PowerShell module:

PowerShell ＝ Copy

Find-Module -Name "RDWebClientManagement" -Repository "PSGallery" | Save-Module -Path "C:\WebClient\"

5. Copy the content of "C:\WebClient" to the RD Web Access server.

From the RD Web Access server

Follow the instructions under How to publish the Remote Desktop web client, replacing steps 4 and 5 with the following.

4. You have two options to retrieve the latest web client management PowerShell module:

Import the Remote Desktop web client management PowerShell module:

PowerShell ＝ Copy

Import-Module -Name RDWebClientManagement

Copy the downloaded RDWebClientManagement folder to one of the local PowerShell module folders listed
under $env:psmodulePath, or add the path to the folder with the downloaded files to the
$env:psmodulePath.

5. Deploy the latest version of the Remote Desktop web client from the local folder (replace with the appropriate zip
file):

PowerShell ＝ Copy

Install-RDWebClientPackage -Source "C:\WebClient\rdwebclient-1.0.1.zip"

Connecting to RD Broker without RD Gateway in

Windows Server 2019
This section describes how to enable a web client connection to an RD Broker without an RD Gateway in Windows Server
2019.

Setting up the RD Broker server

Follow these steps if there's no certificate bound to the RD Broker server

1. Open Server Manager > Remote Desktop Services.

2. In Deployment Overview section, select the Tasks dropdown menu.

3. Select Edit Deployment Properties, a new window titled Deployment Properties will open.

4. In the Deployment Properties window, select Certificates in the left menu.

5. In the list of Certificate Levels, select RD Connection Broker - Enable Single Sign On. You have two options: (1)
create a new certificate or (2) an existing certificate.

Follow these steps if there's a certificate previously bound to the RD Broker

server
1. Open the certificate bound to the Broker and copy the Thumbprint value.

2. To bind this certificate to the secure port 3392, open an elevated PowerShell window and run the following
command, replacing "< thumbprint >" with the value copied from the previous step:

PowerShell ＝ Copy

netsh http add sslcert ipport=0.0.0.0:3392 certhash="<thumbprint>" certstorename="Remote Desktop" appid=

７ Note

To check if the certificate has been bound correctly, run the following command:

PowerShell ＝ Copy

netsh http show sslcert

In the list of SSL Certificate bindings, ensure that the correct certificate is bound to port 3392.

3. Open the Windows Registry (regedit), go to HKLM\SYSTEM\CurrentControlSet\Control\Terminal

Server\WinStations\RDP-Tcp and locate the key WebSocketURI. Next, set the value to https://+:3392/rdp/ .

Setting up the RD Session Host

Follow these steps if the RD Session Host server is different from the RD Broker server:

1. Create a certificate for the RD Session Host machine, open it and copy the Thumbprint value.

2. To bind this certificate to the secure port 3392, open an elevated PowerShell window and run the following
command, replacing "< thumbprint >" with the value copied from the previous step:

PowerShell ＝ Copy

netsh http add sslcert ipport=0.0.0.0:3392 certhash="<thumbprint>" appid="{00000000-0000-0000-0000-00000

７ Note

To check if the certificate has been bound correctly, run the following command:

PowerShell ＝ Copy

netsh http show sslcert

In the list of SSL Certificate bindings, ensure that the correct certificate is bound to port 3392.

3. Open the Windows Registry (regedit) and navigate to HKLM\SYSTEM\CurrentControlSet\Control\Terminal

Server\WinStations\RDP-Tcp and locate the key WebSocketURI. The value must be set to https://+:3392/rdp/ .

General Observations
Ensure that both the RD Session Host and RD Broker server are running Windows Server 2019.

Ensure that public trusted certificates are configured for both the RD Session Host and RD Broker server.

７ Note

If both the RD Session Host and the RD Broker server share the same machine, set the RD Broker server
certificate only. If the RD Session Host and RD Broker server use different machines, both must be configured
with unique certificates.

The Subject Alternative Name (SAN) for each certificate must be set to the machine's Fully Qualified Domain
Name (FQDN). The Common Name (CN) must match the SAN for each certificate.

How to pre-configure settings for Remote Desktop

web client users
This section tells you how to use PowerShell to configure settings for your Remote Desktop web client deployment.
These PowerShell cmdlets control a user's ability to change settings based on your organization's security concerns or
intended workflow. The following settings are all located in the Settings side panel of the web client.

Suppress telemetry
By default, users may choose to enable or disable collection of telemetry data that is sent to Microsoft. For information
about the telemetry data Microsoft collects, refer to our Privacy Statement via the link in the About side panel.

As an administrator, you can choose to suppress telemetry collection for your deployment using the following
PowerShell cmdlet:

PowerShell ＝ Copy

Set-RDWebClientDeploymentSetting -Name "SuppressTelemetry" $true

By default, the user may select to enable or disable telemetry. A boolean value $false will match the default client
behavior. A boolean value $true disables telemetry and restricts the user from enabling telemetry.

Remote resource launch method

７ Note

This setting currently only works with the RDS web client, not the Azure Virtual Desktop web client.

By default, users may choose to launch remote resources (1) in the browser or (2) by downloading an .rdp file to handle
with another client installed on their machine. As an administrator, you can choose to restrict the remote resource launch
method for your deployment with the following PowerShell command:

PowerShell ＝ Copy

Set-RDWebClientDeploymentSetting -Name "LaunchResourceInBrowser" ($true|$false)

By default, the user may select either launch method. A boolean value $true will force the user to launch resources in the
browser. A boolean value $false forces the user to launch resources by downloading an .rdp file to handle with a locally
installed RDP client.

Reset RDWebClientDeploymentSetting configurations to default

To reset a deployment-level web client setting to the default configuration, run the following PowerShell cmdlet and use
the -name parameter to specify the setting you want to reset:

PowerShell ＝ Copy

Reset-RDWebClientDeploymentSetting -Name "LaunchResourceInBrowser"

Reset-RDWebClientDeploymentSetting -Name "SuppressTelemetry"

Troubleshooting
If a user reports any of the following issues when opening the web client for the first time, the following sections will tell
you what to do to fix them.

What to do if the user's browser shows a security warning when

they try to access the web client
The RD Web Access role might not be using a trusted certificate. Make sure the RD Web Access role is configured with a
publicly trusted certificate.

If that doesn't work, your server name in the web client URL might not match the name provided by the RD Web
certificate. Make sure your URL uses the FQDN of the server hosting the RD Web role.

What to do if the user can't connect to a resource with the web

client even though they can see the items under All Resources
If the user reports that they can't connect with the web client even though they can see the resources listed, check the
following things:

Is the RD Gateway role properly configured to use a trusted public certificate?

Does the RD Gateway server have the required updates installed? Make sure that your server has the KB4025334
update installed.

If the user gets an "unexpected server authentication certificate was received" error message when they try to connect,
then the message will show the certificate's thumbprint. Search the RD Broker server's certificate manager using that
thumbprint to find the right certificate. Verify that the certificate is configured to be used for the RD Broker role in the
Remote Desktop deployment properties page. After making sure the certificate hasn't expired, copy the certificate in .cer
file format to the RD Web Access server and run the following command on the RD Web Access server with the
bracketed value replaced by the certificate's file path:

PowerShell ＝ Copy

Import-RDWebClientBrokerCert <certificate file path>

Diagnose issues with the console log

If you can't solve the issue based on the troubleshooting instructions in this article, you can try to diagnose the source of
the problem yourself by watching the console log in the browser. The web client provides a method for recording the
browser console log activity while using the web client to help diagnose issues.

Select the ellipsis in the upper-right corner and navigate to the About page in the dropdown menu.
Under Capture support information select the Start recording button.
Perform the operation(s) in the web client that produced the issue you're trying to diagnose.
Navigate to the About page and select Stop recording.
Your browser will automatically download a .txt file titled RD Console Logs.txt. This file contains the full console log
activity generated while reproducing the target issue.

The console may also be accessed directly through your browser. The console is generally located under the developer
tools. For example, you can access the log in Microsoft Edge by pressing the F12 key, or by selecting the ellipsis, then
navigating to More tools > Developer Tools.

Get help with the web client

If you've encountered an issue that can't be solved by the information in this article, you can report it on the Azure
Virtual Desktop forum of Microsoft Tech Community .

Feedback

） Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content
and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.

Submit and view feedback for

This product ６ This page

６ View all page feedback

 English (United States) Your Privacy Choices ０ Theme Ｓ Manage cookies Previous Versions Blog Contribute Privacy Terms of Use Trademarks © Microsoft 2024