Install PSM HTML5 Gateway using an RPM package

This topic describes how to install the PSM HTML5 gateway using an RPM package.

Software prerequisites

Red Hat Enterprise Linux 7.x versions, and CentOS 7.x versions

Required libraries:

• libpng

• libjpeg

• libcairo

• OpenSSL v1.0.x

• Java

• Java Developer

The libraries must be installed with yum:

yum install cairo libpng libjpeg java java-devel openssl

Install the HTML5 Gateway

This section describes how to install the PSM HTML5 Gateway.

1. Deploy the HTML Webapp

   This step describes how to deploy an HTML Webapp on the server.

   We describe deploying the Tomcat web service.

   1. Download Tomcat

      We recommend deploying Tomcat manually. The yum repository does not always contain the latest Tomcat version. The PSM HTML5 Gateway supports Tomcat v.8.5 or v.9.

   2. Set CATALINA_HOME to be the root folder for Tomcat.

      In the examples below, we use /opt/tomcat as the root folder.

      All scripts assume that /opt/tomcat is the root folder. If you use a different root folder, you must change these scripts.

      export CATALINA_HOME=/opt/tomcat

   3. Run the following commands to configure Tomcat to run as a low privileged user/group

      1. Create a new group called tomcat:

         groupadd tomcat

      2. Create a new tomcat user with a home directory of /opt/tomcat and a group of tomcat:

         useradd -M -s /bin/nologin -g tomcat -d $CATALINA_HOME tomcat

      3. Extract the contents of the Tomcat archive that you downloaded to /opt and rename apache-tomcat-<version> to tomcat.

         cd /opt   tar -xvf apache-tomcat-<version>.tar.gz   mv apache-tomcat-<version> tomcat

      4. Set up ownership:

         chown -R tomcat:tomcat $CATALINA_HOME

      5. Set permissions for the Tomcat server configuration file:

         chmod 600 $CATALINA_HOME/conf/server.xml

      6. Set up the Tomcat service script in RHEL 7.x:

         1. In the /etc/systemd/system folder, create the tomcat.service script:

            [Unit] Description=Apache Tomcat Web Application Container After=syslog.target network.target [Service] Type=forking Environment=JAVA_HOME=/usr/lib/jvm/jre Environment=CATALINA_PID=/opt/tomcat/temp/tomcat.pid Environment=CATALINA_HOME=/opt/tomcat Environment=CATALINA_BASE=/opt/tomcat Environment='CATALINA_OPTS=-Xms128M -Xmx765M -server -XX:+UseParallelGC' Environment='JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom' ExecStart=/opt/tomcat/bin/startup.sh ExecStop=/bin/kill -15 $MAINPID User=tomcat Group=tomcat [Install] WantedBy=multi-user.target*

         2. Set the script permissions:

            chmod +x /etc/systemd/system/tomcat.service   chown root:root /etc/systemd/system/tomcat.service

         3. Start the Tomcat service and enable it to start on boot:

            systemctl daemon-reload   systemctl start tomcat   systemctl enable tomcat

   4. Secure the connection between the end user and Tomcat

      1. Generate a new keystore:

         The keystore is used for the SSL configuration. You can place it in a folder of your choice.

         Self-signed certificate

         Using a self signed certificate is not recommended and should only be used for testing purposes.

         1. Run the following command:

            keytool -genkey -alias <keystore name> -keyalg RSA -keystore <output keystore> -ext san=dns:<PSM gateway FQDN>

            keytool -genkey -alias psmgw -keyalg RSA -keystore /opt/tomcat/keystore -ext san=dns:<PSM gateway FQDN>

         2. At the prompt, enter the keystore password and other requested information

         3. Accept using the same password.

         4. Generate a self-signed certificate and PEM file by running the following command:

            openssl req -x509 -nodes -days 365 -newkey rsa:4096 -keyout <PEM file output path> -out <crt file output path>

            For example:

            openssl req -x509 -nodes -days 365 -newkey rsa:4096 -keyout /opt/tomcat/key.pem -out /opt/tomcat/cert.crt

            When prompted, provide the requested information.

         Organization's certificate

         Use your organization's pfx file to generate the keystore:

         1. Run the following command:

            keytool –importkeystore –srckeystore <pfx file path> –srcstoretype pkcs12 –destkeystore <keystore name> –deststoretype JKS

         2. At the prompt, enter the keystore password.

         3. If requested, provide the pfx password.

            The pfx password and the keystore password must be identical. If you need to change the password of the private key inside the keystore, get the private key entry alias keytool -list -keystore <keystore path> and update the password as follows: keytool –keypasswd <Alias> –new <New Password> –keystore <Path to your keystore>.

      2. If you have other certificates used during communication between the client and Tomcat, for each certificate do the following:

         When configuring Tomcat to work using HTTPS, a certificate must be imported to the keystore that is used within Tomcat. The certificate can be an organizational certificate that is used throughout the company, or a specific certificate that is generated solely for this purpose. Another solution is to generate a self-signed certificate. For details, refer to Secure the connection between guacd and the webapp below.

         1. Import the certificate using the following command:

            keytool -import -alias <Certificate alias> -keystore <created keystore path> -trustcacerts -file <.crt file path>

            For example:

            keytool -import -alias newkey -keystore /opt/tomcat/keystore -trustcacerts -file /opt/tomcat/cert.crt

         2. When prompted, enter the password of the keystore you generated above.

         3. Accept the import of the certificate to the keystore.

      3. Configure Tomcat to work with SSL and the keystore you generated in the previous step:

         1. In $CATALINA_HOME/conf/, open server.xml.

         2. Add the connector:

            <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" maxThreads="150" SSLEnabled="true" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keystoreFile="<generated keystore path>" keystorePass="<generated keystore password>" />

         3. Locate Connector port="8443" and change the keystore attributes to those of your generated keystore.

            Attribute	Description
            keystoreFile	The keystore path
            keystorePass	The keystore password

         4. Delete any additional Connector sections.

      4. Restart the Tomcat server.

         service tomcat restart

   5. Configure the reverse proxy for Tomcat, based on your OS.

      Open the Tomcat default ports in the RHEL7 firewall (firewalld):

      firewall-cmd --permanent --add-forward-port=port=443:proto=tcp:toport=<Tomcat secured connector port - defaults to 8443>   firewall-cmd --reload

      The PVWA PSM gateway port should be 443 instead of 8443.

   6. Test the basic connection: link to https://<server-ip-address>. The Tomcat default webApp success page should appear.

