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 . Important: 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 GSSAPI. 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 PEM-encoded x509 SSL/TLS certificate that can be used for encryption. The certificate file must have an extension .crt.

  • Self-signed certificates are not supported.

  • 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.

  • 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.

  • If you are using a PKI or non-3rd party certificate, upload the CA root certificate to the Java trust store.

Import 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 in the following location:

/opt/tableau/tableau_server/packages/repository.<installer version>/jre/bin/keytool.

The following command imports the certificate:

sudo "<installation_directory>/packages/repository*/jre/bin/keytool -importcert -file "<cert_directory/<cert_name.crt>" -alias "<cert_alias>" -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 and LDAPS.

  • StartTLS: This is the default configuration for communicating with Active Directory in Tableau Server 2021.2. Beginning with Tableau Server 2021.2, TLS is enforced for simple bind LDAP connections to Active Directory. This default TLS configuration is enforced for both new installations and for upgrade scenarios.

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

    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. As the default configuration, this scenario only requires a valid TLS certificate on Tableau Server. No other configuration is required.

  • 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.

Configure encrypted channel for simple bind

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

When to configure

You must configure Tableau Server to use an encrypted channel for LDAP simple bind before Tableau Server is initialized or as part of configuring the initial node as mentioned in the “Use the TSM CLI” tab in Configure Initial Node Settings.

For 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.

For 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 leave the default option set to 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.

Upgrade scenarios

If you are upgrading to a 2021.2 (or newer) version of Tableau Server and using Active Directory as your external identity store, then the encrypted channel is enforced for LDAP simple bind connections. If you do not have an encrypted channel configured, then upgrade will fail.

To successfully upgrade to version 2021.2 or newer, one of the following must be true:

  • The existing Tableau Server installation has already been configured for LDAPS and includes a certificate in the Tableau key store.
  • A valid SSL/TLS certificate is present in the Tableau key store prior to upgrading. In this scenario, the default StartTLS configuration will enable an encrypted channel.
  • The encrypted LDAP channel has been disabled as described in the following section.

Disable default encrypted LDAP channel

If you are running Tableau Server on Linux and connecting to Active Directory, you can disable the encrypted channel requirement.

When disabled, user credentials that are used to establish the bind session with Active Directory are communicated in plaintext between Tableau Server and the Active Directory server.

Disable new installation

If you will be using Active Directory as your identity store, then you must use the TSM GUI to configure the Active Directory connection. See Configure Initial Node Settings.

Select LDAP (unencrypted channel) when running Setup.

Disable before upgrading

If you are upgrading to Tableau Server 2021.2 (or newer) from an earlier version, run the following commands on earlier version of Tableau Server before you upgrade:

tsm configuration set -k wgserver.domain.ldap.starttls.enabled -v false --force-keys
tsm pending-changes apply

To verify that the key has been set, run the following command:

tsm configuration get -k wgserver.domain.ldap.starttls.enabled

The command should return false.

Error messages

The following error messages may be displayed or logged. If you see these errors, do the following:

  • 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.

In the 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!Your feedback has been successfully submitted. Thank you!