Configure TLS on Independent Gateway

Applies to: Tableau Advanced Management

TLS support for Independent Gateway is in Tableau Server 2022.1.2 and later.

Both Tableau Server and Tableau Server Independent Gateway use the SSL module (mod_ssl) built with OpenSSL to implement Transport Layer Security (TLS) features.

Because of its complexity and security-sensitive nature, we recommend that TLS configuration is planned and implemented by an IT professional who is familiar TLS on Apache httpd.

In many cases, we use "SSL" in the names of things for compatibility with existing TSM or Apache httpd configuration properties or concepts. "SSL" actually refers to protocol versions now considered insecure and obsolete. However, the legacy name persists and is often used interchangeably with TLS as convention. Tableau Server and Independent Gateway do not support SSL-era protocols.

TLS configuration example

For an end-to-end TLS configuration example, see Configure SSL/TLS from load balancer to Tableau Server(Link opens in a new window) in the Enterprise Deployment Guide. The topic shows a step-by-step example of configuring TLS on Tableau Server on Linux in an AWS deployment. Although the example describes the process for Linux, the configuration example is also useful for Tableau Server on Windows.

TLS configuration overview

You can configure TLS for HTTPS on any of the following sections of the internet-to-Tableau Server path:

  • From the external network (internet or front-end load balancer) to Independent Gateway
  • From Independent Gateway to Tableau Server
  • For housekeeping (HK) process from Tableau Server to Independent Gateway

This topic provides procedures to configure each of these hops.

You will need to make configuration changes to Independent Gateway computers and to the Tableau Server cluster.

Certificate requirements and considerations

The certificate requirements for Independent Gateway are the same as those specified for Tableau Server "external SSL." See SSL certificate requirements.

Other considerations:

  • To simplify certificate management and deployment, and as a security best practice, we recommend using certificates generated by a major trusted third party certificate authority (CA). Alternatively, you may generate self-signed certificates or use certificates from a PKI for TLS. In this case, pay attention to the configuration options for trusting CA certificates and validating certificates.
  • If your implementation requires the use of a certificate chain file, see the Knowledge Base article, Configure TLS on Independent Gateway when using a certificate that has a certificate chain(Link opens in a new window).
  • If you are running multiple instances of Independent Gateway, then you must distribute certificates to each computer in the same location (file path).
  • If you are running a Tableau Server deployment with more than one node, certificates that you upload with TSM commands are automatically distributed across the nodes. Run all TSM commands on the initial node.

Global TLS configurations

The following configurations are global. The configuration options below refer to configuration keys that must set with the tsm configuration set command. The commands must include the --force-keys option.

It's unlikely that you will need to change these values.

Note that each pair of keys shares the same naming format, where the string, tsig, sets the value for the Independent Gateway. The key that does not include the string, tsig, sets the value for the gateway process on the Tableau Server cluster.

If you do not set a value for the tsig key, then the default Tableau Server gateway value will be used.

gateway.tsig.httpd.socache or gateway.httpd.socache

Default: shmcb

Alternate value: dbm

The storage type of the inter-process SSL Session Cache. For more information about the shmcb and dbm storage types, see SSLSessionCache Directive(Link opens in a new window) on Apache website.

gateway.tsig.httpd.shmcb.size or gateway.httpd.shmcb.size

Default: 2048000

Amount of memory, in bytes, to use for the circular buffer when using shmcb storage type.

Note: Another global key is gateway.tsig.ssl.key.passphrase.dialog. If applicable, there is only a single configuration for gateway.tsig.ssl.key.passphrase.dialog. By design, it collects passphrases for all encrypted private key files in the configuration. The applicable sections later in this topic describe the use of this key.

External TLS to Independent Gateway

The process of configuring external connections to terminate TLS on the Independent Gateway servers is conceptually similar to how "external SSL" is configured for a Tableau Server cluster. The mechanics are different. TSM does not automatically distribute certificate and key material to Independent Gateway nodes. Additionally, Independent Gateway does not automatically provide a way to supply the optional TLS key passphrase on startup.

The following steps describe how to configure TLS from external source to Independent Gateway computers.

