Secure Access with an HTML5 Gateway

This topic describes how to configure PSM to work through an HTML5 gateway. PSM HTML5 Gateway allows the users browser-based access to PSM sessions via HTML5 instead of the native RDP-based access.

Configure the PVWA

The following procedure describes how to configure the PVWA to work with the HTML5 Gateway server.

Select one of the following options to work with HTML5:

You can use HTML5 sessions exclusively.

  1. Log in to the PVWA with an administrative user.

  2. Go to Options > Privileged Session Management UI.

  3. Set DefaultConnectionMethod to HTML5.


HTML5 sessions are triggered only for PSM machines associated with HTML5 Gateway.

You can use a single account for both RDP file and HTML5-based sessions


This option is only available in the Version 10 interface.

The use of shared privileged accounts often means that the same account is used by both an external third-party vendor and an internal privileged employee. While the external vendor's access is frequently through an HTML5 browser-based session, the internal employee may prefer to connect with an RDP-file based session.

Users can use either an HTML5-based or RDP-file connection method when connecting to the remote server.

Set the default connection method to the most common method used in the PAS environment.

  1. Log in to the PVWA with an administrative user.

  2. Go to Options > Privileged Session Management UI.

  3. Set DefaultConnectionMethod to either RDP or HTML5. The default value is RDP.

The following procedure describes how to configure the PVWA so that users can select either method.

Perform this procedure for every connection component for which both connection methods should be available.

  1. Log in to the PVWA with an administrative user.

  2. Go to Options > Connection Components > {Connection Component} > User Parameters

  3. Add AllowSelectHTML5. For details, refer to Connection Components.

    1. Ensure Visible is set to Yes.

    2. Set Type to CyberArk.TransparentConnection.BooleanUserParameter, CyberArk.PasswordVault.TransparentConnection.


When the AllowSelectHTML5 user parameter is configured on the connection component level, the default value is set according to the AllowSelectHTML5 parameter value.

You can configure a single PSM to enable connectors to use one of the following methods when connecting to the remote server:

  • RDP-file
  • HTML5 Gateway

Set HTML5 as the default connection method:

  1. Log in to the PVWA with an administrative user.

  2. Go to Options > Privileged Session Management UI.

  3. Set DefaultConnectionMethod to HTML5.

Configure a single PSM to set the connection method:

  1. Duplicate the PSM server and give a unique name to the new server. For example, duplicate the PSMServer_RDP server and call the new server PSMServer_HTML5.

  2. On the new server, add and enable the PSM HTML5 Gateway, as described in Add PSM HTML5 Gateway server and Configure the PSM server to use the HTML5 gateway.

  3. Connect all platforms that will use the HTML5 Gateway or that will enable the user to select the connection method to the new server.


For platforms that enable the user to select the connection method, you can configure the connection components as described in Single account for RDP/HTML5.

Gateway configuration

This section describes how to configure the Gateway.

JWT validation

JWT validation is a security layer that ensures that only authenticated sessions are allowed via HTML5 Gateway. When a user establishes an HTML5 connection through PVWA, the HTTP response includes JWT, which is used by HTML5 Gateway to validate the HTTP request by the client. When validation fails the connection is not established.


  • Vault 11.5 or higher
  • PVWA 11.5 or higher
  • HTML5 Gateway 11.6 or higher


Keyboard layouts

The HTML5 gateway supports the keyboard layouts listed above in the description of the ServerKeyboardLayout parameter.

You can also set the keyboard layout in the PVWA:

  1. Log in to the PVWA with an administrative user.

  2. Go to Options > Privileged Session Management > Configured PSM Gateway Servers.

  3. Right-click the relevant Gateway server and select Add server settings.

  4. Enter the KeyboardLayout parameter to set the type of keyboard layout to implement in HTML5 sessions. The values are the same as the ServerKeyboardLayout parameter.

    • If this parameter is not valued, the keyboard layout value is taken from ServerKeyboardLayout.

    • This parameter is only supported for PSM HTML5 gateway version 12.0 or higher.

Configure a non-default keyboard layout

The default keyboard layout value is en-us-qwerty.

There are three possible non-default keyboard layout values:

  1. In environments with one of the following keyboard layouts, value ServerKeyboardLayout or KeyboardLayout with that layout:

    • fr-fr-azerty
    • fr-be-azerty
    • fr-ch-qwertz
    • de-ch-qwertz
    • de-de-qwertz
    • en-us-qwerty
    • en-gb-qwerty
    • hu-hu-qwertz
    • it-it-qwerty
    • ja-jp-qwerty
    • pt-br-qwerty
    • es-es-qwerty
    • es-latam-qwerty
    • sv-se-qwerty
    • tr-tr-qwerty

    For RDP sessions, align the keyboard layout on the target machine. For all other sessions, align the keyboard layout on the PSM machine.

  2. In an environment with keyboard layouts not included in the above list, or in an environment with targets and PSM machines that use different keyboard layouts, set the keyboard layout value to failsafe. This option sends only unicode events and does not support any key combinations that include letters.


    This option should work for any keyboard, though not necessarily all RDP servers or applications.

  3. If the targets and PSM machines in your environment use different keyboard layouts, but all layouts are en-us-qwerty, fr-fr-azerty, or de-de-qwertz, you can set the keyboard layout value to ca-psm-unicode. This option is based on unicode, but supports the following key combinations:

Configure universal keystrokes audit for PSM-RDP sessions

By default, PSM-RDP is configured with WindowsEventsAudit. To work with KeystrokesAudit, you must configure it instead of WindowsEventsAudit. For details, see Configure universal keystrokes text recording and universal keystrokes auditing.

For PSM-RDP sessions with the non-default ServerKeyboardLayout value, set WindowsKeystrokesSingleLanguage=No to work with universal keystrokes audit. For details, see Configure universal keystrokes for Windows connections when an additional language is used.

Logs when you install using an RPM package

Logs are provided for the webapp and the daemon service.

Logs when you install via a container

Logs are generated for the PSM HTML5 gateway web application and the guacd daemon service.


The following error codes are displayed in the HTML5 connection tab when the end-user fails to establish a connection. The end-user sees the error message code, and you can use this table to troubleshoot the issue:

Error message

Possible cause



An issue in the HTML5 security layer.

The session was not authenticated during the JWT flow.

  • Ensure that the PVWA endpoint for JWT validation is correct

  • Ensure that the certificate of the CA that signed the PVWA was imported correctly (required for PSMGW to trust the PVWA)

  • JWT token expired or invalid for some other reason


Websocket connection cannot be established - TLS handshake

Verify the HTML5 Gateway certificate. Refer to Run the container with an imported SSL certificate


PSMGW is reachable, but busy/unavailable

  • Try again later

  • Check tomcat service status

  • Restart tomcat





PSM is unreachable


Guacd is down


Check PSM logs and status


Check guacd service status - Run the service guacd status command



Failed to connect to PSM

  • Check the PSM status or logs

  • Check the HMTL5 gateway logs for possible reasons for the RDP connection failure

    • If the Failed connecting to RDP server message appears along with a Certificate validation failed error, check the PSM CA certificate

    • Otherwise, this is a TLS/network issue:

      • Check the traffic between the HTML5 gateway and PSM

      • Run the HTML5 gateway task with a higher debug level

      • Check the TLS configuration on the PSM side to verify that it allows TLS communication


Unexpected error code or bad error page redirection




If the PSMGW session tab is closed immediately after establishing the session, either PSM or guacd crashed or experienced an unexpected error. Check the PSM and guacd logs and status.