Configure Mutual SSL Authentication

Using mutual SSL, you can provide users of Tableau Desktop, Tableau Mobile, and other approved Tableau clients a secure, direct-access experience to Tableau Server. With mutual SSL, when a client with a valid SSL certificate connects to Tableau Server, Tableau Server confirms the existence of the client certificate and authenticates the user, based on the user name in the client certificate. If the client does not have a valid SSL certificate, Tableau Server can refuse the connection. You can also configure Tableau Server to fall back to username/password authentication if mutual SSL fails.

As part of your disaster recovery plan, we recommend keeping a backup of the certificate and revocation (if applicable) files in a safe location off of the Tableau Server. The certificate and revocation files that you add to Tableau Server will be stored and distributed to other nodes by the Client File Service. However, the files are not stored in a recoverable format. See Tableau Server Client File Service.

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

  2. Open TSM in a browser:

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

  3. On the Configuration tab, select User Identity & Access > Authentication Method.

  4. Under Authentication Method, select Mutual SSL in the drop-down menu.

  5. Under Mutual SSL, select Use mutual SSL and automatic sign in with client certificates.

  6. Click Select File and upload your certificate authority (CA) issued certificate to the server.

    This certificate must be a valid PEM-encoded x509 certificate with the extension .crt.

  7. Enter remaining SSL configuration information for your organisation.

    Username format: When Tableau Server is configured for mutual SSL, the server gets the user name from the client certificate, so it can establish a direct sign-in for the client user. The name that Tableau Server uses depends on how Tableau Server is configured for user authentication:

    • Local Authentication – Tableau Server uses the UPN (User Principal Name) from the certificate.
    • Active Directory (AD) – Tableau Server uses LDAP (Lightweight Directory Access Protocol) to get the user name.

    Alternatively, you can set Tableau Server to use the CN (Common Name) from the client certificate.

    Configure mutual SSL screenshot

  8. Click Save Pending Changes after you've entered your configuration information.

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

  10. Click Apply Changes and Restart.

Step 1: Require SSL for external server communication

To configure Tableau Server to use SSL for external communication between Tableau Server and web clients, run the external-ssl enable command as follows, providing the names for the server certificate’s .crt and .key files:

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

  • For --cert-file and --key-file, specify the location and file name where you saved the server’s CA-issued SSL certificate (.crt) and key (.key) files.

  • The above command assumes the you are signed in as a user that has the Server Administrator site role on Tableau Server. You can instead use the -u and -p parameters to specify an administrator user and password.

  • If the certificate key file requires a passphrase, include the --passphrase parameter and value.

Step 2: Use mutual SSL

Add mutual authentication between the server and each client, and allow for Tableau client users to be authenticated directly after the first time they provide their credentials.

  1. Run the following command:

    tsm authentication mutual-ssl configure --cert-file <file.crt>

    For --cert-file, specify the location and file name of the server’s CA certificate (.crt) file, as in the previous step for external SSL.

    See the remaining sections in this article for any additional options you might want to include with the mutual-ssl configure command.

  2. Run the following commands to enable mutal SSL and apply the changes:

    tsm authentication mutual-ssl enable

    tsm pending-changes apply

    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.

Additional options for mutual SSL

You can use mutual-ssl configure to configure Tableau Server to support the following options.

For more information, see tsm authentication mutual-ssl <commands>.

Fallback authentication

When Tableau Server is configured for mutual SSL, authentication is automatic and clients must have a valid certificate. You can configure Tableau Server to allow a fallback option, to accept user name and password authentication.

tsm authentication mutual-ssl configure -fb true

Tableau Serer accepts username and password authentication from REST API clients, even if the above option is set to false.

User name mapping

When Tableau Server is configured for mutual SSL, the server authenticates the user directly by getting the user name from their client certificate. The name that Tableau Server uses depends on how the server is configured for user authentication:

  • Local Authentication – uses the UPN (User Principal Name) from the certificate.

  • Active Directory (AD) – uses LDAP (Lightweight Directory Access Protocol) to get the user name.

You can override either of these defaults to set Tableau Server to use the common name.

tsm authentication mutual-ssl configure -m cn

For more information, see Mapping a Client Certificate to a User During Mutual Authentication

Certificate Revocation List (CRL)

You might need to specify a CRL if you suspect that a private key has been compromised, or if a certificate authority (CA) did not issue a certificate properly.

tsm authentication mutual-ssl configure -rf <revoke-file.pem>

Thanks for your feedback!