Getting started with managing NICE DCV sessions secured behind a NICE DCV Connection Gateway

Note: [August 2024 update] The steps in this blog have been automated with the dcv-gw-sm-without-pipelines AWS CDK hosted in dcv-samples.

In this blog, you walk through configuring a NICE DCV Connection Gateway to provide secure access sessions managed by NICE DCV Session Manager.

NICE DCV is a high-performance remote display protocol. DCV provides a secure way to deliver remote desktops and application streaming through a centralized DCV Connection Gateway to any device. This versatile streaming component provides a native desktop end user experience. DCV’s versatility enables the power of Elastic Compute Cloud (EC2) to right-size the compute aligning to your end user’s requirements. When end users reside outside of the corporate network, they need a secure way to access their NICE DCV server session.

A best practice is to protect your end user instances by placing them in a private subnet, unreachable from the public internet. To provide end user’s access to these instances, they must pass through an internet gateway.

Time to read	20 minutes
Time to complete	One hour
Cost to complete	<$10
Learning level	300
Services used	Amazon EC2, NICE DCV

Solution Overview

Architecture diagram illustrating the DCV Connection Gateway in a public subnet proxying sessions to DCV servers in a private subnet. DCV Session manager is used to initiate these connections.

In this blog, you build the environment illustrated in the previous architecture diagram. You configure DCV Session Manager to orchestrate DCV sessions on your backend DCV server fleet. DCV Session Manager acts as broker, exposing API operations to create, modify, and delete DCV sessions at scale. DCV Session Manager also acts as a resolver for the DCV Connection Gateway, verifying that incoming sessions are routed to the correct server. Lastly, DCV Session Manager acts as an external authenticator, which is required when using a DCV Connection Gateway. External authenticators provide an additional layer of protocol security, requiring an authentication token to be validated before DCV servers begin streaming a session.

The DCV Connection Gateway acts as a single point of entry for users to target with their connections. DCV Connection Gateway requires a session ID, and an authentication token. In your configuration, DCV Session Manager acts a session resolver. The DCV Connection Gateway resolves the session ID against DCV Session Manager; illustrated in the following diagram. Once the session is resolved, the DCV Connection Gateway passes the authentication token to the targeted DCV server. The DCV Server validates the token against its configured external authenticator.

Architecture diagram illustrating the DCV Connection Gateway using the session ID to resolve DCV sessions against DCV Session Manager.

Prerequisites

To follow this blog, you need the following:

A Virtual Private Cloud (VPC) with at least one public, and one private subnet to deploy resources in with default DHCP Options set or DNS configured to forward AmazonProvidedDNS.
AWS Identity and Access Management (IAM) permissions to deploy three Amazon EC2 instances.
IAM EC2 role for DCV licensing.
Networking access to the instances that are deployed.
Access to a supported NICE DCV client (download page).
IAM permissions to AWS Systems Manager Session Manager (Systems Manager Session Manager), or SSH client.
An existing Amazon EC2 key pair.

Step 1: Deploy NICE DCV Session Manager

Navigate to the EC2 Console.
Select Launch instance.
(Optional) Name your instance DCV Session Manager.
Select Amazon Linux 2.
- Note that Session Manager supports a variety of Linux distributions.
Use the Architecture dropdown to select 64-bit (Arm). This allows you to use a EC2 Graviton instance family.
For Instance type, choose M6g.large. This aligns to the memory requirement of 8GB for DCV Session Manager.
For Key pair (login), select your key pair from the dropdown.
In the Network settings section, choose the VPC and private subnet for DCV Session Manager to be provisioned in. The subnet you choose must have routing in place so the gateway and DCV servers are reachable.
- Note: you must access this instance via an SSH client, or Systems Manager Session Manager. If you choose to SSH, you must have network access to the instance, and the security group will need to allow TCP connections on port 22 from your IP address. If you use SSM Session Manager, you must meet the SSM Session Manager prerequisites.
Select a security group that provides access to the instance, as well communication between DCV Session Manager, the DCV Connection Gateway, and the DCV servers managed by DCV Session Manager. The inbound TCP ports can be changed, but the default port communication is the following:
- 8443 – Client to broker
- 8445 – Agent to broker
- 8447 – Gateway to broker
- 47100 – Broker to broker
- 47200 – CLI to broker
- 47500 – Broker to broker discovery
For the Configure Storage section, keep the default value of 8GB for gp2 storage.
Expand Advanced details.
Apply your organization requirements that you must apply to EC2 instances. For example, applying an IAM instance profile, or limiting EC2 metadata to V2 calls only (IMDSv2). For DCV products to inherit their license, ensure your instance’s IAM permissions meet the minimum requirement.