2. Deploy the HTML5 service

   This step deploys the HTML5 service, and starts a new daemon called guacd on the system. The paths on which the HTML5 service is deployed cannot be configured.

   1. Copy the psmgwparms.sample to /var/tmp/psmgwparms:

      cp <installation folder path>/psmgwparms.sample /var/tmp/psmgwparms

   2. Edit the psmgwparms file:

      vi /var/tmp/psmgwparms

   3. Configure the psmgwparms as follows:

       

      Parameter	Description	Value
      AcceptCyberArkEULA	Accept the CyberArk EULA	Yes
      Hardening	Specify whether or not to harden the machine	Yes
      WebAppsDir	The name of your web application directory.	For example: <Tomcat_path>/webapps
      WebApplicationServerUser WebApplicationServerGroup	The name of the group and user that the web server is deployed with	For example: User: tomcat Group: tomcat
      EnableJWTValidation	Enable or disable JWT validation to authenticate the requests to the HTML5 gateway For details, see JWT validation	Yes
      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
      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. Default value: blank

   4. Install the RPM.

      This installs the required daemon files and webapp files.

      The RPM installation package is located in the HTML5 Gateway directory of the PSM installation package.

      Run the following command as root:

      rpm -i CARKpsmgw-<version>.rpm

   5. Run the following command to verify that the guacd daemon service is up and running:

      /etc/init.d/guacd status

   6. Run the following command to verify that the web service is up and running:

      service tomcat restart

3. Secure the connection between guacd and the webapp

   To secure the connection between guacd and the webapp, a certificate and PEM file are required.

   1. Import the certificate into the JVM Keystore:

      Import the self-signed certificate and PEM file that you created when deploying Tomcat, into the JVM Keystore.

      To discover where the JVM Keystore is, run the following command:

      readlink -f /usr/bin/java | sed "s:bin/java::"

      The cacerts JVM Keystore should be in <readlink output path>/lib/security/cacerts

      To import the certificate, run the following command:

      keytool -import -alias webapp_guacd_cert -keystore <readlink output path>/lib/security/cacerts -trustcacerts -file <.crt file path>

      The default password to the keystore is changeit.

   2. Configure the guacd configuration file:

      1. In /etc/guacamole/guacd.conf, open the guacd configuration file.
      2. Locate the SSL section and do the following:
         1. If the section is commented out, uncomment it.

         2. Configure the following parameters:

            Attribute	Description
            server_certificate	The path of the certificate
            server_key	The path to the PEM file

            [ssl] server_certificate = <.crt file path> server_key = <.pem key file path>

   3. Restart the guacd service by running:

      /etc/init.d/guacd restart

   4. Restart the Tomcat service by running:

      service tomcat restart

4. Secure the webapp and JWT validation endpoint

   To secure the connection between the webapp and the JWT validation endpoint, the endpoint signing CA certificate is required.

   1. Import the the endpoint signing CA certificate (PVWA) into the JVM Keystore:

      To discover where the JVM Keystore is, run the following command:

      readlink -f /usr/bin/java | sed "s:bin/java::"

      The cacerts JVM Keystore should be in <readlink output path>/lib/security/cacerts

      To import the certificate, run the following command:

      keytool -import -alias jwt_endpoint_cert -keystore <readlink output path>/lib/security/cacerts -trustcacerts -file <CA certificate file path>

      For details about the default password and how to change it, see Change keystore password.

      If the JWT validation endpoint is signed by a CA chain, repeat this step for each intermediate CA certificate.

Hardening

This section describes hardening for each component and connection. Before you begin, complete Install the HTML5 Gateway.

Hardening includes:

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.

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

Upgrade the PSM HTML5 Gateway

For details, see Using RPM.