Configure SSL for External HTTP Traffic to and from Tableau Server


You can configure Tableau Server to use Secure Sockets Layer (SSL) encrypted communications on all external HTTP traffic. Setting up SSL ensures that access to Tableau Server is secure and that sensitive information passed between the server and Tableau clients – such as Tableau Desktop, the REST API, analytics extensions and so on – is protected. Steps on how to configure the server for SSL are described this topic; however, you must first acquire a certificate from a trusted authority, and then import the certificate files into Tableau Server.

Mutual SSL authentication is not supported on Tableau Mobile.

SSL certificate requirements

Acquire an Apache SSL certificate from a trusted authority (for example, Verisign, Thawte, Comodo, GoDaddy). You can also use an internal certificate issued by your company. Wildcard certificates, which allow you to use SSL with many host names within the same domain, are also supported.

When you acquire an SSL certificate for external communication to and from Tableau Server, follow these guidelines and requirements:

  • All certificate files must be valid PEM-encoded X509 certificates with the extension .crt.

  • Use a SHA-2 (256 or 512 bit) SSL certificate. Most browsers no longer connect to a server that presents an SHA-1 certificate.

  • In addition to the certificate file, you must also acquire a corresponding SSL certificate key file. The key file must be a valid RSA or DSA private key file (with the extension .key by convention).

    You can choose to passphrase-protect the key file. The passphrase you enter during configuration will be encrypted while at rest. However, if you want to use the same certificate for SSL and SAML, you must use a key file that is not passphrase protected.

    Important:If your key file is passphrase protected, you must verify that the related cryptographic algorithm is supported by the version of Tableau Server you are running. Tableau Server uses OpenSSL to open password-protected key files. As of August 2023, the latest releases of Tableau Server (2021.3.26, 2021.4.21, 2022.1.17, 2022.3.9, 2023.1.5 and newer) run OpenSSL 3.1. Previous versions of Tableau Server ran OpenSSL 1.1. A number of cryptographic algorithms have been retired and are no longer supported in OpenSSL 3.1. If you are using a passphrase-protected key file on an older version of Tableau Server that is still running OpenSSL 1.1, review the following Knowledge Base article before you upgrade to the latest version of Tableau Server: Gateway and Prep Conductor failed to start when using External SSL with passphrase to protect the key file after upgrade to Tableau Server 2022.1.17(Link opens in a new window).

  • SSL certificate chain file: A certificate chain file is required for Tableau Desktop on the Mac and for Tableau Prep Builder on the Mac and Tableau Prep Builder on Windows. The chain file is also required for the Tableau Mobile app if the certificate chain for Tableau Server is not trusted by the iOS or Android operating system on the mobile device.

    The chain file is a concatenation of all of the certificates that form the certificate chain for the server certificate. All certificates in the file must be x509 PEM-encoded and the file must have a .crt extension (not .pem).

  • For multiple sub-domains, Tableau Server supports wildcard certificates.

  • Verify that the domain, host name, or IP address that clients use to connect to Tableau Server is included in the Subject Alternative Names (SAN) field. Many clients (Tableau Prep, Chrome and Firefox browsers, etc) require valid entry in the SAN field to establish a secure connection.

Note: If you plan to configure Tableau Server for single-sign on using SAML, see Using SSL certificate and key files for SAML in the SAML requirements to help determine whether to use the same certificate files for both SSL and SAML.

Configuring SSL for a Cluster

You can configure a Tableau Server cluster to use SSL. If the initial node is the only one running the gateway process (which it does by default), you need to configure SSL only on that node, using the steps described in this topic.

SSL with multiple gateways

A highly available Tableau Server cluster can include multiple gateways, fronted by a load balancer. If you are configuring this type of cluster for SSL, you have the following choices:

  • Configure the load balancer for SSL: Traffic is encrypted from the client web browsers to the load balancer. Traffic from the load balancer to the Tableau Server gateway processes is not encrypted. No SSL configuration in Tableau Server is required by you. It’s all handled by the load balancer.

  • Configure Tableau Server for SSL: Traffic is encrypted from the client web browsers to the load balancer, and from the load balancer to the Tableau Server gateway processes. For more information, continue to the following section.

