Security

Overview

This article describes the security-related settings available for your Hyperscience instance: TLS / HTTPS for inbound and outbound connections, certificate management, HSTS, TLS version and cipher requirements, listening ports, server-identifying headers, and NGINX issue logging.

All settings are configured through variables in the .env File.

TLS / HTTPS

To enable TLS in the Hyperscience application, a certificate and a key must be provided.

Prepare the certificate directory

Hyperscience expects PEM-formatted certificates. This page discusses how to convert DER-encoded certificates and Java Keystore (JKS) certificates to the PEM format.

1. Create the directory that will hold the certificate and key. Assuming /mnt/hs/ is used as the HS_PATH:

   mkdir -p /mnt/hs/certs

   To learn more about sharing files (e.g., certificates) across application machines, see Best Practices for Sharing Files Across Machines.

2. Copy the certificate and key to this directory.

3. If SELinux is enabled, execute:

   chcon -t container_file_t -R /mnt/hs/certs/

   SELinux requires re-running chcon on every file change. If SELinux is enabled, the chcon command must be executed again each time a file is added to the certs directory for any reason.

openssl s_client -showcerts -connect <hostname>:443 </dev/null | sed -n -e '/-.BEGIN/,/-.END/ p' > certifs.pem

TLS configuration for inbound connections

Add the following to the “.env” file, where NGINX_TLS_CERT and NGINX_TLS_KEY are the names of the two files copied into the certs directory::

NGINX_ENABLE_SSL=yes
NGINX_TLS_CERT=<cert filename (without folder path)>
NGINX_TLS_KEY=<key filename (without folder path)>
SECURE_COOKIES=true

In the parameters above, NGINX_TLS_CERT and NGINX_TLS_KEY are the names of the two files that were copied into the certs directory (e.g., /mnt/hs/certs).

Optionally, enable the HTTP-to-HTTPS redirect with NGINX_ENABLE_SSL_REDIRECT=yes, and override the default TLS port (443) with NGINX_TLS_PORT .

TLS configuration for outbound connections

Depending on how it is configured, the application may connect to various external services, such as a UiPath Orchestrator instance, over HTTPS or TLS. The mutually exclusive settings described below control how these connections are validated. In v33 and later, they apply to connections that use Java Message Service (JMS) — including RabbitMQ, ActiveMQ, and IBM MQ output connections — and, in all versions, to the connection between the Trainer and the main application.

HS_TLS_CA_BUNDLE (recommended)

This setting specifies a custom bundle of CA certificates to validate against when establishing an HTTPS or TLS connection:

HS_TLS_CA_BUNDLE=<CA_bundle_filename>

The filename used must be a file in the HS_PATH/certs directory. To retrieve a server's certificate chain in PEM format, see Obtain outbound server's CA certificate in PEM format.

To give the application read access to the CA bundle file, run:

chmod 644 $HS_PATH/certs/*

If using SELinux, also run:

chcon -t container_file_t .

This bundle replaces the default set of trusted CA certificates, so it must include all root certificates used by external services. To combine multiple certificates, simply concatenate them together into a single file.

HS_TLS_VERIFY_ENABLED

Setting HS_TLS_VERIFY_ENABLED=false disables certificate validation entirely, allowing the use of self-signed or enterprise-signed certificates. However, because it leaves connections open to man-in-the-middle attacks, we recommend using HS_TLS_CA_BUNDLE instead wherever possible.

HS_TLS_VERIFY_ENABLED=false

HTTP Strict Transport Security (HSTS)

In v37 and later, you can force users' browsers to connect to your instance via HTTPS rather than HTTP by enabling HSTS. Doing so adds the Strict-Transport-Security HTTP response header to your application URL's responses, preventing cookie-hijacking and downgrade attacks, among other types of malicious activity.

HSTS is disabled by default. To enable it, set HS_SECURE_HSTS_SECONDS — the number of seconds that users' browsers should remember the URL's enforcement of HTTPS-only access:

HS_SECURE_HSTS_SECONDS=<value for max-age for the Strict-Transport-Security header>

Optionally, set HS_SECURE_HSTS_INCLUDE_SUBDOMAINS to true to apply HSTS protections across all of the URL's subdomains, and HS_SECURE_HSTS_PRELOAD to true to add preload to the header. Preload requires HS_SECURE_HSTS_SECONDS of at least 31536000 (1 year) and HS_SECURE_HSTS_INCLUDE_SUBDOMAINS set to true.

For more information on HSTS, see Mozilla's Strict-Transport-Security - HTTP.

TLS versions and cipher suites

By default, we only support TLS versions 1.2 and above. However, our OpenSSL library configuration options allow you to use TLS 1.0 or 1.1, if necessary.

The OpenSSL library is the default TLS protocol implementation in Linux. For compatibility reasons, we use a custom OpenSSL configuration to relax TLS cipher suite requirements. The following “.env” variables let you fine-tune your TLS cipher suites:

HS_CUSTOM_OPENSSL_CNF_DISABLE=<yes/no, default is not set>
HS_OPENSSL_SECLEVEL=<sec level, default is 1>
HS_OPENSSL_MINPROTOCOL=<TLS version, default is TLSv1.2>

• HS_CUSTOM_OPENSSL_CNF_DISABLE — yes disables the custom configuration and restores the default OpenSSL cipher options; any other value enables the custom configuration.

• HS_OPENSSL_SECLEVEL — see OpenSSL's SSL_CTX_set_security_level documentation for options.

• HS_OPENSSL_MINPROTOCOL — see the “-min_protocol, -max_protocol” section of OpenSSL's SSL_CONF_cmd documentation for options.

To learn more about OpenSSL, see OpenSSL's Documentation.

Load balancer

To achieve HA/DR goals for the application, we encourage customers to deploy the application on multiple VMs and to use a load balancer for the web requests. To learn more, see Load Balancer.

The application uses the HTTP_HOST from the request to generate some of its links. Bear this in mind if you are configuring a load balancer.

Ports and HTTP headers

HTTP listening port

To change the HTTP listening port for inbound connections (default 80), set:

NGINX_PORT=<listening port number>

Excluding X-Extract-Backend-Server HTTP headers

The X-Extract-Backend-Server HTTP header of each application response contains the hostname of the VM that processed the request. In v30.0.7+ and v31.0.1+, you can exclude these headers from your application's responses:

NGINX_DISABLE_BACKEND_SERVER_HEADER=yes

Logging NGINX-related issues

With the NGINX_ERROR_LOG_LEVEL “.env” variable in v40 and later, you can specify the minimum severity level an issue must have in order for it to be logged by the syslog utility.

Possible values, from least severe to most severe, are:

• debug

• info (default)

• notice

• warn

• error

• crit

• alert

• emerg

Choose the level that helps you debug most effectively — at the default info level, issues with info severity and above are logged.

For more details, see NGINX's Configuring Logging.