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.  Additionally, a user can log in using the REST API with a username and password (if one exists) whether or not fallback authentication is configured.

User authentication session time limits

When users log in with mutual SSL, the authentication session is governed by the same method that governs the Tableau Server global authentication session configuration.

For clients that connect to Tableau Server using a web browser, configuration of the global authentication session is described in the Security Hardening Checklist, see 10. Verify session lifetime configuration.

Sessions for connected clients (Tableau Desktop, Tableau Mobile, Tableau Prep Builder, and Bridge) use OAuth tokens to keep users logged in by re-establishing a session. By default, OAuth client tokens reset after a year. If a client token has not been used in 14 days, then it will expire. You can change these values by setting the refresh_token.absolute_expiry_in_seconds and refresh_token.idle_expiry_in_seconds options. See tsm configuration set Options.

Certificate usage

Before you enable and configure mutual SSL, you must configure external SSL. External SSL authenticates Tableau Server to the client and encrypts the session using the certificate and key that is required when you configure external SSL.

For mutual SSL, an additional certificate file is required. The file is a concatenation of CA certificate files. The file type must be .crt. A "CA" is a certificate authority that issues certificates to the client computers that will connect to Tableau Server. The action of uploading the CA certificate file establishes a trust, which enables Tableau Server to authenticate the individual certificates that are presented by the client computers.

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.

RSA key and ECDSA curve sizes

The CA certificate used for mutual SSL must either have an RSA key strength of 2048, or ECDSA curve size of 256.

.You can configure Tableau Server to accept the less-secure sizes by setting the respective configuration keys:

  • ssl.client_certificate_login.min_allowed.rsa_key_size
  • ssl.client_certificate_login.min_allowed.elliptic_curve_size

See tsm configuration set Options.

Client certificate requirements

Users authenticating to Tableau Server with mutual SSL must present a client certificate that meets minimum security requirements.

Signing algorithm

Client certificates must use a SHA-256 or greater signing algorithm.

Tableau Server configured for mutual SSL authentication will block authentication of users with client certificates that use the SHA-1 signing algorithm.

Users who attempt to log in with SHA-1 client certificates encounter an "Unable to sign in" error, and the following error will be visible in the VizPortal logs:

Unsupported client certificate signature detected: [certificate Signature Algorithm name]

You can configure Tableau Server to accept the less secure SHA-1 signing algorithm by setting the ssl.client_certificate_login.blocklisted_signature_algorithms tsm configuration option.

RSA key and ECDSA curve sizes

The client certificate used for mutual SSL must either have an RSA key strength of 2048, or ECDSA curve size of 256.

Tableau Server will fail mutual authentication requests from client certificates that do not meet these requirements. You can configure Tableau Server to accept the less-secure sizes by setting the respective configuration keys:

  • ssl.client_certificate_login.min_allowed.rsa_key_size
  • ssl.client_certificate_login.min_allowed.elliptic_curve_size

See tsm configuration set Options.

  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) certificate file to the server.

    The file (.crt) is an all-in-one file that includes certificates of CAs that are used for client authentication. The file you upload must be a concatenation of the various PEM-encoded certificate files, in order of preference.

  7. Enter remaining SSL configuration information for your organization.

    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: Configure and enable 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 --ca-cert <certificate-file.crt>

    For --ca-cert, specify the location and file name of the certificate authority (CA) certificate file.

    The file (.crt) is an all-in-one file that includes certificates of CAs that are used for client authentication. The file you upload must be a concatenation of the various PEM-encoded certificate files, in order of preference.

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

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