Additional configuration information for Tableau Server cluster environments

When you want to use SSL on all Tableau Server nodes that run a gateway process, you complete the following steps.

  1. Configure the external load balancer for SSL passthrough.

    Or if you want to use a port other than 443, you can configure the external load balancer to terminate the non-standard port from the client. In this scenario, you would then configure the load balancer to connect to Tableau Server over port 443. For assistance, refer to the documentation provided for the load balancer.

  2. Make sure the SSL certificate is issued for the load balancer’s host name.

  3. Configure the initial Tableau Server node for SSL.

  4. If you are using mutual SSL, upload the SSL CA certificate file. See tsm authentication mutual-ssl <commands>.

SSL certificate and key files will be distributed to each node as part of the configuration process.

Prepare the environment

When you get the certificate files from the CA, save them to a location accessible by Tableau Server, and note the names of the certificate .crt and .key files and the location where you save them. You will need to provide this information to Tableau Server when you enable SSL.

Configure SSL on Tableau Server

Use the method you’re most comfortable with.

  1. Open TSM in a browser:

    https://<tsm-computer-name>:8850. For more information, see Sign in to Tableau Services Manager Web UI.

  2. On the Configuration tab, select Security > External SSL.

    Note: If you are updating or changing an existing configuration, click Reset to clear the existing settings before proceeding.

  3. Under External web server SSL, select Enable SSL for server communication.

  4. Upload the certificate and key files, and if required for your environment, upload the chain file and enter the passphrase key:

    Configure SSL screenshot

    If you are running Tableau Server in a distributed deployment, then these files will be automatically distributed to each appropriate node in the cluster.

  5. Click Save Pending Changes.

  6. Click Pending Changes at the top of the page:

  7. Click Apply Changes and Restart.

After you have copied the certificate files to the local computer, run the following commands:

tsm security external-ssl enable --cert-file <path-to-file.crt> --key-file <path-to-file.key>

tsm pending-changes apply

See the command reference at tsm security external-ssl enable to determine whether you want to include additional options for external-ssl enable. Tableau has specific recommendations for the --protocols option.

The external-ssl enable command imports the information from the .crt and .key files. If you run this command on a node in a Tableau Server cluster, it also distributes the information to any other gateway node.

If the pending changes require a server restart, the pending-changes apply command will display a prompt to let you know a restart will occur. This prompt displays even if the server is stopped, but in that case, there is no restart. You can suppress the prompt using the --ignore-prompt option, but this does not change the restart behaviour. If the changes do not require a restart, the changes are applied without a prompt. For more information, see tsm pending-changes apply.

Port redirection and logging

After the server has been configured for SSL, it accepts requests to the non-SSL port (default is port 80) and automatically redirects to the SSL port 443.

Note: Tableau Server supports only port 443 as the secure port. It cannot run on a computer where another application is using port 443.

SSL errors are logged in the at the following location. Use this log to troubleshoot validation and encryption issues:

\ProgramData\Tableau\Tableau Server\data\tabsvc\logs\httpd\error.log

Change or update SSL certificate

After you have configured SSL, you may need to periodically update the certificate. In some cases, you may need change the certificate for operational changes in your IT environment. In either case, you must use TSM to replace the SSL certificate that has already been configured for external SSL.

Do not copy a new certificate to the file directory on the operating system. Rather, when you add the certificate with either the TSM web UI or the tsm security external-ssl enable command, the certificate file is copied to the appropriate certificate store. In a distributed deployment, the certificate is also copied across the nodes in the cluster.

To change or update the SSL certificate (and the corresponding key file if required), follow the steps in the previous section of this topic, Configure SSL on Tableau Server.

After you change the certificate, you must run tsm pending-changes apply to restart Tableau Server services. We also recommend restarting any other services on the computer that use the SSL certificate. If you are changing a root certificate on the operating system, you must reboot the computer.

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