Install the HTML5 Gateway for PSM (side-by-side)

This topic describes how to install the HTML5 gateway for PSM using side-by-side installation mode.

Download and run the preliminary setup script

This section describes how to install the PSM HTML5 gateway on Docker.

 

BY RUNNING PSM HTML5 GATEWAY DOCKER CONTAINER OR OTHERWISE USING THE SOFTWARE, YOU AGREE TO THE TERMS AND CONDITIONS OF THE SOFTWARE LICENSE AGREEMENT. IF YOU DO NOT AGREE TO THIS AGREEMENT, DO NOT INDICATE CONSENT ELECTRONICALLY AND MAKE NO FURTHER USE OF THE SOFTWARE.

  1. Download and unpack the PSM HTML5 gateway scripts package from CyberArk Marketplace.

  2. Copy the unpacked contents of this package to the Linux machine.

  3. Grant execution permissions for the script by running the following command:

     
    chmod +x html5_installation.sh
  4. Execute the script by running the following command:

    sudo ./html5_installation.sh

     

    If there are users or groups that already exist on the host machine, the installation will stop for security purposes.

    To remove and replace the users and groups with the relevant IDs, run the installation script again with the -f flag

    sudo ./html5_installation.sh -f

    To view the help, run the installation script with the -h flag:

    sudo ./html5_installation.sh -h
  5. During the installation you are prompted for the docker password. You can find this password in the Install connector wizard in the Remote Access portal.

    To continue installing the HTML5 gateway for PSM, continue deployment as explained in the relevant section below.

Map a directory for certificates and related files

The following certificates are required because the Docker image is pre-configured to use TLS to establish a secure communication with certificate validation to PSM. Communication to PVWA as part of JWT validation also uses TLS with certificate validation.

  1. On the host machine, create a directory for certificates and related files. For example:

     
    sudo mkdir /opt/cert
  2. Copy the following files into this directory:

    • The .der or .pem certificate of the CA that signed the PSM certificate, or the PSM certificate itself if it is self-signed.

    • The .der or .pem certificate of the CA that signed the PVWA certificate.

     

    If the PSM or JWT validation endpoints are signed by a CA chain, place all intermediate CA certificates in the mapped directory.

    For more details, see JWT validation in the Privileged Access Management docs.

Deploy PSM HTML5 gateway docker container

Use the following template to create a command that deploys the PSM HTML5 gateway for Remote Access:

 
sudo docker run --restart unless-stopped -ti -d -v <certificates directory>:/opt/import:ro --cap-drop=all  --cap-add={CHOWN,DAC_OVERRIDE,FOWNER,SETGID,SETUID} -e AcceptCyberArkEULA=yes --net=cyberark --hostname <container name> --name <container name> docker.io/alerocyberark/psmhtml5
 
  • The values of --name and --hostname options in this command must be identical.

  • Replace <container name> with a container name that is resolvable within the internal network to the host machine that runs the HTML5 gateway container.

By default, an SSL certificate is automatically created to secure inside container communication.

If you choose to use the automatic certificate, skip the next section, and go directly to Docker command options to view details about mandatory and optional parameters.

If you choose to import your own certificate, continue below.

(Optional) Run the container with an imported SSL certificate

Import your own certificate, or create a new PSM HTML5 gateway certificate.

Launch a PSM HTML5 gateway instance

Use the following command to run a PSM HTML5 gateway container instance with the prepared certificate.

When you set the --name option, specify the server certificate common name.

 
sudo docker run --restart unless-stopped -ti -d -v <certificates directory>:/opt/import:ro --cap-drop=all --cap-add={CHOWN,DAC_OVERRIDE,FOWNER,SETGID,SETUID} -e AcceptCyberArkEULA=yes -e GWCert=<Gateway certificate .crt filename> -e GWKey=<Gateway private key .key filename> -e GWCAFile=<Gateway certificate signing CA .crt filename> --net=cyberark --name <common name> docker.io/alerocyberark/psmhtml5

 

If you use a password protected private key, you must run the container in interactive mode and enter the password when prompted. To run the container in interactive mode, omit the -d option.

  • Enter the private key password when prompted.

  • To return to the host machine shell, press Ctrl-P-Q on your keyboard.

Docker command options

The Docker run command accepts the following options:

 

The Docker command options need to prefaced with -e in the docker run commands.

Option

Description

AcceptCyberArkEULA

Accepts the Cyberark EULA from the user.

Mandatory: Yes

Default value: No

EnableJWTValidation

Enables validation of connections via the PSM HTML5 gateway, based on a JWT generated earlier.

Default value: Yes

Min PVWA version: 11.5

Min Vault version: 11.5

To change the default value, add this parameter manually.

EndPointAddress

Sets the HTTPS endpoint of the JWT validation host.

Set this value to https://<PVWA hostname>/passwordvault

If EnableJWTValidation is set to no, leave this parameter blank.

Mandatory: Yes

Default value: Blank

Min PVWA version: 11.5

Min Vault version: 11.5

EnableFileTransfer

Enables file transfer via the PSM HTML5 gateway.

Default value: Yes

Min PVWA version: 11.2

EnableCORS

Enables the PSM to accept HTTP requests from a different domain than the original request.

Set this command to no to support PSM gateway connections from PVWA v10 interface in PVWA versions earlier than 11.2.

Default value: Yes

Min PVWA version: 11.2 for the new PVWA interface (v10 and later), or any version for the classic PVWA interface.

MaxClipboardSize

The maximum capacity in bytes for the clipboard area in PSM gateway that is allocated for each session for copy-paste operations between the client and target.

When this value is left blank, the internally configured maximum clipboard capacity is applied.

Default value: Blank

PSMGWAppLogLevel

Sets the minimum level of written log messages for the PSM HTML5 gateway web application.

Valid values: debug, info, warning, error

Default value: info

PSMGWGuacLogLevel

Sets the minimum level of written log messages for the PSM HTML5 gateway backend service (guacd)

Valid values: debug, info, warning, error

Default value: info

IgnorePSMCertificateErrors

Allows a connection via the PSM HTML5 gateway to proceed, even if validation of the PSM certificate fails.

Default value: No

This parameter is not for use in production environments.

ServerKeyboardLayout

Defines the expected keyboard layout on the target Windows server for PSM-RDP connections, or the PSM for non PSM-RDP connections, for correct key mapping.

Default value: en-us-qwerty

For a full list of valid values, see Keyboard layouts.

GWCert

The name of the PSM HTML5 gateway server certificate file, without the path. The file must appear in the mapped directory.

For more information, see (Optional) Run the container with an imported SSL certificate .

Default value: Blank

GWKey

The name of the PSM HTML5 gateway server private key file, without the path. The file must appear in the mapped directory.

For more information, see (Optional) Run the container with an imported SSL certificate .

Default value: Blank

GWCAFile

The name of the PSM HTML5 gateway server certificate signing authority file without the path. The file must appear in the mapped directory.

For more information, see (Optional) Run the container with an imported SSL certificate .

Default value: Blank