In the Advanced details section, copy the following user data into the User data section.

#!/bin/bash
yum update -y 
mkdir /tmp/DCVSM/
cd /tmp/DCVSM/
# Import key, fetch and install the latest package
rpm --import https://d1uj6qtbmh3dt5.cloudfront.net/NICE-GPG-KEY
wget https://d1uj6qtbmh3dt5.cloudfront.net/nice-dcv-session-manager-broker-el7.noarch.rpm
yum install -y ./nice-dcv-session-manager-broker*
# Start and enable service
systemctl start dcv-session-manager-broker.service && systemctl enable dcv-session-manager-broker.service

Select Launch instance.

Step 2: Configure DCV Session Manager

When your instance is available and passing EC2 health checks, configure the DCV Session Manager.

Remotely access the instance via SSH, or Systems Manager Session Manager. Copy the self-signed certificate to your home folder with the following command:
- sudo cp /var/lib/dcvsmbroker/security/dcvsmbroker_ca.pem $HOME
- Note: In this walkthrough, you use DCV Session Manager’s self-signed certificate to encrypt communication. If you must distribute a different certificate from your organization’s certificate authority, review the administration guide on managing the TLS certificate.
Open dcvsmbroker_ca.pem in your preferred text editor. Copy its contents locally. You will need its contents for both DCV server and DCV Connection Gateway.
Open DCV Session Manager’s configuration in your preferred text editor. The configuration can be found at /etc/dcv-session-manager-broker/session-manager-broker.properties.
Set enable-gateway to true.
Uncomment the following two lines.
- gateway-to-broker-connector-https-port = 8447
- gateway-to-broker-connector-bind-host = 0.0.0.0
Save the configuration file.
Restart the broker service with the following command:
- sudo systemctl restart dcv-session-manager-broker.service
To make API calls to your broker, you will need to register an API client. To generate these credentials, run the following command. These credentials cannot be retrieved later so take note of the response.
- sudo -u root dcv-session-manager-broker register-api-client --client-name client_name
Disconnect from your SSH or AWS System Manager Session Manager session.

Step 3: Create a NICE DCV Connection Gateway

In this step, you provision a single gateway. You can scale your gateway and use DNS load balancing to handle all of your inbound sessions.

Navigate to the EC2 Console.
Select Launch instance.
(Optional) Name your instance DCV Connection Gateway.
Select Amazon Linux 2 as the instance’s AMI.
Use the Architecture dropdown to select 64-bit (Arm).
For instance type, select a C7g.large, from the C7g instance family. You can monitor historical CloudWatch metrics to get insights on right-sizing your instance for your workload. The more DCV features your end users use, the more resources your DCV Connection Gateway will require.
For Key pair (login), select your key pair from the dropdown.
In the Network settings section, choose the VPC and subnet for the DCV Connection Gateway.
- Note: you must have direct access to the gateway to establish connections to the DCV servers. If the end users are initiating connections from the internet, you must have an internet gateway.
Select a security group. This security group provides streaming access to the instance, and also communication between the gateway, DCV Session Manager, and the DCV servers. The default configuration binds to port 8443: this can be changed.
Within the Configure Storage section, select the default value of 8GB.
Expand Advanced details.
(optional) Apply your organization requirements that you must apply to EC2 instances. For example, applying an IAM instance profile, or limiting EC2 metadata to V2 calls only (IMDSv2).

In the Advanced details section, copy the following user data into the User data section.

There are two placeholders that you must replace:

CERT-PLACEHOLDER – replace this with the contents of dcvsmbroker_ca.pem that you retrieved in the previous step. This starts with “—–BEGIN CERTIFICATE—–”.
BROKER-PRIVATE-DNS – replace this with the private DNS name of your DCV Session Manager. The private DNS name of your DCV is shown in Instance details in the EC2 console.

User data

#!/bin/bash
yum update -y
mkdir /tmp/DCVGW/
cd /tmp/DCVGW/
rpm --import https://d1uj6qtbmh3dt5.cloudfront.net/NICE-GPG-KEY
wget https://d1uj6qtbmh3dt5.cloudfront.net/nice-dcv-connection-gateway-el7.aarch64.rpm
yum install -y ./nice-dcv-connection-gateway*
echo 'CERT-PLACEHOLDER' > /etc/dcv-connection-gateway/dcvsmbroker_ca.pem
chmod 400 /etc/dcv-connection-gateway/dcvsmbroker_ca.pem
chown dcvcgw /etc/dcv-connection-gateway/dcvsmbroker_ca.pem
echo '[gateway]
quic-listen-endpoints = ["0.0.0.0", "::"]
quic-port = 8443
web-listen-endpoints = ["0.0.0.0", "::"]
web-port = 8443
#[health-check]            # Enable Health Check Service (Optional)
#bind-addr = "::"
[dcv]
tls-strict = false
[resolver]
url = "https://BROKER-PRIVATE-DNS:8447"
ca-file="/etc/dcv-connection-gateway/dcvsmbroker_ca.pem"
[web-resources]
url = "https://localhost:8080"' > /etc/dcv-connection-gateway/dcv-connection-gateway.conf
systemctl start dcv-connection-gateway.service && systemctl enable dcv-connection-gateway.service
systemctl restart dcv-connection-gateway.service

