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 or podman.

 

BY RUNNING PSM HTML5 GATEWAY DOCKER OR PODMAN 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.

  • For installations on Red Hat 7.x, you need to use a docker engine

  • For installations on Red Hat 8.x, you need to use a podman engine

The procedures in this topic are relevant for both docker and podman.

For more details, see System requirements

  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_console.sh

  4. Execute the script by running the following command:

    sudo ./html5_console.sh install

     

    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_console.sh install -f

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

    sudo ./html5_console.sh install -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 ./html5_console.sh run -ti -d -v <certificates directory>:/opt/import:ro -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.

Place the following items in the directory you created in Map a directory for certificates and related files, above.

  • A certificate to use as the PSM HTML5 gateway certificate, as a .crt file

  • A private key that matches the PSM HTML5 gateway remote certificate's public key, as a .key file

  • A certificate of the signing root CA, as a .crt file

 

If the certificate is signed by a CA chain and not just by a root CA, the CA certificate file must contain the entire chain and must be in PEM (Base64) format. To create the CA certificate file with the entire chain, concatenate the certificates into a combined file, starting from the inner CA with the root CA last.

You can create a new certificate to use as the remote certificate for the PSM HTML5 gateway.

  1. Create a key file for the signing root CA:

      
    sudo openssl genrsa -out <CA .key file output path> 4096

    Alternatively, to make the key password protected, add the -aes256 option:

      
    sudo openssl genrsa -aes256 -out <CA .key file output path> 4096

    Enter and verify the root CA private key password at the prompt.

  2. Create and self-sign the certificate for the root CA:
     
    sudo openssl req -x509 -new -nodes -key <CA .key file path> -sha256 -days 1024 -out <CA .crt file output path>

  3. At the prompt, enter any requested information.
    If the root CA private key is password protected, you are prompted for the password.

     

    The Common Name field is mandatory.

  4. Create the PSM HTML5 gateway private key:

      
    sudo openssl genrsa -out <Gateway .key file output path> 2048

    Alternatively, to make the key password protected, add the -aes256 option:

      
    sudo openssl genrsa -aes256 -out <Gateway .key file output path> 2048

    Enter and verify the PSM HTML5 gateway private key password at the prompt.

  5. Create the certificate signing request for the PSM HTML5 gateway:

      
    sudo openssl req -new -key <Gateway .key file path> -out <Gateway .csr file output path>

  6. At the prompt, enter any requested information.
    If the PSM HTML5 gateway private key is password protected, you are prompted for the password.

     

    The Common Name field is mandatory and its value must be different from the one created for the root CA certificate earlier.

  7. Generate the HTML gateway certificate:

      
    sudo openssl x509 -req -in <Gateway .csr file output path> -CA <CA .crt file path> -CAKey <CA .key file path> -CAcreateserial -out <Gateway .crt file output path> -days 1024 -sha256

    If the root CA private key is password protected, enter the password when prompted.

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 ./html5_console.sh run -ti -d -v <certificates directory>:/opt/import:ro -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 <container 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