You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/devtest-labs/configure-lab-remote-desktop-gateway.md
+40-40Lines changed: 40 additions & 40 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,35 +11,35 @@ ms.custom: UpdateFrequency2
11
11
12
12
# Configure and use a remote desktop gateway in Azure DevTest Labs
13
13
14
-
This article describes how to set up and use a gateway for secure [remote desktop](/windows-server/remote/remote-desktop-services/Welcome-to-rds) access to lab virtual machines (VMs) in Azure DevTest Labs. Using a gateway improves security because you don't expose the VMs' remote desktop protocol (RDP) ports to the internet. This remote desktop gateway solution also supports token authentication.
14
+
This article describes how to set up and use a gateway for secure [remote desktop](/windows-server/remote/remote-desktop-services/Welcome-to-rds) access to lab virtual machines (VMs) in Azure DevTest Labs. Using a gateway improves security because you don't expose the VMs' Remote Desktop Protocol (RDP) ports to the internet. This remote desktop gateway solution also supports token authentication.
15
15
16
16
DevTest Labs provides a central place for lab users to view and connect to their VMs. Selecting **Connect** > **RDP** on a lab VM's **Overview** page creates a machine-specific RDP file, and users can open the file to connect to the VM.
17
17
18
-
With a remote desktop gateway, lab users connect to their VMs through a gateway machine. Users authenticate directly to the gateway machine, and can use company-supplied credentials on domain-joined machines. Token authentication provides an extra layer of security.
18
+
With a remote desktop gateway, lab users connect to their VMs through a gateway machine. Users authenticate directly to the gateway machine and can use company-supplied credentials on domain-joined machines. Token authentication provides an extra layer of security.
19
19
20
20
Another way to securely access lab VMs without exposing ports or IP addresses is through a browser with Azure Bastion. For more information, see [Enable browser connection to DevTest Labs VMs with Azure Bastion](enable-browser-connection-lab-virtual-machines.md).
21
21
22
22
## Architecture
23
23
24
24
The following diagram shows how a remote desktop gateway applies token authentication and connects to DevTest Labs VMs.
25
25
26
-
26
+
:::image type="content" source="./media/configure-lab-remote-desktop-gateway/architecture.png" alt-text="Diagram that shows the remote desktop gateway architecture." lightbox="./media/configure-lab-remote-desktop-gateway/architecture.png":::
27
27
28
28
1. Selecting **Connect** > **RDP** from a lab VM invokes the [getRdpFileContents](/rest/api/dtl/virtualmachines/getrdpfilecontents) REST command:
29
29
30
30
```http
31
31
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DevTestLab/labs/{labName}/virtualmachines/{name}/getRdpFileContents
32
32
```
33
33
34
-
1. When the lab has a gateway configured, the `getRdpFileContents` action invokes `https://{gateway-hostname}/api/host/{lab-machine-name}/port/{port-number}` to request an authentication token.
34
+
1. When the lab is configured with a gateway, the `getRdpFileContents` action invokes `https://{gateway-hostname}/api/host/{lab-machine-name}/port/{port-number}` to request an authentication token.
35
35
-`{gateway-hostname}`, or `{lb-uri}` for a load balancer, is the gateway hostname specified on the **Lab settings** page for the lab.
36
36
-`{lab-machine-name}` is the name of the VM to connect to.
37
-
-`{port-number}` is the port to use for the connection. Usually this port is 3389, but if the lab VM uses a [shared IP](devtest-lab-shared-ip.md), the port number is different.
37
+
-`{port-number}` is the port to use for the connection. Usually this port is 3389, but if the lab VM uses a [shared IP address](devtest-lab-shared-ip.md), the port number is different.
38
38
39
39
1. The remote desktop gateway uses `https://{function-app-uri}/api/host/{lab-machine-name}/port/{port-number}` to defer the call to an Azure Functions function app.
40
40
41
41
> [!NOTE]
42
-
> The request header automatically includes the function key, which it gets from the lab's key vault. The function key secret's name is the **Gateway token secret** on the lab's **Lab settings** page.
42
+
> The request header automatically includes the function key, which it gets from the lab's key vault. The function key secret's name is the **Gateway token secret**that's specified on the lab's **Lab settings** page.
43
43
44
44
1. The Azure function generates and returns a token for certificate-based authentication on the gateway machine.
45
45
@@ -55,13 +55,13 @@ When an RDP connection program opens the RDP file, the remote desktop gateway au
55
55
56
56
## Configuration requirements
57
57
58
-
There are some configuration requirements for gateway machines, Azure Functions, and networks to work with DevTest Labs RDP access and token authentication:
58
+
There are some configuration requirements for enabling gateway machines, Azure Functions, and networks to work with DevTest Labs RDP access and token authentication:
59
59
60
60
### Gateway machine requirements
61
61
62
62
The gateway machine must have the following configuration:
63
63
64
-
- A TLS/SSL certificate to handle HTTPS traffic. The certificate must match the fully qualified domain name (FQDN) of the gateway machine if there's only one machine, or the load balancer of a gateway farm. Wild-card TLS/SSL certificates don't work.
64
+
- A TLS/SSL certificate to handle HTTPS traffic. The certificate must match the fully qualified domain name (FQDN) of the gateway machine if there's only one machine, or the load balancer of a gateway farm. Wildcard TLS/SSL certificates don't work.
65
65
66
66
- A signing certificate. You can create a signing certificate by using the [Create-SigningCertificate.ps1](https://github.com/Azure/azure-devtestlab/blob/master/samples/DevTestLabs/GatewaySample/tools/Create-SigningCertificate.ps1) PowerShell script.
67
67
@@ -90,15 +90,15 @@ For a sample function, see [CreateToken.cs](https://github.com/Azure/azure-devte
90
90
The [Azure DevTest Labs GitHub repository](https://github.com/Azure/azure-devtestlab) has Azure Resource Manager (ARM) templates that help set up DevTest Labs token authentication and remote desktop gateway resources. There are templates for gateway machine creation, lab settings, and a function app.
91
91
92
92
> [!NOTE]
93
-
> By using the sample templates, you agree to the [Remote Desktop Gateway license terms](https://www.microsoft.com/licensing/product-licensing/products).
93
+
> Use of the sample templates indicates your agreement with the [Remote Desktop Gateway license terms](https://www.microsoft.com/licensing/product-licensing/products).
94
94
95
95
Follow these steps to set up a sample remote desktop gateway farm.
96
96
97
97
1. Create a signing certificate.
98
98
99
-
Run [Create-SigningCertificate.ps1](https://github.com/Azure/azure-devtestlab/blob/master/samples/DevTestLabs/GatewaySample/tools/Create-SigningCertificate.ps1). Record the thumbprint, password, and Base64 encoding of the created certificate to use later.
99
+
Run [Create-SigningCertificate.ps1](https://github.com/Azure/azure-devtestlab/blob/master/samples/DevTestLabs/GatewaySample/tools/Create-SigningCertificate.ps1). Record the thumbprint, password, and Base64 encoding of the new certificate to use later.
100
100
101
-
1. Get a TLS/SSL certificate. The FQDN associated with the TLS/SSL certificate must be for a domain you control.
101
+
1. Get a TLS/SSL certificate. The FQDN associated with the TLS/SSL certificate must be for a domain that you control.
102
102
103
103
1. Record the password, thumbprint, and Base64 encoding for the TLS/SSL certificate to use later.
104
104
@@ -118,24 +118,24 @@ Follow these steps to set up a sample remote desktop gateway farm.
118
118
119
119
1. Download all the files from [https://github.com/Azure/azure-devtestlab/tree/master/samples/DevTestLabs/GatewaySample/arm/gateway](https://github.com/Azure/azure-devtestlab/tree/master/samples/DevTestLabs/GatewaySample/arm/gateway). Copy all the files and *RDGatewayFedAuth.msi* to a blob container in a storage account.
120
120
121
-
1. Open *azuredeploy.json* from [https://github.com/Azure/azure-devtestlab/tree/master/samples/DevTestLabs/GatewaySample/arm/gateway](https://github.com/Azure/azure-devtestlab/tree/master/samples/DevTestLabs/GatewaySample/arm/gateway), and fill out the following parameters:
121
+
1. Open *azuredeploy.json* from [https://github.com/Azure/azure-devtestlab/tree/master/samples/DevTestLabs/GatewaySample/arm/gateway](https://github.com/Azure/azure-devtestlab/tree/master/samples/DevTestLabs/GatewaySample/arm/gateway), and fill in the following parameters:
122
122
123
123
124
-
|Parameter |Required |Description |
124
+
|Parameter |Required? |Description |
125
125
|---------|---------|---------|
126
-
|`adminUsername` |**Required** |Administrator user name for the gateway machines. |
127
-
|`adminPassword` |**Required** |Password for the administrator account for the gateway machines. |
126
+
|`adminUsername` |Required |Administrator user name for the gateway machines. |
127
+
|`adminPassword` |Required |Password for the administrator account for the gateway machines. |
128
128
|`instanceCount` | |Number of gateway machines to create. |
129
-
|`alwaysOn` | |Whether to keep the created Azure Functions app warmed (on) or not. Keeping the app on avoids delays when users first try to connect to their lab VMs, but has cost implications. |
130
-
|`tokenLifetime` | |The length of time in HH:MM:SS format that the created token is valid. |
131
-
|`sslCertificate` |**Required** |The Base64 encoding of the TLS/SSL certificate for the gateway machine. |
132
-
|`sslCertificatePassword` |**Required** |The password of the TLS/SSL certificate for the gateway machine. |
133
-
|`sslCertificateThumbprint` |**Required** |The certificate thumbprint for identification in the local certificate store of the signing certificate. |
134
-
|`signCertificate` |**Required** |The Base64 encoding for the signing certificate for the gateway machine. |
135
-
|`signCertificatePassword` |**Required** |The password for the signing certificate for the gateway machine. |
136
-
|`signCertificateThumbprint` |**Required** |The certificate thumbprint for identification in the local certificate store of the signing certificate. |
137
-
|`_artifactsLocation` |**Required** |The URI location to find artifacts this template requires. This value must be a fully qualified URI, not a relative path. The artifacts include other templates, PowerShell scripts, and the Remote Desktop Gateway Pluggable Authentication module, expected to be named *RDGatewayFedAuth.msi* that supports token authentication. |
138
-
|`_artifactsLocationSasToken`|**Required** |The shared access signature (SAS) token to access artifacts, if the `_artifactsLocation` is an Azure storage account. |
129
+
|`alwaysOn` | |Whether to keep the created Azure Functions app warmed (on). Keeping the app on avoids delays when users first try to connect to their lab VMs, but it has cost implications. |
130
+
|`tokenLifetime` | |The length of time, in HH:MM:SS, format that the created token is valid. |
131
+
|`sslCertificate` |Required |The Base64 encoding of the TLS/SSL certificate for the gateway machine. |
132
+
|`sslCertificatePassword` |Required |The password of the TLS/SSL certificate for the gateway machine. |
133
+
|`sslCertificateThumbprint` |Required |The certificate thumbprint for identification in the local certificate store of the signing certificate. |
134
+
|`signCertificate` |Required|The Base64 encoding for the signing certificate for the gateway machine. |
135
+
|`signCertificatePassword` |Required |The password for the signing certificate for the gateway machine. |
136
+
|`signCertificateThumbprint` |Required |The certificate thumbprint for identification in the local certificate store of the signing certificate. |
137
+
|`_artifactsLocation` |Required |The URI location to find artifacts this template requires. This value must be a fully qualified URI, not a relative path. The artifacts include other templates, PowerShell scripts, and the Remote Desktop Gateway Pluggable Authentication module, expected to be named *RDGatewayFedAuth.msi*, that supports token authentication. |
138
+
|`_artifactsLocationSasToken`|Required|The shared access signature (SAS) token to access artifacts, if the `_artifactsLocation` is an Azure storage account. |
139
139
140
140
1. Run the following Azure CLI command to deploy *azuredeploy.json*:
141
141
@@ -157,51 +157,51 @@ Follow these steps to set up a sample remote desktop gateway farm.
157
157
158
158
1. Configure DNS so that the FQDN of the TLS/SSL certificate directs to the `gatewayIP` IP address.
159
159
160
-
After you create the remote desktop gateway farm and update DNS, configure Azure DevTest Labs to use the gateway.
160
+
After you create the remote desktop gateway farm and update DNS, configure DevTest Labs to use the gateway.
161
161
162
162
## Configure the lab to use token authentication
163
163
164
-
Before you update lab settings, store the key for the authentication token function in the lab's key vault. You can get the function key value on the function's **Function Keys** page in Azure portal. To find the ID of the lab's key vault, run the following Azure CLI command:
164
+
Before you update lab settings, store the key for the authentication token function in the lab's key vault. You can get the function key value on the function's **Function Keys** page in the Azure portal. To find the ID of the lab's key vault, run the following Azure CLI command:
165
165
166
166
```azurecli
167
167
az resource show --name {lab-name} --resource-type 'Microsoft.DevTestLab/labs' --resource-group {lab-resource-group-name} --query properties.vaultName
168
168
```
169
169
170
-
Learn how to save a secret in a key vault in the article,[Add a secret to Key Vault](/azure/key-vault/secrets/quick-create-portal#add-a-secret-to-key-vault). Record the secret name to use later. This value isn't the function key itself, but the name of the key vault secret that holds the function key.
170
+
To learn how to save a secret in a key vault, see[Add a secret to Key Vault](/azure/key-vault/secrets/quick-create-portal#add-a-secret-to-key-vault). Record the secret name to use later. This value isn't the function key itself, but the name of the key vault secret that holds the function key.
171
171
172
-
To configure a lab's **Gateway hostname** and **Gateway token secret** to use token authentication with the gateway machine(s), follow these steps:
172
+
To configure a lab's **Gateway hostname** and **Gateway token secret** to use token authentication with the gateway machine or machines, complete these steps:
173
173
174
-
1. On the lab's **Overview** page, select **Configuration and policies**from the left navigation.
174
+
1. On the lab's **Overview** page, select **Configuration and policies**in the left pane.
175
175
176
-
1. On the **Configuration and policies** page, select **Lab settings** from the **Settings** section of the left navigation.
176
+
1. On the **Configuration and policies** page, select **Lab settings** from the **Settings** section in the left pane.
177
177
178
178
1. In the **Remote desktop** section:
179
179
180
-
-For the **Gateway hostname**field, enter the FQDN or IP address of the remote desktop services gateway machine or farm. This value must match the FQDN of the TLS/SSL certificate used on gateway machines.
180
+
-In the **Gateway hostname**box, enter the FQDN or IP address of the remote desktop services gateway machine or farm. This value must match the FQDN of the TLS/SSL certificate used on gateway machines.
181
181
182
-
-For**Gateway token**, enter the secret name you recorded earlier. This value isn't the function key itself, but the name of the key vault secret that holds the function key.
182
+
-In**Gateway token secret**, enter the secret name you recorded earlier. This value isn't the function key itself, but the name of the key vault secret that holds the function key.
183
183
184
-
184
+
:::image type="content" source="./media/configure-lab-remote-desktop-gateway/remote-desktop-options-in-lab-settings.png" alt-text="Screenshot of remote desktop options in Lab settings." lightbox="./media/configure-lab-remote-desktop-gateway/remote-desktop-options-in-lab-settings.png":::
185
185
186
186
1. Select **Save**.
187
187
188
188
> [!NOTE]
189
-
> By selecting **Save**, you agree to [Remote Desktop Gateway license terms](https://www.microsoft.com/licensing/product-licensing/products).
189
+
> Selecting **Save** indicates that you agree to the[Remote Desktop Gateway license terms](https://www.microsoft.com/licensing/product-licensing/products).
190
190
191
-
Once you configure both the gateway and the lab, the RDP connection file created when the lab user selects **Connect** includes the necessary information to connect to the gateway and use token authentication.
191
+
After you configure both the gateway and the lab, the RDP connection file created when the lab user selects **Connect** includes the necessary information to connect to the gateway and use token authentication.
192
192
193
193
### Automate lab configuration
194
194
195
-
- PowerShell: [Set-DevTestLabGateway.ps1](https://github.com/Azure/azure-devtestlab/blob/master/samples/DevTestLabs/GatewaySample/tools/Set-DevTestLabGateway.ps1) is a sample PowerShell script to automatically set**Gateway hostname** and **Gateway token secret** settings.
195
+
- PowerShell: [Set-DevTestLabGateway.ps1](https://github.com/Azure/azure-devtestlab/blob/master/samples/DevTestLabs/GatewaySample/tools/Set-DevTestLabGateway.ps1) is a sample PowerShell script to automatically configure**Gateway hostname** and **Gateway token secret** settings.
196
196
197
197
- ARM: Use the [Gateway sample ARM templates](https://github.com/Azure/azure-devtestlab/tree/master/samples/DevTestLabs/GatewaySample/arm/lab) in the Azure DevTest Labs GitHub repository to create or update labs with **Gateway hostname** and **Gateway token secret** settings.
198
198
199
199
### Configure a network security group
200
200
201
-
To further secure the lab, add a network security group (NSG) to the virtual network the lab VMs use as described in [Create, change, or delete a network security group](../virtual-network/manage-network-security-group.md). For example, an NSG could allow only traffic that first goes through the gateway to reach lab VMs. The rule source is the IP address of the gateway machine or load balancer for the gateway farm.
201
+
To further secure the lab, add a network security group (NSG) to the virtual network the lab VMs use, as described in [Create, change, or delete a network security group](../virtual-network/manage-network-security-group.md). For example, an NSG could allow only traffic that first goes through the gateway to reach lab VMs. The rule source is the IP address of the gateway machine or load balancer for the gateway farm.
202
202
203
-
203
+
:::image type="content" source="./media/configure-lab-remote-desktop-gateway/network-security-group-rules.png" alt-text="Screenshot of a network security group rule." lightbox="./media/configure-lab-remote-desktop-gateway/network-security-group-rules.png":::
204
204
205
-
## Next steps
205
+
## Related content
206
206
207
207
-[Deploy your remote desktop environment](/windows-server/remote/remote-desktop-services/rds-deploy-infrastructure)
0 commit comments