Configure SSL for JDBC Connections

Applies to: Tableau Desktop

Many JDBC connectors support one-way (standard) SSL, and some support two-way SSL. For those that don’t have explicit support using Tableau, you may be able to enable it with customization. There are different ways that SSL can be configured for both types, and you can use the method that makes the most sense for your environment.

Note: For Tableau Cloud, if your server certificate is not signed by a common public root CA, and you don't have the option to embed the certificate, you can use Tableau Bridge. This will allow you to configure certificates and private keys as needed.

One-Way SSL for JDBC Connections

If you are using regular (one-way) SSL with a JDBC based connector, and you have self-signed certificates, or certificates that are signed by a non-public certificate authority (CA), then you will need to configure trust for your certificate.

With Tableau, you can configure one-way SSL trust for JDBC connections using one of these methods:

Embed a certificate

Some connectors support embedding the certificate in the workbook or data source. If that is available, then you can use Tableau Desktop to embed the CA certificate.

Install a certificate in the system trust store

If embedding is not available, you will need another way to configure trust. Also, it may be easier to do this than to embed the certificate in every workbook. Instructions are included for Windows, Mac, and Linux platforms below.

The default trust store location for Tableau Server is:

/opt/tableau/tableau_server/packages/repository.20233.24.0514.1218/jre/lib/security/cacerts

For Windows:

You can install your CA or self-signed certificate in the Windows root CA trust store. The Java Runtime looks for trusted CAs in the system root trust store. It does not look in the intermediate certificate storage.

Note: If you have installed your root CA, but are still having trouble making connections, it may be caused by missing intermediate certificates. While the TLS standard requires that servers send all certificates in their chain except the root certificate, not all servers are compliant. If your server doesn’t send the intermediate certificates, you can either fix the server to properly forward intermediate certificates or install the intermediate certificates in the root trust store. Alternatively, you could choose to embed certificates in the data source or configure a trust store with driver properties.

  1. In Windows, search for "certificates".
  2. Select Manage computer certificates.
  3. From the Action menu, select All Tasks, and then, depending on Windows version, do one of the following:
    • Select Import and then select Local Machine.
    • Select Find Certificates.
  4. Browser to find your certificate file.
  5. Import into "Trusted Root Certificate Authorities".

For Mac:

To install a custom certificate on a Mac, follow these steps to import the certificate into the "System" keychain.

Note: Loading certificates from keychain on Mac works for most, but not all, drivers. For other drivers, you may need to use a .properties file to configure the trust store. For more information, see Customize and Tune Connections.

  1. Go to https://support.apple.com/guide/keychain-access/add-certificates-to-a-keychain-kyca2431/mac(Link opens in a new window).
  2. Import the certificate into the "System" keychain (not "System Roots").
  3. Enable trust as follows:
    1. In the Keychain App, right-click the new certificate.
    2. Select Get Info.
    3. In the dialog, open the Trust section, and then select When using this certificate always trust.

For Linux:

Many Linux distributions will generate a trust store in Java format from the system certificates. You may need to install Java from the package manager for this file to be created.

This allows the JRE to use the same certificates as the operating system.

Note: Tableau Server looks for this file in the standard locations:
/etc/ssl/certs/java/cacerts
/etc/pki/java/cacerts

To configure a different location, run: 

tsm configuration set -k native_api.ConnectivityTrustStore -v <path-to-cacerts> --force-keys

This file should:

  • Contain all trusted CAs and self-signed certificates.
  • Contain only public keys.
  • Be in JKS format.
  • Be readable by the Tableau unprivileged user ("run as user").
  • Use default JKS password "changeit"

To install a custom CA or self-signed certificate, see the documentation for your distribution. Run the appropriate commands to generate the key store. For example: 

update-ca-certificates

Ubuntu configuration notes

Configuring a SSL connection on Ubuntu distributions may require extra steps to work correctly. If you cannot connect to a SQL Server, follow these instructions to configure your CA certification paths:

  1. Create a /etc/pki/tls/certs directory: sudo mkdir -p /etc/pki/tls/certs
  2. Either create a symlink to the certificate file, or copy the ca-certificates.crt file into the newly created directory and rename it ca-bundle.crt:
    • Symlink: sudo ln -s /etc/ssl/certs/ca-certificates.crt /etc/pki/tls/certs/ca-bundle.crt
    • Copy: sudo cp /etc/ssl/certs/ca-certificates.crt /etc/pki/tls/certs/ca-bundle.crt

  3. After restarting the server, try connecting again.

Use custom driver properties

You can customize JDBC connection options, including the location of the trust store, with a .properties file. This is a plain-text file containing key-value pairs for each connection parameter.

For example, lines in this properties file are being used to configure trust settings:

javax.net.ssl.trustStore=C:\\My_Folder\\truststore.jks
javax.net.ssl.trustStoreType=JKS
javax.net.ssl.trustStorePassword=password

Note: For details on specific property settings, see the documentation for your driver.

When you create the file and save it to the correct location, the properties in the file are applied to all JDBC connections to the same data source type.

If you use the generic "Other Database (JDBC)" connector, you can specify a .properties file directly in the connection dialog.

For more information, see Customize and Tune Connections(Link opens in a new window).

Two-Way SSL for JDBC Connections

Some JDBC connections, such as Postgres, can also be configured to use two-way SSL authentication. This can be configured by using a .properties file to specify the locations and details of the trust store and keys.

Use a .properties file to configure the client certificate and private key

Note: For Tableau Cloud, if you require two-way SSL and your connector doesn't have an option to embed the keys, you will need to use Tableau Bridge and set up the SSL configuration there.

  1. Modify the .properties file to reflect the key store and trust store settings. Use the following as an example. Be sure to replace “My_Folder” for the location of your files and “<password>” with your own password. Paths on OSX and Linux need only a single "/" to separate.

    javax.net.ssl.trustStore=C:\\My_Folder\\truststore.jks
    javax.net.ssl.trustStoreType=JKS
    javax.net.ssl.trustStorePassword=<password>
    javax.net.ssl.keyStore=C:\\My_Folder\\keystore.jks
    javax.net.ssl.keyStoreType=JKS
    javax.net.ssl.keyStorePassword=password

  2. Save the .properties file to the appropriate datasources folder, depending on the Tableau product. If you are unsure, see the complete list of possible directories in Customize and Tune a Connection.
  3. If you publish to Tableau Server, ensure that you install the .properties file, truststore.jks, and keystore.jks in the right locations for each Tableau Server node.

If you use this method, you don't need to upload certificates and key via the SSL dialog. Instead, simply click Require SSL. This causes the JDBC connector to read the locations of the key store and trust store from the .properties file.

Troubleshooting

Issues with using SSL often are related to incorrect certificate configuration.

One way to begin narrowing down the source of the issue is to verify what certificates are in use and where they are installed. With OpenSSL CLI tools installed, you can use the s_client command:

openssl s_client -connect hostname:port -showcerts

Replace hostname and port with the proper values for the system you are testing. When executed, this command will attempt to create an SSL connection, and then display the certificates sent from the server.

Some databases have a custom TLS handshake, and openssl supports a couple of those directly. As of the latest version those are postgres and mysql. If you are connecting to a postgres or mysql compatible database, and you have problems with the command above, you can try using the -starttls option to enable the protocol used by your database. For example:

openssl s_client -connect hostname:port -showcerts -starttls postgres

For more information about troubleshooting with OpenSSL, see Using OpenSSL s_client commands to test SSL connectivity(Link opens in a new window). You can find the full documentation for OpenSSL s_client in OpenSSL Documentation(Link opens in a new window).

See also

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