Use External Authentication - Amazon DCV
Amazon DCV Server ConfigurationUsing the TokenAuthentication service requirements

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 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 comes with an external authenticator built in. To use this feature, your DCV servers will need to set the auth-token-verifier 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.

  • 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.

  • 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.

Amazon DCV Server Configuration

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

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.

  2. 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

  3. Save and close the file.

Windows Amazon DCV server
To specify an external authentication server on Windows

  1. Open the Windows Registry Editor.

  2. Navigate to the HKEY_USERS/S-1-5-18/Software/GSettings/com/nicesoftware/dcv/ key.

  3. Locate the auth-token-verifier parameter in the security Parameters.

  4. 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.

      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.

  5. Close the Windows Registry Editor.

  6. Stop and restart the Amazon DCV server.

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.

Using the Simple External Authenticator

  1. Navigate to your authentication directory.

    sudo mkdir -p /var/run/dcvsimpleextauth

  2. Generate your authentication token.

    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

  3. Start up your server.

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

  4. Once the server is running, test the configuration for validation.

    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.