Step 1: Distribute files to Independent Gateway computers

  1. Place certificates and related files in a location and with permissions that allow the Independent Gateway service (tsig-httpd) to read them. We recommend restricting access to the key files such that only the Independent Gateway service can read them.
  2. Place all files, certificates, and keys in exactly the same locations on all Independent Gateway computers. Place the files outside of the TSIG_INSTALL and TSIG_DATA paths so that they do not get removed if you reinstall or upgrade Independent Gateway.

Step 2: Update environment variables on Independent Gateway computers

On each Independent Gateway computer, set the TSIG_PORT and TSIG_PROTOCOL environment variables to 443 (by convention, but any unused TCP port number is supported) and https respectively.

Change these values by re-running the post-install script to provide a different value for TSIG_PORT and TSIG_PROTOCOL. By default, the script is at C:\Program Files\Tableau\Tableau Server\independentgateway\scripts\initialize-tsig.bat.

Step 3: Set TLS configuration properties on Tableau Server

Most of the TSM configuration keys in the following table are derived from Apache httpd directives. As such, the configuration values for these TSM configuration keys map directly to the valid values for the corresponding Apache directive. Links to corresponding directives are included in the following table.

In some cases. the configuration will use fallback configurations if a particular key is not set. These are called out in the table below.

The configuration options in the following table refer to configuration keys that you must set with the tsm configuration set command. All commands must include the --force-keys option. For example:

tsm configuration set -k gateway.tsig.ssl.enabled -v true --force-keys

After you have set the configuration keys, you must run tsm pending-changes apply.

Configuration property Description Corresponding Apache directive
gateway.tsig.ssl.enabled

Required.

Enables TLS. Must be set to true.

 N/A
gateway.tsig.ssl.cert.file_name

Required.

Path + file name of the certificate file for Independent Gateway. For example, /etc/ssl/certs/tsig-ssl.crt.

 SSLCertificateFile(Link opens in a new window)
gateway.tsig.ssl.key.file_name

Required.

Path + file name of the certificate key file for Independent Gateway. For example, /etc/ssl/keys/tsig-ssl.key.

 SSLCertificateKeyFile(Link opens in a new window)
gateway.tsig.ssl.key.passphrase.dialog If your key requires a passphrase, then you must configure this key with the correct string expected by the Apache httpd SSLPassPhraseDialog directive. Do not enter the literal passphrase for this key. Refer to the Apache documentation for information about how to configure this key.
This configuration is global for Independent Gateway. 		SSLPassPhraseDialog(Link opens in a new window)

gateway.tsig.ssl.protocols

Fallback: ssl.protocols

 Specify supported versions of SSL/TLS. See Security Hardening Checklist for more information about default configuration. SSLProtocols(Link opens in a new window)

gateway.tsig.ssl.ciphersuite

Fallback: ssl.ciphersuite

 Specifies ciphers that the client is permitted to negotiate for SSL connection. SSLCipherSuite(Link opens in a new window)
gateway.tsig.ssl.client_certificate_login.required

Set this value to true to enable mutual TLS on this connection.

You must also set the gateway.tsig.ssl.cacert.file property as specified below.

 N/A
gateway.tsig.ssl.cacert.file Specifies the file containing the concatenated CA certificates for client authentication process. SSLCACertificateFile(Link opens in a new window)
gateway.tsig.ssl.revocation.file Specifies the file containing the concatenated CA revocation lists for clients that connect to Independent Gateway. SSLCARevocationFile(Link opens in a new window)
gateway.tsig.ssl.redirect

When Independent Gateway has been configured for TLS, this option forces client requests from port 80 (default) to redirect to TLS.

Default: true.

 N/A
gateway.tsig.ssl.redirect_from_port

When gateway.tsig.ssl.redirect is set to true, this option allows you to specify the port from which traffic is redirected.

Default: 80.

 N/A

Independent Gateway to Tableau Server

This section describes how to encrypt the connection between the Independent Gateway and Tableau Server.

Step 1: Configure and enable TLS on Tableau Server

See Configure SSL for External HTTP Traffic to and from Tableau Server.

Note that "SSL" is actually a TLS implementation, and "external" refers to an external connection to Tableau Server. In this scenario, the Independent Gateway is the "external" connection.

