# What is Amazon DCV Access Console?
What is Amazon DCV Access Console?

**Note**  
Amazon DCV was previously known as NICE DCV.

The Amazon DCV Access Console is a web application that helps administrators and end users manage their Amazon DCV sessions. The Access Console consists of installable software packages that include a Handler, an Authentication Server, and a Web Client configured to provide a graphical interface.

The Access Console provides administrators with the following:
+ Access to the Amazon DCV Session Manager APIs
+ The ability to monitor the host servers running their sessions
+ Tools to manage the users who have access to the console

The Access Console provides end users a way to connect, manage, and launch their own Amazon DCV sessions.

**Topics**
+ [

## How Amazon DCV Access Console works
](#how)
+ [

## Features
](#features)
+ [

## Limitations
](#limitations)
+ [

## Pricing
](#pricing)
+ [Requirements](requirements.md)
+ [

# Authentication methods
](console-authentication.md)
+ [

# Datastore
](datastore.md)
+ [

# Certificates
](certificates.md)
+ [

# Networking and connectivity
](networking-connectivity.md)
+ [

# Open source code
](open-source.md)

## How Amazon DCV Access Console works


The following system architecture diagram shows the high-level components of the Amazon DCV Access Console and how they work with each other.

![\[Amazon DCV Access Console components and how they work with each other.\]](http://docs.aws.amazon.com/dcv/latest/access-console/images/access-console-diagram.png)


Handler  
The *Handler* is an application that helps connect to and manage Amazon DCV sessions by communicating with the *Session Manager Broker* using the *Session Manager APIs*.

Authentication Server  
The *Authentication Server* is responsible for authenticating users using Header based or PAM authentication methods.

Web Client  
The client is the front-end web application you setup to interact with the *Handler* (and in turn with the *Session Manager Broker*). It renders the relevant web pages and serves to the *Web Browser*.

Session Manager Broker  
The *Broker* is a web server that hosts and exposes the Session Manager APIs. It receives and processes *API* requests to manage Amazon DCV sessions from the *client*, and then passes the instructions to the relevant *Agents*. The Broker must be installed on a host that's separate from your Amazon DCV servers. It must also be accessible to the client, and be able to access the Agents.

## Features


Amazon DCV Access Console offers the following features:
+ **Provides Amazon DCV session information**–get information about the sessions running on multiple Amazon DCV servers.
+ **Manage the lifecycle for multiple Amazon DCV sessions**–create or delete multiple sessions for multiple users across multiple Amazon DCV servers with one API request.
+ **Supports tags**–use custom tags to target a group of Amazon DCV servers when creating sessions.
+ **Manages permissions for multiple Amazon DCV sessions**–modify user permissions for multiple sessions with one API request.
+ **Provides connection information**–retrieve client connection information for Amazon DCV sessions.
+ **Supports for cloud and on-premises**–use Session Manager on AWS, on-premises, or with alternative cloud-based servers.

## Limitations


Amazon DCV Access Console does not provide resource provisioning capabilities. If you are running Amazon DCV on Amazon EC2 instances, you might need to use additional AWS services, such as Amazon EC2 Auto Scaling to manage the scaling of your infrastructure.

## Pricing


Amazon DCV Access Console is available at no cost for AWS customers running EC2 instances.

On-premises customers require a Amazon DCV Plus or Amazon DCV Professional Plus license. For information about how to purchase a Amazon DCV Plus or Amazon DCV Professional Plus license, see [How to Buy](https://www.nice-software.com/index.html#buy) on the Amazon DCV website. You can also use the website to find an Amazon DCV distributor or reseller in your region. Licensing requirements will only be enforced starting with Amazon DCV version 2021.0,so that all on-premises customers can experiment with the Amazon DCV Access Console.

For more information, see [ Licensing the Amazon DCV Server](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-license.html) in the *Amazon DCV Administrator Guide*.

# Requirements
Requirements

The Amazon DCV Access Console has the following requirements.


|  | Authentication Server | Handler | Web Client | 
| --- | --- | --- | --- | 
|  **Operating system**  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/dcv/latest/access-console/requirements.html)  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/dcv/latest/access-console/requirements.html)  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/dcv/latest/access-console/requirements.html)  | 
|  **Browser**  |  N/A  |  N/A  |  Latest Chrome Browser  | 
|  **Architecture**  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/dcv/latest/access-console/requirements.html)  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/dcv/latest/access-console/requirements.html)  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/dcv/latest/access-console/requirements.html)  | 
|  **Memory**  |  4 GB  |  4 GB  |  4 GB  | 
|  **Additional requirements**  |  Java 17  |  Java 17, DynamoDB/MariaDB/MySQL  |  Node 18, NGNIX  | 

