Configure TLS

Itential Platform supports TLS versions 1.0 through 1.3.

Configure TLS settings with environment variables or platform properties.

Use webserver_https_secure_protocol to set a specific TLS method, or use webserver_https_tls_min_version and webserver_https_tls_max_version to define a version range. When both are configured, min and max properties take precedence and the platform logs a warning.

For information, see Platform properties and environment variables.

Configuration Methods

Set a specific TLS method

Use to set a specific TLS method:

• TLSv1_method, TLSv1_1_method, TLSv1_2_method: Restricts to that version only
• TLS_method: Allows TLS v1.0 through v1.3, negotiating the highest mutually supported version

Set minimum and max versions

Use webserver_https_tls_min_version and webserver_https_tls_max_version to define a version range.

Defines an allowed version range. Takes precedence over webserver_https_secure_protocol.

Valid values: TLSv1.3, TLSv1.2, TLSv1.1, TLSv1

Examples

Allow TLS v1.0 through v1.3:

$
ITENTIAL_WEBSERVER_HTTPS_SECURE_PROTOCOL=TLS_method

Restrict to TLS v1.2:

$
ITENTIAL_WEBSERVER_HTTPS_SECURE_PROTOCOL=TLSv1_2_method

Restrict to TLS v1.3:

$
ITENTIAL_WEBSERVER_HTTPS_TLS_MIN_VERSION=TLSv1.3
$
ITENTIAL_WEBSERVER_HTTPS_TLS_MAX_VERSION=TLSv1.3

Allow TLS v1.2 and v1.3:

$
ITENTIAL_WEBSERVER_HTTPS_TLS_MIN_VERSION=TLSv1.2
$
ITENTIAL_WEBSERVER_HTTPS_TLS_MAX_VERSION=TLSv1.3

Considerations

Keep in mind these considerations:

• TLS v1.3 uses a new handshake format incompatible with some older clients
• When using TLS_method, the platform negotiates the TLS version with each client based on mutual support
• TLS v1.0 and v1.1 have known security vulnerabilities
• Configure using either secure_protocol or min/max properties, not both

Troubleshoot

If clients cannot connect, verify they support the configured TLS versions and check logs for handshake errors or configuration warnings.