We recommend enabling and verifying that clients can connect with TLS directly to Tableau Server before configuring Independent Gateway.

Step 2: Distribute certificate files on Independent Gateway computers

You will need to distribute certificate files on the Independent Gateway computers if either of the following are true:

  • You are using self-signed or PKI certificates for the TLS certificates on the Tableau Server deployment.
  • You are enabling mutual TLS on the connection from Independent Gateway to Tableau Server.

As with all TLS-related files on Independent Gateway computers, you must put the files in the same paths on each computer. All file names for TLS shared files must also be the same.

Step 3: Set TLS configuration properties on Tableau Server

Most of the TSM configuration keys in the following table are derived from Apache httpd directives. As such, the configuration values for these TSM configuration keys map directly to the valid values for the corresponding Apache directive. Links to corresponding directives are included in the following table.

In some cases. the configuration will use fallback configurations if a particular key is not set. These are called out in the table below.

The configuration options in the following table refer to configuration keys that you must set with the tsm configuration set command. All commands must include the --force-keys option. For example:

tsm configuration set -k gateway.tsig.ssl.enabled -v true --force-keys

After you have set the configuration keys, you must run tsm pending-changes apply.

Configuration property Description Corresponding Apache directive

gateway.tsig.ssl.proxy.cacertificatefile

If your organization uses a self-singed or PKI-generated TLS certificate for Tableau Server, then you must specify a path to the root CA certificate file. This root CA certificate file must be stored on the Independent Gateway computers. SSLProxyCACertificateFile (Link opens in a new window)

gateway.tsig.ssl.proxy.protocols

Fallback: ssl.protocols

 Specify supported versions of SSL/TLS. See Security Hardening Checklist for more information about default configuraiton. SSLProtocols(Link opens in a new window)

gateway.tsig.ssl.proxy.ciphersuite

Fallback: ssl.ciphersuite

 Specifies ciphers that the client is permitted to negotiate for SSL connection. SSLCipherSuite(Link opens in a new window)
gateway.tsig.ssl.proxy.machinecertificatefile For mutual TLS. Specifies the file containing concatenated certificate-key pairs for authentication of the Independent Gateway to Tableau Server. SSLProxyMachineCertificateFile(Link opens in a new window)
gateway.tsig.ssl.proxy.verify

Specify whether Independent Gateway should verify the certificate presented by Tableau Server.

Defaults to require.

 SSLProxyVerify(Link opens in a new window)
gateway.tsig.ssl.proxy.checkpeername

Specify whether Independent Gateway inspects Tableau Server certificate to verify that subject name matches server name.

Defaults to off.

 SSLProxyCheckPeerName(Link opens in a new window)
gateway.tsig.ssl.proxy.checkpeerexpire

Specify whether Independent Gateway inspects Tableau Server certificate to verify expiry:

Defaults to off.

 SSLProxyCheckPeerExpire(Link opens in a new window)

Step 4: Upload root CA certificate to Tableau Server

If the TLS certificate that you are using on the Independent Gateway computers is a self-signed or PKI-generated certificate then you must perform this additional step. If the TLS certificate that you are using on the Independent Gateway computer is a certificate from a trusted third-party certificate authority, then you can skip this step.

Copy the root CA certificate used for the Independent Gateway computers to the initial node of Tableau Sever, and then run the following commands:

tsm security custom-cert add -c <root-certificate-file-name>.pem
tsm pending-changes apply

Housekeeping connection between Tableau Server and Independent Gateway

The housekeeping (HK) process maintains configuration state between the backend Tableau Server deployment and the Independent Gateway.

When Independent Gateway is installed, the default configuration provides an unencrypted HTTP connection. Independent Gateway listens for housekeeping requests originating in the Tableau Server cluster (as you defined it during installation).

If you are running multiple instances of Independent Gateway, then all servers must accept housekeeping requests with TLS or all without TLS. This section describes how to configure HK connection for TLS. This process requires restarting Tableau Server and will result in downtime.

As with the previous TLS scenarios described above, many of the configuration changes for HK connection are set on configuration properties managed by the Tableau Server cluster. However, HK TLS configuration requires additional steps on Independent Gateway.