# Authentication methods


The Authentication Server for the Amazon DCV Access Console can be setup to use either Pluggable Authentication Modules (PAM), HTTP Header authentication, or external OAuth providers. Utilizing PAM authentication allows you to inherit your existing Linux authentication model. HTTP Header authentication provides a customizable authentication mechanism to perform additional validation before the end user reaches the authentication server. External OAuth providers, such as AWS Cognito, allow you to leverage managed identity services for user authentication and management.

## PAM authentication


The authentication server can be setup to use PAM authentication, it validates the username and the password using the PAM method of the operating system on the host running the authentication server. 

**Enabling PAM authentication**

1. Connect to the host that is running the authentication server.

1. Open `/etc/dcv-access-console-auth-server/access-console-auth-server.properties` with your preferred editor.

1. Comment out or remove the `authentication-header-name` property to disable header based authentication if it is present.

1. Set the `pam-helper-path to the full path of the dcvpamhelper` that is installed as part of the authentication server. By default this is `/usr/share/dcv-access-console-auth-server/dcvpamhelper`.

1. Set the `pam-service-name` to the name of the file in `/etc/pam.d` that should be used to authenticate users.
   + To use the host’s authentication for Redhat based operating systems, set the `pam-service-name` property to `system-auth`.
   + To use the host’s authentication for Ubuntu/Debian based operating systems, set the `pam-service-name` to `common-auth`.

1. If the host uses different format of the username that are mapped to the same user in the operating system with the same uid and gid, set the `pam-normalize-userid-enabled` to true in order to normalize the username.

   The userid is normalized using the command specified in `pam-normalize-userid-command`, by default it runs `id -u -nr` for each username and uses the output of the command as the userid.

1. Restart the authentication server.

   ```
   sudo systemctl restart dcv-access-console-auth-server
   ```

## HTTP Header authentication


The Amazon DCV Access Console can be setup to use the HTTP header in the request to the Authentication Server to authenticate a user. The Authentication Server checks for the configured header name in the request and uses the value of the header as the user id.

This method is useful when there is an intermediary identity provider between the Web Client and the Authentication Server. The intermediary solution authenticates the user and forwards the request with the configured HTTP header. For example, the authentication server can be setup behind a load balancer which uses an Amazon Incognito user pool to validate the user.

**Note**  
It is important that the intermediary solution removes the configured header name from the requests from the web browser so that users cannot bypass the authentication solution.

**Configuring HTTP header authentication**

1. Connect to the host that is running the authentication server.

1. Open `/etc/dcv-session-manager-ui-auth-server/session-manager-auth-server.properties` with your preferred editor.

1. Disable PAM based authentication if it is present, by commenting out or removing the `pam-helper-path` property.

1. Set the `authentication-header-name` to the header name in the request and use the value of the header as the userid.

1. Restart the authentication server.

   ```
   sudo systemctl restart dcv-access-console-auth-server
   ```

## External authentication with AWS Cognito


The Amazon DCV Access Console can be configured to use external OAuth providers for authentication. The following shows how to configure AWS Cognito as an OAuth provider.

**Setting up AWS Cognito for external oAuth**

1. Go to AWS Cognito on the AWS Management Console > User pools > Create user pool

1. Set up resources for your application and Create user directory:
   + Define your application- Traditional web application
   + Configure options as you like
   + Add a return URL: `<web-client-url>/api/auth/callback/<NEXT_PUBLIC_SM_UI_AUTH_ID>`. For example, using defaults for a locally running server: `http://localhost:3000/api/auth/callback/dcv-access-console-auth-server`
   + Once the user pool is created, you can configure Allowed sign-out URLs: Applications > App clients > Login pages > Managed login pages configuration > Edit

1. Adding users to the user pool:
   + Go to User management > Users and add users
   + Alternatively, if you have allowed self-registration in step 2, users may sign up themselves

1. Preparing access-console-handler.properties:
   + Copy the User pool ID from the user pool Overview page and set `jwt-issuer-uri` as `https://cognito-idp.<region>.amazonaws.com/<user_pool_id>`
   + Set the following properties:
     + `jwt-login-username-claim-key` is the key for the login username claim key
     + `jwt-display-name-claim-key` is the key for the display name claim key
     + `auth-server-well-known-uri` is the well known URI (required only if userInfo endpoint is not provided) in the format `https://cognito-idp.<region>.amazonaws.com/<user_pool_id>/.well-known/openid-configuration`
     + `auth-server-userinfo-endpoint` is the userInfo endpoint
   + Restart the handler: `sudo systemctl restart dcv-access-console-handler`
   + Confirm that the service is running: `sudo systemctl status dcv-access-console-handler`
   + To get service logs: `sudo journalctl -u dcv-access-console-handler`

