Configure Encrypted Channel to LDAP External Identity Store

Tableau Server that is configured to connect to an external LDAP identity store must query the LDAP directory and establish a session. The process of establishing a session is called binding. There are multiple ways to bind. Tableau Server supports two methods of binding to an LDAP directory:

  • Simple bind: Establishes a session by authenticating with a username and password. By default, Tableau Server will attempt StartTLS to encrypt sessions when connecting to Windows Active Directory. If Tableau Server has a valid TLS certificate, then the session will be encrypted. Otherwise, LDAP with simple bind is not encrypted. If you are configuring LDAP with simple bind, we strongly recommend that you enable LDAP over SSL/TLS.

  • GSSAPI bind. GSSAPI uses Kerberos to authenticate. When configured with a keytab file, authentication is secure during GSSAPI bind. However, subsequent traffic to the LDAP server is not encrypted. We recommend configuring LDAP over SSL/TLS . StartTLS is not supported for GSSAPI bind with Active Directory.

    If you are running Tableau Server on Linux on a computer that is joined to an Active Directory domain, you can configure GSAPI. See LDAP with GSSAPI (Kerberos) bind.

This topic describes how to encrypt the channel for simple LDAP bind for communications between Tableau Server and LDAP directory servers.

Certificate requirements

You must have a valid SSL/TLS certificate that can be used for encryption. The certificate must be installed on the computer(s) running Tableau Server.

The certificate you install must include Key Encipherment in the key usage field to be used for SSL/TLS. Tableau Server will only use this certificate for encrypting the channel to the LDAP server. The expiry, trust, and CRL and other attributes are not validated.

Note: If you are running Tableau Server in a distributed deployment, then you must manually copy the SSL certificate to each node in the cluster. Copy the certificate only to those nodes where the Tableau Server Application Server process is configured. Unlike other shared files in a cluster environment, the SSL certificate used for LDAP will not be automatically distributed by the Client File Service.

Importing certificate into the Tableau keystore

If you do not have certificates already in place on your computer that are configured for the LDAP server then you must obtain a SSL certificate for the LDAP server and import it into the Tableau system keystore.

Use the "keytool" Java tool to import certificates. In a default installation, this tool is installed with Tableau Server at /opt/tableau/tableau_server/packages/repository.<installer version>/jre/bin/keytool.

The following command (for RHEL-like distributions) imports the certificate:

sudo "$PROGRAMFOLDER"/packages/repository*/jre/bin/keytool -importcert -file "$CERTSDIR" -alias "$OPENLDAPSSLSERVER" -keystore /etc/opt/tableau/tableau_server/tableauservicesmanagerca.jks -storepass changeit -noprompt

The password for the Java keystore is changeit. (Do not change the password for the Java keystore).

Encryption methods

Tableau Server 2021.1 and newer supports two methods for encrypting the LDAP channel for simple bind:

  • StartTLS: Beginning with Tableau Server 2021.1, StartTLS is supported for simple bind LDAP connections to Active Directory.

    Note: StartTLS is only supported on Tableau Server on Linux when communicating with Active Directory. StartTLS is not supported for communication with other LDAP server types.

    The StartTLS method works by establishing an insecure connection with the Active Directory server. After a client-server negotiation, the connection is upgraded to a TLS encrypted connection. This scenario requires a valid TLS certificate on Tableau Server.

  • LDAPS: Secure LDAP, or LDAPS, is a standard encrypted channel that requires more configuration. Specifically, in addition to a TLS certificate on Tableau Server, you must set the host name and the secure LDAP port for the target LDAP server.

    LDAPS is supported on any LDAP server, including Active Directory servers.

Configuring encrypted channel for simple bind

This section describes how to configure Tableau Server to use an encrypted channel for LDAP simple bind.

New installations of Tableau Server

If your organization uses an LDAP directory other than Active Directory, then you cannot use the TSM GUI Setup to configure the identity store as part of Tableau Server installation. Instead, you must use JSON entity files to configure the LDAP identity store. See identityStore Entity,

Before you configure the identityStore entity, import a valid SSL/TLS certificate into the Tableau key store as documented earlier in this topic.

Configuring LDAPS requires setting the hostname and sslPort options in the identityStore JSON file.

New installations in an Active Directory environment

If you are using Active Directory as an external identity store, you must run the GUI version of Tableau Server Setup. Unlike the CLI process for installing Tableau Server, the GUI version of Setup includes logic to simplify and validate Active Directory configuration.

The Tableau Server Setup GUI where you configure Active Directory is shown here.

If you are installing a new instance of Tableau Server on Linux and you have a valid SSL/TLS certificate installed in the Tableau keystore, we recommend that you set the encryption method to LDAP over StartTLS.

If you want to configure for LDAPS, then enter the hostname and secure port (typically 636) for the LDAP server, before selecting the LDAPS option.

You can make changes to these configurations after you install by signing into TSM Web UI, clicking the Configuration tab, User Identity & Access, and then Identity Store.

Error messages

The following error messages may be displayed or logged. If you see these errors

  • Verify that your certificate is valid and imported to the Tableau key store as described earlier in this topic.
  • (LDAPS only) - Verify that the host and port name is correct.

Setup GUI

The following error will be displayed if you have misconfigured LDAPS or StartTLS when running the Setup or Upgrade GUI.

TLS handshake failed. Tableau Server and the Active Directory server could not negotiate a compatible level of security.

Vizportal logs

If you are configuring LDAPS or StartTLS using CLI, the following error message will not be displayed. Rather, the error will be logged in the vizportal logs at /var/opt/tableau/tableau_server/data/tabsvc/logs/vizportal.

Authentication with LDAP server failed. The provided credentials or configuration are either incorrect or do not have the necessary permissions to bind.
Thanks for your feedback!