# Use External Authentication


By default, Amazon DCV client authentication is delegated to the underlying operating system. With Windows Amazon DCV servers, authentication is delegated to WinLogon. With Linux and macOS Amazon DCV servers, authentication is delegated to Linux PAM.

You can configure Amazon DCV to use an external authentication server to authenticate clients. This enables you to use an existing authentication system. With external authentication, Amazon DCV leverages your existing login mechanisms and delegates authentication to an external authentication server. 

The external authentication validates a user with DCV server access to enable usage of session creation. It will not authenticate your user against the underlying OS like **system** authentication does, unless you setup your own external authenticator to do so.

[DCV Session Manager](https://docs.aws.amazon.com/dcv/latest/sm-admin/what-is-sm.html) comes with an external authenticator built in. To use this feature, your DCV servers will need to set the [auth-token-verifier](https://docs.aws.amazon.com/dcv/latest/sm-admin/configure-dcv-server.html) parameter with the Session Manager address.

In order to use an external authentication server, you must have the following in place:
+ **A login mechanism**—This is the front-end mechanism that your users use to log in. It should be able to verify your users by using your existing credentials verification system and it should be able to generate a token and provide it to the Amazon DCV server. For more information, see [Using the Token](#using-token).
+ **An authentication server**—This is the server that authenticates the token generated by the login mechanism. This server should be able to receive an HTTP(S) POST request from the Amazon DCV server that includes the token, perform the necessary authentications, and then send the response back to the Amazon DCV server. For more information about implementing an authentication server, see [Authentication service requirements](#configure-authenticator).
+ **Amazon DCV Server configuration**—The Amazon DCV server must be configured to use an external authentication server. For more information, see [Amazon DCV Server Configuration](#configure-server).

**Topics**
+ [

## Amazon DCV Server Configuration
](#configure-server)
+ [

## Using the Token
](#using-token)
+ [

## Authentication service requirements
](#configure-authenticator)

## Amazon DCV Server Configuration


You must configure the Amazon DCV server to use the external authentication service.

------
#### [ Windows Amazon DCV server ]

**To specify an external authentication server on Windows**

1. Open the Windows Registry Editor.

1. Navigate to the **HKEY\$1USERS\$1S-1-5-18\$1Software\$1GSettings\$1com\$1nicesoftware\$1dcv\$1** key.

1. Locate the **auth-token-verifier** parameter in the [security Parameters](config-param-ref.md#security).

1. Do one of the following:
   + For **Value data**, enter the URL of the external authentication server and the port over which to communicate, in the following format: `url:port`.  
**Example**  

     For example, if you're using the DcvSimpleExternalAuthenticator, specify the following: `http://127.0.0.1:8444`.
   + If there is no **auth-token-verifier** parameter in the security section, add it in the PowerShell. Refer to [ Modifying Configuration Parameters](https://docs.aws.amazon.com/dcv/latest/adminguide/config-param-ref-modify.html).

1. Close the Windows Registry Editor.

1. [Stop](manage-stop.md) and [restart](manage-start.md) the Amazon DCV server.

------
#### [ Linux Amazon DCV server ]

**To specify an external authentication server on Linux**

1. Navigate to `/etc/dcv/` and open the `dcv.conf` with your preferred text editor.

1. Locate the `auth-token-verifier` parameter in the `[security]` section, and replace the existing value with the URL of the external authentication server and the port over which to communicate, in the following format: `url:port`. For example, if you're using the DcvSimpleExternalAuthenticator, specify the following: `http://127.0.0.1:8444`.

   If there is no `auth-token-verifier` parameter in the `[security]` section, add it manually using the following format:

   ```
   [security] auth-token-verifier=url:port
   ```

1. Save and close the file.

------
#### [ macOS Amazon DCV server ]

**To specify an external authentication server on macOS**

1. Navigate to `/etc/dcv/` and open the `dcv.conf` with your preferred text editor.

1. Locate the `auth-token-verifier` parameter in the `[security]` section, and replace the existing value with the URL of the external authentication server and the port over which to communicate, in the following format: `url:port`. For example, if you're using the DcvSimpleExternalAuthenticator, specify the following: `http://127.0.0.1:8444`.

   If there is no `auth-token-verifier` parameter in the `[security]` section, add it manually using the following format:

   ```
   [security] auth-token-verifier=url:port
   ```

1. Save and close the file.

------

## Using the Token


Once you have generated the token, you must be able to send it to the Amazon DCV server. With the web browser client, append the token to the connection URL as follows:

```
https://server_hostname_or_IP:port/?authToken=token#session_id
```

For example:

```
https://my-dcv-server.com:8443/?authToken=1234567890abcdef#my-session
```

## Authentication service requirements


Your custom authentication service can run on the same host of the Amazon DCV server or it can run on a separate host. The authentication service must listen for HTTP(S) POST requests from the Amazon DCV server.

The following shows the POST request format used by the Amazon DCV server.

```
POST / HTTP/1.1
Content-Type: application/x-www-form-urlencoded
sessionId=session_id&authenticationToken=token&clientAddress=client_address
```

Your authentication service is responsible for determining whether the supplied token is valid.

After the token is validated, the authentication server must return the response to the Amazon DCV server. The response body must include one of the following, depending on the outcome of the authentication process:
+ If authentication is successful, the authentication service returns a result of `yes` and a user identifier. For example:

  ```
  <auth result="yes"><username>username</username></auth>
  ```
+ If authentication is unsuccessful, the authentication service returns a result of `no`. For example:

  ```
  <auth result="no"><message>message</message></auth>
  ```

### DcvSimpleExternalAuthenticator


Amazon DCV ships with a reference external authentication server called, `DcvSimpleExternalAuthenticator`. DcvSimpleExternalAuthenticator is a single Python script that you can use a starting point for creating your own custom authentication server.

DcvSimpleExternalAuthenticator server supports HTTP and HTTPS, and it must run on the same server on which the Amazon DCV server is installed. By default, the DcvSimpleExternalAuthenticator listens for requests on port `8444`. You can change the port, if needed. To do this, open `/etc/dcv/simpleextauth.conf` with your preferred text editor, locate the `EXTAUTH_PORT` parameter, and replace the existing value with the required port number.

To use DcvSimpleExternalAuthenticator, you must install the `nice-dcv-simple-external-authenticator` package. For more information, see [Install the Amazon DCV Server](setting-up-installing-linux-server.md#linux-server-install).

### Using the Simple External Authenticator




1. Navigate to your authentication directory.

   `sudo mkdir -p /var/run/dcvsimpleextauth`

1. Generate your authentication token.  
**Example**  

   In this example, `123456` is the sample authenticator token, `session-123` is the sample session ID, and `username` is the user.

   `echo "123456" | sudo dcvsimpleextauth add-user --session session-123 --auth-dir /var/run/dcvsimpleextauth/ --user username --append` 

1. Start up your server.

   `sudo dcvsimpleextauth --port 8444 --auth-dir /var/run/dcvsimpleextauth/ start-server`

1. Once the server is running, test the configuration for validation.  
**Example**  

   Once again, using this example, the test would run like this:

   `curl -k http://localhost:8444 -d sessionId=session-123 -d authenticationToken=123456`

   If successful, you will receive a authentication result of `yes`.