Step 1: Distribute files to Independent Gateway computers

If you have enabled TLS with external network and Independent Gateway, you may use the same certificate and key files for the HK connection.

If you are using the same assets, then the only other certificate file that you need to distribute is the root CA certificate for the certificate used by Tableau Server. If the TLS certificate presented by Tableau Server is generated by a trusted third-party CA, then you do not need to copy a root CA certificate to the Independent Gateway computers.

  1. Place certificates and related files in a location and with permissions that allow the Independent Gateway service (tsig-httpd) to read them. We recommend restricting access to the key files such that only the Independent Gateway service can read them.
  2. Place all files, certificates, and keys in exactly the same locations on all Independent Gateway computers.

Step 2: Import Independent Gateway root CA certificate into Tableau Server trust store

If the TLS certificate that you are using on the Independent Gateway computers is a self-signed or PKI-generated certificate then you must perform this additional step. If the TLS certificate that you are using on the Independent Gateway computer is a certificate from a trusted third-party certificate authority, then you can skip this step.

You may only upload one root CA certificate to Tableau Server. Therefore, if you have already uploaded a root CA certificate, then the same root CA certificate must sign the certificate that you will be using for HK connection.

Copy the root CA certificate used for the Independent Gateway computers to the initial node of Tableau Sever, and then run the following commands:

tsm security custom-cert add -c <root-certificate-file-name>.pem
tsm pending-changes apply

Step 3: Update environment variables on Independent Gateway computers

On each Independent Gateway computer, set the TSIG_HK_PROTOCOL environmental variable to https. You may specify an alternative port for HK (default is 21319) by setting the TSIG_HK_PORT environment variable as well.

Change these values by re-running the post-install script to provide a different value for TSIG_HK_PROTOCOL and TSIG_HK_PORT. By default, the script is at C:\Program Files\Tableau\Tableau Server\independentgateway\scripts\initialize-tsig.bat.

Step 4: Update httpd.conf.stub on Independent Gateway

You must update the httpd.conf.stub file on each Independent Gateway server. The httpd.conf.stub file is used to seed the global httpd configuration.

The file is located at TSIG_DATA/config/httpd.conf.stub.

  1. Open the httpd.conf.stub file in a text editor. You must update the <VirtualHost *:${TSIG_HK_PORT}> block with HK configuration details. The following example shows the required changes:

    <VirtualHost *:${TSIG_HK_PORT}>
 SSLEngine on
 #TLS# SSLHonorCipherOrder on
 #TLS# SSLCompression off
 SSLCertificateFile /etc/ssl/certs/tsig-ssl.crt
 SSLCertificateKeyFile /etc/ssl/private/tsig-ssl.key
 SSLCACertificateFile /etc/ssl/certs/rootTS-CACert.pem 
#TLS# SSLCARevocationFile /path/to/file
</VirtualHost>

    Notes:

    • By default, each line in the <VirtualHost *:${TSIG_HK_PORT}> block is commented out by the string, #TLS#. To "enable" a line in the block, delete the #TLS# string at the beginning of the line.
    • As with all httpd configurations, each referenced file requires an absolute path to the file.
    • SSLCACertificateFile specifies the root CA certificate for the CA that generates the certificate presented by Tableau Server. You only need to set this if the TLS certificate used by Tableau Server is self-signed or generated by a PKI.

  2. Stop the tsig-httpd service.

    You will start receiving failed status checks at this point, indicating in TSM that your Independent Gateway component is degraded.

  3. Copy httpd.conf.stub to httpd.conf.

    The httpd.conf file is in the same directory. Overwrite the httpd.conf file with the httpd.conf.stub file.

  4. Start the tsig-httpd service.

    You will continue receiving failed status checks at this point, indicating in TSM that your Independent Gateway component is degraded. These status checks will fail until you have completed the configuration as described in the following steps.

Step 5: Set TLS configuration properties on Tableau Server