13. Select Launch instance.

Step 4: Configure your DCV Fleet

In this step, you configure a DCV server to connect to. For this walkthrough, you create a Windows-based DCV server. However, the DCV server and the Session Manager Agent support a variety of operating system types. The user data provided in this step configures the Windows Server to have all the requirements to be accessed via the DCV Gateway. In also enables the QUIC transport protocol for a more fluid user experience.

Deploying a Windows DCV Server

Navigate to the EC2 Console.
Select Launch instance.
(Optional) Name your instance DCV Windows Fleet.
Select a Windows-based image.
For Instance type, choose an appropriate instance type for testing.
- Note that the resources allocated for this instance will be the resources used by the end user.
For Key pair (login), select your key pair from the dropdown.
In the Network settings section, choose the VPC and private subnet you to deploy the DCV Server in.
- Note that since you are using a DCV Gateway, the DCV server does not need to be internet facing.
Select a security group that allows communication between the gateway, DCV Session Manager, and the DCV server. The default TCP ports are 8443 for streaming, and 8445 for DCV Session Manager to agent communication. QUIC uses 8443 UDP.
Configure your desired storage.

Expand Advanced details. After applying your specific requirements, copy the following user data into the User data section. There are two placeholders that you must replace in script for the DCV Session Manager agent configuration.

BROKER-IP-PLACEHOLDER – replace this entry with the private IP address of your DCV Session Manager.
- Note that there are two entries for this placeholder.
CERT-PLACEHOLDER – replace this with the contents of the dcvsmbroker_ca.pem you retrieved in a previous step. This should start with “—–BEGIN CERTIFICATE—–”.

