Security

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.

Configuration reference

The table below lists the ".env" variables described in this article.

| Variable | Purpose | Default | Min. version | | NGINX_PORT | HTTP listening port for inbound connections | 80 | All | | NGINX_ENABLE_SSL | Enables TLS for inbound connections | Disabled | All | | NGINX_TLS_CERT | Certificate filename (in HS_PATH/certs) | — | All | | NGINX_TLS_KEY | Private-key filename (in HS_PATH/certs) | — | All | | SECURE_COOKIES | Marks cookies as secure; set to true when TLS is enabled | — | All | | NGINX_ENABLE_SSL_REDIRECT | Enables HTTP-to-HTTPS redirect | Disabled | All | | NGINX_TLS_PORT | TLS listening port | 443 | All | | HS_TLS_VERIFY_ENABLED | false disables outbound certificate validation¹ | true | All | | HS_TLS_CA_BUNDLE | Custom CA bundle for validating outbound connections¹ | — | All² | | HS_SECURE_HSTS_SECONDS | Enables HSTS; value is the header's max-age in seconds | Disabled | v37 | | HS_SECURE_HSTS_INCLUDE_SUBDOMAINS | true adds includeSubDomains to the HSTS header | false | v37 | | HS_SECURE_HSTS_PRELOAD | true adds preload to the HSTS header | false | v37 | | HS_CUSTOM_OPENSSL_CNF_DISABLE | yes restores default OpenSSL cipher options | Not set | All | | HS_OPENSSL_SECLEVEL | OpenSSL security level | 1 | All | | HS_OPENSSL_MINPROTOCOL | Minimum TLS protocol version | TLSv1.2 | All | | NGINX_DISABLE_BACKEND_SERVER_HEADER | yes excludes X-Extract-Backend-Server response headers | Not set | v30.0.7 / v31.0.1 | | NGINX_ERROR_LOG_LEVEL | Minimum severity for logging NGINX issues | info | v40 |

¹ Mutually exclusive — use only one of the two. ² Applies to Java Message Service (JMS) connections in v33 and later.

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
  1. Copy the certificate and key to this directory.
  2. If SELinux is enabled, execute:
   chcon -t container_file_t -R /mnt/hs/certs/

Obtain outbound server's CA certificate in PEM format

To validate outbound HTTPS connections, the application needs the external service's certificate in PEM format, placed in the HS_PATH/certs directory. If you don't have the certificate on hand, you can retrieve it directly from the server in one of two ways.

Option 1: Command line (OpenSSL)

Run the following command, replacing <hostname> with the server's domain name:

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

Option 2: Browser (Chrome)

  1. Go to the server's URL, and click the View site information icon to the left of the address bar.
  2. Click Connection is secure, and then click Certificate is valid.
  3. In the Details tab, select the bottom certificate in the hierarchy and click Export.
  4. In the Save dialog, set the file format to Base64-encoded ASCII, select the certificate chain, and save the file.

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

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.

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>

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.

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>

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.

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:

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.