Applying the configuration changes requires a restart of the server. To avoid long timout times, we recommend stopping the server before applying changes that you set here. In Step 6, you will run an update command and then restart TSM. Stopping TSM at this phase of the configuration results in a shorter downtime.

  1. Stop TSM. Run the following command:

    tsm stop

  2. Most of the TSM configuration keys in the following table are derived from Apache httpd directives. As such, the configuration values for these TSM configuration keys map directly to the valid values for the corresponding Apache directive. Links to corresponding directives are included in the following table.

    There are TSM configuration property names that include the hk node in the prefix: gateway.tsig.hk.xyz.abc. If set, these values are used for the HK TLS configuration. If not set, many configuration properties will use the fallback to gateway.tsig.xyz.abc, which themselves may or may not fall back to gateway.xyz.abc. The fallback configuration property is listed when relevant.

    The configuration options in the following table refer to configuration keys that you must set with the tsm configuration set command. All commands must include the --force-keys option. For example:

    tsm configuration set -k gateway.tsig.hk.ssl.enabled -v true --force-keys
    Configuration property Description Corresponding Apache directive

    gateway.tsig.hk.ssl.enabled

    (No fallback)

    Required.

    Enables TLS. Must be set to true.

    		 N/A

    gateway.tsig.hk.ssl.cert.file_name

    Fallback:

    gateway.tsig.ssl.cert.file_name

    Path + file name of the certificate file for Independent Gateway. For example, /etc/ssl/certs/tsig-ssl.crt.

    		 SSLCertificateFile(Link opens in a new window)

    gateway.tsig.hk.ssl.key.file_name

    Fallback:

    gateway.tsig.ssl.key.file_name

    Path + file name of the certificate key file for Independent Gateway. For example, /etc/ssl/keys/tsig-ssl.key.

    		 SSLCertificateKeyFile(Link opens in a new window)

    gateway.tsig.ssl.key.passphrase.dialog

    (Global property)

    		 If your key requires a passphrase, then you must configure this key with the correct string expected by the Apache httpd SSLPassPhraseDialog directive.
    This configuration is global for Independent Gateway.    		 SSLPassPhraseDialog(Link opens in a new window)

    gateway.tsig.hk.ssl.protocols

    Fallbacks:

    gateway.tsig.ssl.protocols

    ssl.protocols

    		 Specify supported versions of SSL/TLS. See Security Hardening Checklist for more information about default configuration. SSLProtocols(Link opens in a new window)

    gateway.tsig.hk.ssl.ciphersuite

    Fallbacks:

    gateway.tsig.ssl.ciphersuite

    ssl.ciphersuite

    		 Specifies ciphers that the client is permitted to negotiate for SSL connection. SSLCipherSuite(Link opens in a new window)

    gateway.tsig.hk.ssl.client_certificate_login.required

    (No fallback)

    Set this value to true to enable mutual TLS on this connection.

    You must also set the gateway.tsig.hk.ssl.cacert.file property as specified below.

    		 N/A

    gateway.tsig.hk.ssl.cacert.file

    Fallback:

    gateway.tsig.ssl.cacert.file

    		 Specifies the file containing the concatenated CA certificates for client authentication process. SSLCACertificateFile(Link opens in a new window)

    gateway.tsig.hk.ssl.revocation.file

    Fallback:

    gateway.tsig.hk.ssl.revocation.file

    		 Specifies the file containing the concatenated CA revocation lists for clients that connect to Independent Gateway. SSLCARevocationFile(Link opens in a new window)

  3. Apply changes. Run the following command:

    tsm pending-changes apply.

Step 6 Update Independent Gateway JSON configuration file

The final step is to update the Independent Gateway configuration with a JSON file reflecting the switch to https and, if applicable, other port numbers.

Refer to the installation topic for more information about editing this file. See Step 3: Enable Independent Gateway in Tableau Server.

After you have updated the JSON file, run the following commands:

tsm topology external-services gateway update -c tsig.json
tsm start

Troubleshooting

For troubleshooting tips, see Troubleshooting Tableau Server Independent Gateway(Link opens in a new window) in the Enterprise Deployment Guide (EDG). The EDG provides example deployment of Tableau Server on Linux. The troubleshooting steps are useful for Windows or Linux versions of Tableau Server.

Back to top
Thanks for your feedback!Your feedback has been successfully submitted. Thank you!