<powershell>
Start-Job -Name WebReq -ScriptBlock { Invoke-WebRequest -uri https://d1uj6qtbmh3dt5.cloudfront.net/nice-dcv-virtual-display-x64-Release.msi -OutFile C:\Windows\Temp\DCVDisplayDriver.msi ; Invoke-WebRequest -uri https://d1uj6qtbmh3dt5.cloudfront.net/nice-dcv-server-x64-Release.msi -OutFile C:\Windows\Temp\DCVServer.msi ; Invoke-WebRequest -uri https://d1uj6qtbmh3dt5.cloudfront.net/nice-dcv-session-manager-agent-x64-Release.msi -OutFile C:\Windows\Temp\SMInstaller.msi }
Wait-Job -Name WebReq
Invoke-Command -ScriptBlock {Start-Process "msiexec.exe" -ArgumentList "/I C:\Windows\Temp\DCVDisplayDriver.msi /quiet /norestart" -Wait}
Invoke-Command -ScriptBlock {Start-Process "msiexec.exe" -ArgumentList "/I C:\Windows\Temp\DCVServer.msi ADDLOCAL=ALL /quiet /norestart /l*v dcv_install_msi.log " -Wait}
Invoke-Command -ScriptBlock {Start-Process "msiexec.exe" -ArgumentList "/I C:\Windows\Temp\SMInstaller.msi /quiet" -Wait}
New-PSDrive -Name SessionMgrReg -PSProvider Registry -Root HKU\S-1-5-18 
Set-location SessionMgrReg:
New-ItemProperty -Path Software\GSettings\com\nicesoftware\dcv\connectivity -Name enable-quic-frontend -PropertyType DWORD -Value 1 -force
New-ItemProperty -Path Software\GSettings\com\nicesoftware\dcv\security -Name authentication -PropertyType string -Value none -force
New-ItemProperty -Path Software\GSettings\com\nicesoftware\dcv\security -Name auth-token-verifier -PropertyType string -Value https://BROKER-IP-PLACEHOLDER:8445/agent/validate-authentication-token -force
New-ItemProperty -Path Software\GSettings\com\nicesoftware\dcv\security -Name ca-file -PropertyType string -Value "C:\Program Files\NICE\DCVSessionManagerAgent\dcvsmbroker_ca.pem" -force
New-ItemProperty -Path Software\GSettings\com\nicesoftware\dcv\session-management -Name create-session -PropertyType DWORD -Value 0 -force
Set-Location C:
Remove-PSDrive SessionMgrReg
$pemFile = "CERT-PLACEHOLDER"
$pemFile | Out-File -FilePath "C:\Program Files\NICE\DCVSessionManagerAgent\dcvsmbroker_ca.pem" -Encoding ASCII
$SMAgentConf = "version = '0.1'
# Agent parameter documentation can be found here:
# https://docs.thinkwithwp.com/dcv/latest/sm-admin/agent-file.html
[agent]
# hostname or IP of the broker. This parameter is mandatory.
broker_host = `'BROKER-IP-PLACEHOLDER`'
# The port of the broker. Default: 8445
#broker_port =
# CA used to validate the certificate of the broker.
ca_file = 'C:\Program Files\NICE\DCVSessionManagerAgent\dcvsmbroker_ca.pem'
# Set to false to accept invalid certificates. True by default.
#tls_strict = false
[log]
"
$SMAgentConf | Out-File -FilePath "C:\Program Files\NICE\DCVSessionManagerAgent\conf\agent.conf" -Encoding utf8 -force
Set-Service -Name dcvserver -StartupType Automatic
Start-Service -Name dcvserver
Set-Service -Name DcvSessionManagerAgentService -StartupType Automatic
Start-Service -Name DcvSessionManagerAgentService
Restart-Service DcvSessionManagerAgentService
Restart-Service dcvserver
</powershell>

Select Launch instance.

Step 5: Testing your configuration

Now that your infrastructure is created, you must create a session for you to connect to. For this step, you use the DCV Session Manager CLI. You can install the CLI anywhere that has access to DCV Session Manager. The following instructions guide you through installing the CLI on the DCV Session Manager, as shown in illustrated in the diagram following.

Architecture diagram illustrating the DCV Session Manager CLI creating a DCV session and retrieving the user's auth token against the DCV Session Manager.

Installing and using the CLI

Access your DCV Session Manager instance using SSH, or Systems Manager Session Manager.
Install the DCV Session Manager CLI.
Configure the CLI to reflect the linked configuration.
- Broker port is 8443.
- Comment out ca-bundle with a ‘#’.
  - #ca-bundle = ca-bundle.pem
- Client-id and client-password should reflect the response you got from the register client API call you recorded when configuring DCV Session Manager in step 2.
- Comment out auth-server-url, it is not needed for this walkthrough.
- In the [broker] section, you will need to point to DCV Session Manager. It will look like the following with you instance specific information.
  - url = https://DCVSessionManager-DNS-or-IP:8443
From the command line, change to the CLI directory.
Test your CLI install by running the following command. This returns the Windows Server instance you deployed in the previous step.
- python3 dcvsm describe-servers
Run the following command to have DCV Session Manager create a DCV session on the DCV Server you deployed. Take note of the session ID in the call response.
- Note that the default Windows local user is Administrator and the password can be retrieved in the console.
- python3 dcvsm create-session --name session123 --owner localUser --type Console --requirements "server:Host.Os.Family = 'windows'"
Run the following command to retrieve the DCV session’s authentication token specific to the connecting user. Take note of the token in the response.
- python3 dcvsm get-session-connection-data --session-id session-id --user localUser
- Take note the connection_token in the response.
You can initiate a connection from a DCV client using the session ID and authentication code. The connection string should be formatted as:
- Connection-Gateway-IP-Or-DNS:8443/?authToken=Token-Placeholder#SessionID-Placeholder
- Note you must initiate the call from a DCV client. If you would like to enable web access, review the administration guide for configuring web resources.
Once your connection is established, log in to your Windows Server with the instance credentials.

Cleanup

To clean up the environment, terminate the three EC2 instances; DCV Session Manager, DCV Connection Gateway, and DCV server respectively.

Conclusion

In this blog, you deployed a DCV architecture proof of concept. You configured a DCV Session Manager, a DCV Connection Gateway, and a DCV server. You also went through the process of generating your connection information using the DCV Session Manager CLI and connecting with a DCV client.

As a next step, you can build from this architecture to meet your business requirements for production use can connect to DCV sessions at scale. To make this configuration ready for production, account for the following items:

High Availability:
- Both DCV Session Manager and DCV Connection Gateway must be scaled across Availability Zones.
Enterprise Security:
- In a production scenario, it is recommended to distribute a certificate from your enterprise certificate authority.

Creating an end user portal is out of scope for this blog, but it can be accomplished using same DCV Session Manager calls within a web-based portal. For more information on how to make these calls in a web-based portal scenario, see the SDK documentation.

Desktop and Application Streaming