1. Preparing the web client:
   + `/etc/dcv-access-console-web-client/access-console-web-client.properties`:
     + Set `auth-server-well-known-uri` in the format `https://cognito-idp.<region>.amazonaws.com/<user_pool_id>/.well-known/openid-configuration`
   + `/etc/dcv-access-console-web-client/access-console-web-client-secrets.properties`:
     + Set the `auth-server-client-id` and `auth-server-client-secret` values as the Client ID and Client secret values of the user pool App client you set up in step 2 above (Applications > App clients > Select your App client name > App client information)
   + Restart the web client: `sudo systemctl restart dcv-access-console-web-client`
   + Confirm that the service is running: `sudo systemctl status dcv-access-console-web-client`
   + To get service logs: `sudo journalctl -u dcv-access-console-web-client`

# Datastore


Amazon DCV Access Console persists user data, group data, session templates and the permission data related to them through integrations with external databases. It supports DynamoDB, MariaDB, and MySQL databases. You must set up and manage one of these databases to use Amazon DCV Access Console. If your Amazon DCV Access Console machines are hosted on Amazon EC2, we recommend using DynamoDB as the external database, since it does not require any additional setup.

**Note**  
Additional costs can happen when running an external database. To see information on DynamoDB pricing, see [Pricing for Provisioned Capacity]( https://aws.amazon.com/dynamodb/pricing/provisioned/).

**Configure the Amazon DCV Access Console to persist on DynamoDB**

1. On the host running the Handler component, open `/etc/dcv-access-console-handler/access-console-handler.properties` in your preferred editor and make the following edits:
   + Set `datastore = dynamodb`.
   + For `dynamodb-region` specify the AWS Region where you want to store the tables containing the Handler component data. For the list of supported Regions, see DynamoDB service endpoints.
   + For `datastore.prefix` specify the prefix that is added to each DynamoDB table (useful to distinguish multiple Handler component using the same account). Only alphanumeric characters, dot, dash, and underscore are allowed.

1. Stop the Handler component.

   ```
   sudo systemctl stop dcv-access-console-handler
   ```

1. Start the Handler component.

   ```
   sudo systemctl start dcv-access-console-handler
   ```

   The Handler component host must have permission to call the DynamoDB APIs. On Amazon EC2 instances, the credentials are automatically retrieved using the Amazon EC2 metadata service. If you need to specify different credentials, you can set them using one of the supported credential retrieval techniques (such as Java system properties or environment variables). For more information, see Supplying and Retrieving AWS Credentials.

**Configure the broker to persist on MariaDB/MySQL**

1. On the host running the Handler component, open `/etc/dcv-access-console-handler/access-console-handler.properties` in your preferred editor and make the following edits:
   + Set `datastore = mysql`.
   + Set `jdbc-connection-url = jdbc:mysql://db_endpoint:db_port/db_name`

     In this configuration, *db\$1endpoint* is the database endpoint, *db\$1port* is the database port, and *db\$1name* is the database name.
   + For `datastore.prefix` specify the prefix that is added to each DynamoDB table (useful to distinguish multiple Handler component using the same account). Only alphanumeric characters, dot, dash, and underscore are allowed.

1. On the host running the Handler component, open `/etc/dcv-access-console-handler/access-console-handler-secrets.properties` in your preferred editor and make the following edits:
   + For `jdbc-user` specify the name of the user that has access to the database.
   + For `jdbc-password` specify the password of the user that has access to the database.

1. Stop the Handler component.

   ```
   sudo systemctl stop dcv-access-console-handler
   ```

1. Start the Handler component.

   ```
   sudo systemctl start dcv-access-console-handler
   ```
**Note**  
The `/etc/dcv-access-console-handler/access-console-handler-secrets.properties` file contains sensitive data. By default, its write access is restricted to root and its read access is restricted to root and to the user running the Handler component. By default, this is the `dcvaccessconsole` user. 

# Certificates


In order to provide a HTTPS connection between the different components, a SSL certificate is required for each of the hosts. Customers are recommend to use their own manager certificates on each of the host. For non-production workloads, a self-signed SSL certificate can be used. For more information on creating a self-signed cert see [Generating a self-signed certificate](generate-certs.md).

See instructions below on how to configure the different Amazon DCV Access Console components to use certificates.

**Authentication Server**

1. Connect to the host that is running the Authentication Server.

1. Open `/etc/dcv-access-console-auth-server/access-console-auth-server-secrets.properties` with your preferred editor and update the following properties:
   + `server.ssl.key-store-type` – Set to `PKCS12`.
   + `server.ssl.key-store` – Set to path of the JKS keystore.
   + `server.ssl.enabled` – Set to true.
   + `server.ssl.key-store-password` – Set to key store password.

1. Restart the Authentication Server service.

   ```
   sudo systemctl restart dcv-access-console-auth-server
   ```

**Handler**

1. Connect to the host that is running the Handler

1. Open `/etc/dcv-access-console-handler/access-console-handler-secrets.properties` with your preferred editor and update the following properties:
   + `server.ssl.key-store-type` – Set to `PKCS12`.
   + `server.ssl.key-store` – Set to path of the JKS key store.
   + `server.ssl.enabled` – Set to true.
   + `server.ssl.key-store-password` – Set to key store password.

1. Restart the Handler service.

   ```
   sudo systemctl restart dcv-access-console-handler
   ```

**Web Client/NGNIX**

1. Connect to the host that is running NGNIX.

1. Open `/etc/nginx/conf.d/dcv-access-console.conf` with your preferred editor and update the following properties:
   + `ssl_certificate` – Set to path to the certificate for the host.
   + `ssl_certificate_key` – Set to path to the key for the certificate.

1. Restart the NGNIX service.

   ```
   sudo systemctl restart ngnix
   ```

# Networking and connectivity


The Amazon DCV Access Console components can all be installed on a single host or on different hosts.

## Single host setup


In a single host setup, the Authentication Server, the Handler component and the Web Client are all installed on a single host. An NGINX server can be used to proxy requests from the web browser to the appropriate component. The web browser should be able to initiate secure, persistent, bi-directional HTTPS connections with NGNIX. All the components need bi-directional HTTP connection between each other on the configured port (see table below). In addition, the Handler component needs to be able to initiate secure, persistent, bi-directional HTTPS connections with the Broker and the persistence store (DynamoDB or MariabDB/MySQL).


| Component | Default Port | 
| --- | --- | 
|  Authentication Server  |  3000  | 
|  Handler  |  8080  | 
|  Web Client  |  9000  | 

## Multiple host setup


In multiple host setup, the Authentication Server, the Handler component and the Web Client can be all installed on different servers. An NGNIX server can be used to proxy requests from the web browser to the Web Client and establish a HTTPS between them. The Authentication Server and the Handler can be configured to accept HTTPS connections. All the components need bi-directional HTTPs connection between them on port 443. In addition, the Handler component needs to be able to initiate secure, persistent, bi-directional HTTPs connections with the Broker and the persistence store (DynamoDB or MariabDB/MySQL).

# Open source code


 The Amazon DCV Access Console consists of installable software packages that include a Handler, an Authentication Server, a Web Client, and a Setup Wizard configured to provide a graphical interface for the Amazon DCV Session Manager broker. The Access Console is available as a packaged commercial build on the [Amazon DCV downloads page](https://www.amazondcv.com/) and as separate open sourced components on [GitHub](https://github.com/aws/dcv-access-console). You may consider using these open source components if you want to customize the Access Console in ways not available with the commercial build to meet your unique use cases. 

Other Amazon DCV products listed and available on the DCV downloads page, like the Amazon DCV Session Manager and the Amazon DCV clients, are not open sourced. If you choose to customize the Access Console using the open sourced Access Console components, the customized Access Console may be used in combination with the other DCV products as described below in the Licensing section. 

## Licensing


The Access Console code repositories stored on GitHub are open source and licensed under the Apache 2.0 License. The Access Console commercial build and other Amazon DCV products listed and available on our Amazon DCV downloads page are proprietary and licensed under the [DCV EULA](https://www.amazondcv.com/eula.html). If you use the open sourced Access Console components, but not the proprietary Amazon DCV products, in a custom Access Console build, the customized Access Console is governed by the Apache 2.0 License. If you use the open sourced Access Console components in any combination that includes the proprietary Amazon DCV products (i.e., Amazon DCV Session Manager, Amazon DCV Clients, or other product listed on the Amazon DCV downloads page), the combination is governed by the DCV EULA. 

## Contributing


As a customer, you have the ability to contribute back to the open source repository. Follow the CONTRIBUTING instructions available on the GitHub repository for further instruction.