v13.0.1 and higher - Install PSM HTML5 Gateway using a container manager

This topic describes how to install the PSM HTML5 gateway via Docker or Podman.

Software prerequisites

Docker - Red Hat Enterprise Linux 7.x versions or Ubuntu 20.x or 22.x versions
Podman - Red Hat Enterprise Linux 8.x versions

Install the HTML5 Gateway

This section describes how to install the PSM HTML5 Gateway.

Download HTML5 Gateway from the CyberArk Marketplace and copy the HTML5 Gateway-Rls-v13.0.1.zip\PSMGWDocker directory to the Linux host.
Go to that directory.

Run the following command to grant execution rights to the setup script.

chmod +x html5_console.sh

Run the following command to execute the setup script

sudo ./html5_console.sh install -l

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
```

Launch the HTML5 Gateway container

Map a directory for certificates and related files

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

sudo mkdir /opt/cert

Place the following items in this directory to import them to the trusted store of the HTML5 Gateway docker:

the .der or .pem certificate of the CA that signed the PSM certificate, or the PSM self-signed certificate
the .der or .pem certificate of the CA that signed the PVWA certificate

These certificates are required because the Docker image is preconfigured 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.

If the PSM or JWT validation endpoints are signed by a CA chain, place all intermediate CA certificates in the mapped directory.
Using a self signed certificate is not recommended and should only be used for testing purposes.

Run the container

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

sudo ./html5_console.sh run -ti -p 443:8443 -v <certificates directory>:/opt/import:ro -d -e AcceptCyberArkEULA=yes -e EndPointAddress=https://<PVWA URL> --hostname <container name> --name <container name> cahtml5gw:<version_tag>

Where:

The values of the --name option and the --hostname option in this command must be identical.
The value of <version_tag> is the specific version of the cahtml5gw image.

To find the version, run sudo docker images or sudo podman images and replace <version_tag> with the value under TAG.
JWT Validation is a security layer that ensures only authenticated sessions to HTML5 Gateway are allowed. It is enabled by default and requires you to enter EndPointAddress and import the certificate of the CA that signed the end point (PVWA) certificate, which you placed in the mapped directory for certiticates in the previous step). For details, see JWT validation.

For example:

sudo ./html5_console.sh run -ti -p 443:8443 -v /opt/cert/:/opt/import:ro -d -e AcceptCyberArkEULA=yes -e EndPointAddress=https://<PVWA hostname>/passwordvault --hostname <PSM gateway FQDN> --name <PSM gateway FQDN> cahtml5gw:11_06_0_8

This command uses the following options:

Option	Description	Default Value
-e AcceptCyberArkEULA	Accept Cyberark EULA	no
-e EnableFileTransfer	Support file transfer	yes
-e PSMGWAppLogLevel	Set the Web app log level Supported values: debug, info, warning, error, info	info
-e PSMGWGuacLogLevel	Set the guac log level Supported values: debug, info, warning, error, info	info
-e EnableJWTValidation	Enable or disable JWT validation to authenticate the requests to the HTML5 gateway For details, see JWT validation	yes
-e EndPointAddress	The address of the API that generates the token for JWT validation. For example, https://<PVWA hostname>/passwordvault If EnableJWTValidation=no, there is no need to add this option to the command For details, see JWT validation
-e ServerKeyboardLayout	Supported values: 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 ca-psm-unicode failsafe For details, see Keyboard layouts	en-us-qwerty
-e GWCert	The name of the .crt file that contains the PSM HTML5 gateway certificate, for use when you import a Gateway certificate For details, see Run the container with an imported SSL certificate
-e GWKey	The name of the .key file that contains the PSM HTML5 gateway private key For details, see Run the container with an imported SSL certificate
-e GWCAFile	The name of the .crt file that contains the certificate of the CA that signed the PSM HTML5 gateway certificate For details, see Run the container with an imported SSL certificate
-e IgnorePSMCertificateErrors	Ignore PSM certificate errors Note: This option must not be used in production deployments	no
-e EnableCORS	Whether to enable or disable Cross Origin Resource Sharing. Once enabled, the following headers are added: Access-Control-Allow-Origin - The origin of the request. If AllowedOrigins is not set to ALL, the origin is only added if it exists on the allowed origins list. Access-Control-Allow-Methods= POST, GET, OPTIONS Access-Control-Allow-Credentials = true Access-Control-Max-Age = 3600 Access-Control-Allow-Headers = x-requested-with, x-ca66666, content-type, accept, authorization	no
-e EnableFontSmoothing	Text over RDP is rendered with rough edges by default, as this reduces the number of colors used by the text, reducing the bandwidth required for the connection. To improve session quality you can set -e EnableFontSmoothing=yes to have text rendered with smooth edges.	no
-e TCPAckTimeout	The maximum time in milliseconds that the HTML5 gateway waits for the first connection response from PSM. This improves tolerance in environments with network latency. Accepted values: 1 – 59000	9000
-e MaxClipboardSize	The maximum capacity in bytes for the clipboard area in the HTML5 gateway that is allocated for each session for copy-paste operations between the client and target. When this value is left blank, the internal clipboard capacity is applied.	blank

Run the container with an imported SSL certificate

Prepare a certificate for the PSM HTML5 gateway.

Use an existing certificate within your organization or create a new certificate.

Use an existing PSM HTML5 gateway certificate from your organization

Place the following items in the directory you created in step 1:

Certificate to use as the PSM HTML5 gateway certificate, as a .crt file
Private key that matches the PSM HTML5 gateway remote certificate's public key, as a .key file

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.

Create a new PSM HTML5 gateway certificate

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

Create a key file for the signing root CA:

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

For example:

sudo openssl genrsa -out /opt/cert/rootCA.key 4096

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

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

For example:

sudo openssl genrsa -aes256 -out /opt/cert/rootCA.key 4096

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

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>

For example:

sudo openssl req -x509 -new -nodes -key /opt/cert/rootCA.key -sha256 -days 1024 -out /opt/cert/rootCA.crt

At the prompt, enter any requested information.

If the root CA private key is password protected, you will be prompted for the password.

The Common Name field is mandatory.

Create the PSM HTML5 gateway private key:

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

For example:

sudo openssl genrsa -out /opt/cert/psmgw.key 2048

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

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

For example:

sudo openssl genrsa -aes256 -out /opt/cert/psmgw.key 2048

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

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>

For example:

sudo openssl req -new -key /opt/cert/psmgw.key -out /opt/cert/psmgw.csr

At the prompt, enter any requested information.

If the PSM HTML5 gateway private key is password protected, you will be 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.

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

For example:

sudo openssl x509 -req -in /opt/cert/psmgw.csr -CA /opt/cert/rootCA.crt -CAkey /opt/cert/rootCA.key -CAcreateserial -out /opt/cert/psmgw.crt -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 -p 443:8443 -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> -e EndPointAddress=<PVWA url> --name <common name> cahtml5gw:<version_tag>

Where:

The values of the --name option and the --hostname option in this command must be identical.
The value of <version_tag> is the specific version of the cahtml5gw image.

To find the version, run sudo docker images or sudo podman images and replace <version_tag> with the value under TAG.
JWT Validation is a security layer that ensures only authenticated sessions to HTML5 Gateway are allowed. It is enabled by default and requires you to enter EndPointAddress and import the certificate of the CA that signed the end point (PVWA) certificate, which you placed in the mapped directory for certiticates in the previous step). For details, see JWT validation.

For example:

sudo ./html5_console.sh run -ti -d -p 443:8443 -v /opt/cert/:/opt/import:ro -e AcceptCyberArkEULA=yes -e GWCert=psmgw.crt -e GWKey=psmgw.key -e GWCAFile=rootCA.crt -e EndPointAddress=https://<PVWA hostname>/passwordvault --name <PSM gateway FQDN> cahtml5gw:11_06_0_8 -e

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, as shown below.

sudo ./html5_console.sh run -ti -p 443:8443 -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> -e EndPointAddress=<PVWA url> --name <common name> cahtml5gw:<version_tag>

For example:

sudo ./html5_console.sh run -ti -p 443:8443 -v /opt/cert/:/opt/import:ro -e AcceptCyberArkEULA=yes -e GWCert=psmgw.crt -e GWKey=psmgw.key -e GWCAFile=rootCA.crt -e EndPointAddress=https://<PVWA hostname>/passwordvault --name <PSM gateway FQDN> cahtml5gw:11_06_0_8 -e

Enter the private key password when prompted.

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

This command uses the following options:

Option	Description
-e GWCert	The name of the .crt file that contains the PSM HTML5 gateway certificate.
-e GWKey	The name of the .key file that contains the PSM HTML5 gateway private key.
-e GWCAFile	The name of the .crt file that contains the certificate of the CA that signed the PSM HTML5 gateway certificate.

Hardening

Harden the host machine by executing the following command:

Red Hat 7:

sudo sh RHEL7-CIS/harden.sh

Red Hat 8:

sudo sh RHEL8-CIS/harden.sh

Ubuntu 20:

sudo bash UBUNTU20-CIS/harden.sh

Ubuntu 22:

sudo bash UBUNTU22-CIS/harden.sh

Restart the machine. This is required after hardening.

After hardening, the root account does not have PermitRootLogin rights and therefore cannot log in using SSH.

Post-installation configuration

After installation, configure the HTML5 Gateway. For details, see Secure Access with an HTML5 Gateway.

Load balancing

The PSM HTML5 gateway can be load balanced as you would load balance any other web server (or the PVWA).

You can deploy farms of HTML5 gateway servers behind a load balancer. Then when adding a configured PSM Gateway server, use the relevant farm's Virtual IP (VIP) in the Address parameter. For details, see Add PSM HTML5 Gateway server.

In deployments where multiple connectors point to the same load-balanced URL, and multiple HTML5 gateways are behind this URL, the HTML5 copy files capability works if the Load Balancer has been configured with sticky sessions so that all requests for a particular user session are routed through the same HTML5 gateway.

You can perform a health check on the servers. For details, see Health Check.

Upgrade the PSM HTML5 Gateway

For details, see Using a container manager.