Install the HTML5 Gateway for PSM

This topic describes how to install the HTML5 gateway for PSM.

Installation mode

You can install the HTML5 gateway for PSM and the Alero connector Docker containers side-by-side on the same host or standalone on separate hosts. Each mode of installation has its own considerations.

Standalone

  • More efficient resource and performance consumption.

  • The HTML5 gateway for PSM is available for any connections from the PVWA, not only those from Alero.

  • To use copy files capabilities with multiple standalone HTML5 gateways for PSM, configure the Load Balancer with sticky sessions so that all requests for a particular user session are routed through the same HTML5 gateway for PSM.

For details about installing a standalone HTML5 gateway for PSM, see Install PSM HTML5 Gateway via Docker in the Privileged Access Security docs.

Side-by-side

  • Minimal on-prem customer footprint

  • The HTML5 gateway for PSM is only be accessible via Alero-initated sessions.

  • Copy files capabilities are not available if you have more than one host with the Alero connector and HTML5 gateway for PSM installed.

  • Can be installed on an Ubuntu 18.04 host.

For details about installing a side-by-side HTML5 gateway for PSM, continue below.

System requirements

Software specifications

  • Red Hat Linux 7.x for standalone installation

  • Ubuntu 18.04 or Red Hat Linux 7.x for side-by-side installation with the Alero connector

  • Docker engine

Hardware specifications

Small + mid-range implementations
(1-50 concurrent RDP/SSH sessions)

Mid-range + large implementations
(51-100 concurrent RDP/SSH sessions)

Very large implementations
(101-200 concurrent RDP/SSH sessions)

  • 2 core processors (Intel compatible)
  • 4 GB RAM
  • 15 GB disk space*
  • 4 core processors (Intel compatible)
  • 8 GB RAM
  • 15 GB disk space*
  • 8 core processors (Intel compatible)
  • 16 GB RAM
  • 15 GB disk space*

 

* To use 'Copy files' functionality, the host machine must have enough free disk space to hold the files that are transferred to the target for the duration of the session. For more details, see Copy files.

Pre-installation considerations

Installation

This section describes how to install the PSM HTML5 gateway.

Download and run the preliminary setup script

  1. Download and unpack the PSM HTML5 Gateway Scripts package from the 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
  5. To continue installing the HTML5 gateway for PSM, continue deployment as explained in the relevant section below:

    Side by side

    Standalone

 

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.

Side by side

The PSM HTML5 gateway must use an SSL certificate to provide secure communication. You can choose whether to create an SSL certificate automatically when the container starts, or to import an existing certificate.

Standalone

The PSM HTML5 gateway must use an SSL certificate to provide secure communication. You can choose whether to create an SSL certificate automatically when the container starts, or to import an existing certificate.

Disable JWT Validation

JWT Validation is a security measure that is being developed and will be available soon. Currently, it must be disabled.

  • In the Docker run command, add the following parameter:

     
    -e EnableJWTValidation=no

Validate the PSM remote certificate

The PSM HTML5 gateway in the Docker image is preconfigured to use TLS to establish secured communication with PSM. It is highly recommended to supply a certificate file that allows it to verify PSM's certificate, such as the certificate of the signing CA.

  1. Place the certificate file of the CA that signed the PSM's certificate in a directory on the host machine. For example, in /opt/cert.

    If the PSM certificate is signed by an intermediate CA, the file must be in PEM format and contain all CA certificates in the chain concatenated one after the other.

  2. To import the certificate into the PSM HTML5 gateway, use the -e PSMCAFile option when running the PSM HTML5 gateway container.

    Option

    Description

    -e PSMCAFile

    The name of the .crt file that contains the certificate of the CA that signed the PSM certificate.

    Specify -e PSMCAFile=<PSM CA certificate filename>.

    Specify either this option or -e IgnorePSMCertificateErrors.

    -e IgnorePSMCertificateErrors

    Ignore PSM certificate errors.

    Specify -e IgnorePSMCertificateErrors=yes.

    Specify either this option or -e PSMCAFile.

     

    This must not be used in production deployments.

Hardening

  • When the Alero connector and the HTML5 Gateway for PSM are installed side-by-side on the same host machine, the Alero connector hardening is used to protect both components. For more details, see Hardening.

  • To harden the HTML5 Gateway for PSM installed on its own host machine, see Harden a standalone PSM HTML5 gateway.

Post-installation configuration

After installation, configure the PSM HTML5 gateway. For details, see Secure Access with a PSM 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 PSM 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 the PSM HTML5 gateway server.

Upgrade

To upgrade the PSM HTML5 gateway, do the following:

  1. Stop the running PSM HTML5 gateway container:

     
    sudo docker kill <container name>

    For example:

     
    sudo docker kill psmgw.com
  1. Delete the PSM HTML5 gateway container from the local Docker system:

     
    sudo docker rm <container name>

    For example:

     
    sudo docker rm psmgw.com
  1. Download the latest image, as described in Download and run the preliminary setup script.

  1. Run a new PSM HTML5 gateway instance, as described in Install the HTML5 Gateway for PSM.

     

    To keep using the original certificate, skip the steps in Prepare a certificate for the PSM HTML5 gateway.