tsm security
Use the tsm security commands to configure Tableau Server support for external (gateway) SSL or repository (Postgres) SSL. Repository SSL configuration includes the option to enable SSL over direct connections from Tableau clients – including Tableau Desktop, Tableau Mobile, and web browsers – to the repository.
- tsm security custom-cert
- tsm security custom-indexandsearch-ssl
- tsm security custom-tsm-ssl
- tsm security external-ssl
- tsm security kms
- tsm security maestro-rserve-ssl
- tsm security maestro-tabpy-ssl
- tsm security regenerate-internal-tokens
- tsm security repository-ssl
- tsm security rotate-coordination-service-secrets
- As of the 2020.2 release, to configure Rserve and TabPy analytics extensions, use the Tableau Server admin pages. See Configure Connections with Analytics Extensions.
Prerequisites
Before you configure SSL, you must acquire certificates, and then copy them to the computer that runs the Tableau Server gateway process. Additional preparation is required for enabling direct connections from clients. To learn more, see the following articles:
Configure SSL for External HTTP Traffic to and from Tableau Server
Configure SSL for Internal Postgres Communication
For information about mutual (two-way) SSL, see Configure Mutual SSL Authentication and tsm authentication mutual-ssl commands.
tsm security authorise-credential-migration
Authorises a Tableau user to migrate embedded credentials from a Tableau Server installation to a Tableau Cloud site using Content Migration Tool. Both Tableau Server and Tableau Cloud must have an Advanced Management licence to migrate content. For more information, see Migrate Workbooks and Data Sources with Embedded Credentials.
You can cancel authorization using the tsm security cancel-credential-migrations command.
Synopsis
tsm security authorize-credential-migration --source-site-url-namespace <Tableau Server site ID> --destination-site-url-namespace <Tableau Cloud site ID> --destination-server-url <Tableau Cloud site url> --authorized-migration-runner <username> --destination-public-encryption-key <public key>
Options
--source-site-url-namespace
Required. Site ID of the Tableau Server site. The site ID is used in the URL to uniquely identify the site.
For example, a site named West Coast Sales might have a site ID of west-coast-sales.
--destination-site-url-namespace
Required. Site ID of the Tableau Cloud site. The site ID is used in the URL to uniquely identify the site.
--destination-server-url
Required. URL of the pod that your Tableau Cloud site is deployed to. The URL you specify must include a trailing slash (
/).Your pod is shown in the first portion of the site URL after signing in to Tableau Cloud. For example,
https://10az.online.tableau.com/is the United States - West (10AZ) pod. For more information about pods, see the Salesforce Trust(Link opens in a new window) page.--authorised-migration-runner
Required. Username of the Tableau Server user authorised to migrate embedded credentials.
--destination-public-encryption-key
Required. Specify the public key generated on the Tableau Cloud site.
--expiration-time-in-days
Optional. Number of days before authorisation expires. Default value is 7 days.
Version: Retired in version 2023.1. Beginning in 2023.1.0, this option is no longer valid and will generate an error if used. The expiry value is hard-coded as seven days.
Example
The following example authorizes user “admin” to migrate workbooks and published data sources with embedded credentials from Tableau Server site “ExampleA” to Tableau Cloud site “ExampleB”. The authorisation will expire in 9 days.
tsm security authorize-credential-migration --source-site-url-namespace ExampleA --destination-site-url-namespace ExampleB --destinationServerUrl https://10ay.online.tableau.com/ --authorized-migration-runner admin --destination-public-encryption-key <public key> --expiration-time-in-days 9
tsm security cancel-credential-migrations
Cancels granted authorisations for migrating embedded credentials using Content Migration Tool. For more information, see Migrating Workbooks and Data Sources with Embedded Credentials.
Synopsis
tsm security cancel-credential-migrations --source-site-url-namespace <Tableau Server site ID>
Options
--source-site-url-namespace
Required. Site ID of the Tableau Server site. The site ID is used in the URL to uniquely identify the site.
For example, a site named West Coast Sales might have a site ID of west-coast-sales.
tsm security custom-cert add
Adds a custom CA certificate to Tableau Server. This certificate is optionally used to establish trust for TLS communication between a SMTP server and Tableau Server.
If a custom certificate already exists, this command will fail. You can remove the existing custom certificate using the tsm security custom-cert delete command.
Note: The certificate that you add with this command may be used by other Tableau Server services for TLS connections.
As part of your disaster recovery plan, we recommend keeping a backup of the certificate file in a safe location off of the Tableau Server. The certificate file that you add to Tableau Server will be stored and distributed to other nodes by the Client File Service. However, the file is not stored in a recoverable format. See Tableau Server Client File Service.
Synopsis
tsm security custom-cert add --cert-file <file.crt> [global options]
Options
-c, --cert-file <file.crt>
Required. Specify the name of a certificate file in valid PEM or DER format.
tsm security custom-indexandsearch-ssl add
Add custom certificates for Index and Search Server for Tableau Server 2023.1 and newer. The SSL implementation is based on Opensearch.org TLS implementation. See Configuring TLS certificates(Link opens in a new window) for more information.
- --admin <file.crt>
- Required.
- Admin certificate file. Specify the path to a valid PEM-encoded x509 certificate with the extension .crt.
- --admin-key <file.key>
- Required.
- Specify the path to a valid RSA or DSA private key file (PKXA #8), with the extension .key by convention.
- -- ca <file.crt>
- Required.
- Trusted CA file. Specify the path to a valid PEM-encoded x509 certificate with the extension .crt.
- --node <file.crt>
- Required.
- Node certificate file. Specify the path to a valid PEM-encoded x509 certificate with the extension .crt. This command will distribute this certificate to each node in the cluster. Use a wild card certificate to allow the full array of node Distinguished Names (DNs) in a single certificate.
- -- node-key <file.key>
- Required.
- Specify the path to a valid RSA or DSA private key file (PKXA #8), with the extension .key by convention.
Synopsis
tsm security custom-indexandsearch-ssl add --node <file.crt> --admin
<file.crt> --node-key <file.key> --admin-key
<file.key> --ca <file.crt> [parameters]
[global options]
tsm security custom-indexandsearch-ssl list
List details of Index and Search Server SSL custom certificate configuration.
Synopsis
tsm security custom-indexandsearch-ssl list[global options]
tsm security custom-tsm-ssl disable
Disable the custom SSL certificate for connections to TSM Controller. Revert back to an automatically-managed, self-signed certificate.
Synopsis
tsm security custom-tsm-ssl disable [global options]
tsm security custom-tsm-ssl enable
Enable the custom SSL certificate for connections to TSM Controller for Tableau Server 2023.1 and newer. If you have already enabled SSL and need to update an expired certificate, use this command.
- -cf,--cert-file <file.crt>
- Required.
- Specify the path to a valid PEM-encoded x509 certificate with the extension .crt. The subject name on certificate must match host name or IP address of the Tableau computer where the Administration Controller is running. By default, the Administration Controller runs on the initial node of a Tableau Server deployment.
- -kf,--key-file <file.key>
- Required.
- Specify the path to valid RSA or DSA private key file (PKXA #8), with the extension .key by convention. This key cannot be passphrase-protected.
- --chain-file <file.crt>
- Optional.
Specify the path to a certificate chain file (.crt)
The chain file is a concatenation of all the certificates that form the certificate chain for the server certificate.
All certificates in the file must be x509 PEM-encoded and the file must have a .crt extension (not .pem).
- --skip-validation
- Optional
- Pass this option to skip certificate authority root verification.
Synopsis
tsm security custom-tsm-ssl enable --key-file <file.key> --cert-file <file.crt> [global options]
tsm security custom-tsm-ssl list
List details of TSM custom certificate configuration.
Synopsis
tsm security custom-tsm-ssl list[global options]
tsm security external-ssl disable
Removes the server’s existing SSL configuration settings and stops encrypting traffic between external clients and the server.
Synopsis
tsm security external-ssl disable [global options]
tsm security external-ssl enable
Enable and specify certificate and key files for SSL over external HTTP communication.
Synopsis
tsm security external-ssl enable --cert-file <file.crt> --key-file <file.key> [options] [global options]
Options
--cert-file <file.crt>
Required. Specify the name of a valid PEM-encoded x509 certificate with the extension .crt.
--key-file <file.key>
Required. Specify a valid RSA or DSA private key file, with the extension .key by convention.
--chain-file <chainfile.crt>
Specify the certificate chain file (.crt)
A certificate chain file is required for Tableau Desktop on the Mac. In some cases, a certificate chain file may be required for Tableau Mobile.
Some certificate providers issue two certificates for Apache. The second certificate is a chain file, which is a concatenation of all the certificates that form the certificate chain for the server certificate.
All certificates in the file must be x509 PEM-encoded and the file must have a .crt extension (not .pem).
--passphrase
Optional. Passphrase for the certificate file. The passphrase you enter will be encrypted while at rest.
Note: If you create a certificate key file with a passphrase, you cannot reuse the SSL certificate key for SAML.
--protocols <list protocols>
Optional. List the Transport Layer Security (TLS) protocol versions you want to allow or disallow.
TLS is an improved version of SSL. Tableau Server uses TLS to authenticate and encrypt connections. Accepted values include protocol versions supported by Apache. To disallow a protocol, prepend the protocol version with a minus (-) character.
Default setting:
"all, -SSLv2, -SSLv3"This default explicitly does not allow clients to use SSL v2 or SSL v3 protocols to connect to Tableau Server. However, we recommend that you also disallow TLS v1 and TLS v1.1.
Before you deny a specific version of TLS, verify that the browsers from which your users connect to Tableau Server support TLS v1.2. You might need to preserve support for TLSv1.1 until browsers are updated.
If you do not need to support TLS v1 or v1.1, use the following command to allow TLS v1.2 (using the value
all), and explicitly deny SSL v2, SSL v3, TLS v1, and TLS v1.1.tsm security external-ssl enable --cert-file file.crt --key-file file.key --protocols "all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1"
tsm security external-ssl list
Displays a list of settings related to the configuration of gateway external SSL. The list includes the names of the certificate files in use, but not their location.
Synopsis
tsm security external-ssl list [global options]
tsm security kms set-mode aws
Set the KMS mode to AWS.
You will need the full ARN string from AWS KMS. This string is in the "General configuration" section of the AWS KMS management pages. The ARN is presented in this format: arn:aws:kms:<region>:<account>:key/<CMK_ID>, for example, arn:aws:kms:us-west-2:867530990073:key/1abc23de-fg45-6hij-7k89-1l0mn1234567.
For more information, see AWS Key Management System.
Synopsis
tsm security kms set-mode aws --key-arn "<arn>" --aws-region "<region>" [global options]
Options
--key-arn
Required. The
--key-arnoption takes a direct string copy from the ARN in the "General configuration" section of the AWS KMS management pages.--aws-region
Required. Specify a region as shown in the Region column in the Amazon API Gateway table(Link opens in a new window).
Example
For example, if your AWS KMS instance is running in us-west-2 region, your account number is 867530990073, and your CMK key is 1abc23de-fg45-6hij-7k89-1l0mn1234567, then the command would be:
tsm security kms set-mode aws --aws-region "us-west-2" --key-arn "arn:aws:kms:us-west-2:867530990073:key/1abc23de-fg45-6hij-7k89-1l0mn1234567"
tsm security kms set-mode azure
Set the KMS mode to Azure Key Vault.
Note: The KMS mode will display as "Azure Key Vault" when you run tsm security kms status, but you set it as "azure".
You will need the name of the Azure key vault and the name of the key in Azure.
For more information, see Azure Key Vault.
Synopsis
tsm security kms set-mode azure --key-name "<key_name>" --vault-name "<vault_name>" [global options]
Options
--key-name
Required. The name of the asymmetric key stored in the Azure Key Vault.
--vault-name
Required. Name of the Azure Key Vault.
Example
For example, if your Azure Key Vault is named tabsrv-keyvault and your key is tabsrv-sandbox-key01, then the command would be:
tsm security kms set-mode azure --key-name "tabsrv-sandbox-key01" --vault-name "tabsrv-keyvault"
tsm security kms set-mode local
Set or reset the KMS mode to local. Local is the default KMS mode. For more information, see Tableau Server Key Management System.
Synopsis
tsm security kms set-mode local [global options]
tsm security kms status
View the status of KMS configuration. The status returned includes:
- Status: OK indicates that the KMS is accessible by Tableau, or by the controller node if a multi-node installation.
- Mode: Local, AWS or Azure Key Vault. Indicates what KMS mode is being used.
Encrypt and decrypt master encryption key:
KMS stores a collection of master extract keys (MEKs). Each MEK has:
- An ID, for example, 8ddd70df-be67-4dbf-9c35-1f0aa2421521
- Either a “encrypt or decrypt key” or “decrypt-only key” status. If a key is "encrypt or decrypt", Tableau Server will encrypt new data with it. Otherwise, the key will only be used for decryption
- A creation timestamp, for example, "Created at: 2019-05-29T23:46:54Z."
- First transition to encrypt and decrypt: a timestamp indicating when the key became an encrypt or decrypt key.
- Transition to decrypt-only: a timestamp indicating when the key transitioned to decrypt-only.
Other values returned depend on the KMS mode.
When the KMS mode is AWS, the following is returned:
- The ARN (ID) of the customer master key (CMK) .
- The region the CMK is in.
- The ID of the root master key (RMK) in use. The RMK is a key that is encrypted by the CMK. Tableau Server decrypts the CMK by making calls to AWS KMS. The RMK is then used to encrypt/decrypt the master extract key (MEK). The RMK can change, but there will be only one at a time.
When the KMS mode is Azure Key Vault, the following is returned:
- Vault name: The name of the Azure key vault.
- Azure Key Vault key name: The name of the key in the vault.
Synopsis
tsm security kms status [global options]
tsm security maestro-rserve-ssl disable
Disable the Rserve connection.
For more information, see Use R (Rserve) scripts in your flow.
tsm security maestro-rserve-ssl enable
Configure a connection between an Rserve server and Tableau Server version 2019.3 or later.
For more information, see Use R (Rserve) scripts in your flow.
Synopsis
tsm security maestro-rserve-ssl enable --connection-type <maestro-rserve-secure | maestro-rserve> --rserve-host <Rserve IP address or host name> --rserve-port <Rserve port> --rserve-username <Rserve username> --rserve-password <Rserve password> --rserve-connect-timeout-ms <RServe connect timeout>
Options
--connection-type
Select
maestro-rserve-secureto enable a secure connection ormaestro-rserveto enable an unsecured connection. If you selectmaestro-rserve-secure, specify the certificate file path in the command line.--rserve-host
Host
--rserve-port
- Port
--rserve-username
- Username
--rserve-password
- Password
--rserve-connect-timeout-ms
- The connect timeout in milliseconds. For example
--rserve-connect-timeout-ms 900000.
tsm security maestro-tabpy-ssl disable
Disable the TabPy connection.
For more information, see Use Python scripts in your flow.
tsm security maestro-tabpy-ssl enable
Configure a connection between a TabPy server and Tableau Server version 2019.3 or later.
For more information, see Use Python scripts in your flow.
Synopsis
tsm security maestro-tabpy-ssl enable --connection-type <maestro-tabpy-secure | maestro-tabpy> --tabpy-host <TabPy IP address or host name> --tabpy-port <TabPy port> --tabpy-username <TabPy username> --tabpy-password <TabPy password> --tabpy-connect-timeout-ms <TabPy connect timeout>
Options
--connection-type
Select
maestro-tabpy-secureto enable a secure connection ormaestro-tabpyto enable an unsecured connection. If you selectmaestro-tabpy-secure, specify the certificate file -cf<certificate file path> in the command line.--tabpy-host
Host
--tabpy-port
- Port
--tabpy-username
- Username
--tabpy-password
- Password
--tabpy-connect-timeout-ms
- The connect timeout in milliseconds. For example
--tabpy-connect-timeout-ms 900000.
tsm security regenerate-internal-tokens
This command performs the following operations:
Stops Tableau Server if it is running.
Generates new internal SSL certificates for Postgres repository the search server.
Generates new passwords for all of the internally managed passwords.
Updates all Postgres repository passwords.
Generates a new encryption key for asset key management and encrypts the asset key data with the new key.
Generates a new encryption key for configuration secrets (master key) and encrypts the configuration with it.
Reconfigures and updates Tableau Server with all of these secrets. In a distributed deployment, this command also distributes the reconfiguration and updates across all nodes in the cluster.
Regenerates a new master key, adds it to the master keystore file, and then creates new security tokens for internal use.
Starts Tableau Server.
If you plan to add a node to your cluster after you have run this command, then you will need to generate a new node configuration file to update the tokens, keys, and secrets that are generated by this command. See Install and Configure Additional Nodes.
For more information about internal passwords see Manage Server Secrets.
Synopsis
tsm security regenerate-internal-tokens [options] [global options]
Options
--ignore-prompt
Optional.
Perform a restart (if necessary) without prompting. This option only suppresses the prompt. The restart behaviour is unchanged.
--request-timeout <timeout in seconds>
Optional.
Wait the specified amount of time for the command to finish. Default value is 1800 (30 minutes).
tsm security repository-ssl disable
Stop encrypting traffic between the repository and other server components, and stop support for direct connections from Tableau clients.
Synopsis
tsm security repository-ssl disable [global-options]
tsm security repository-ssl enable
When the repository is local, it enables SSL and generates the server’s .crt and .key files used for encrypted traffic between the Postgres repository and other server components.
Starting in version 2021.4, when using an external repository, imports the server's .crt and 'key files used to encrypt traffic between external PostgreSQL repository and Tableau Server components.
Enabling this also gives you the option to enable SSL over direct connections from Tableau clients to the server.
Synopsis
tsm security repository-ssl enable [options] [global options]
Options
-i, --internal-only
Optional. This option only applies when the repository is local to Tableau Server and is not configured externally to Tableau Server. This option should not be used for Tableau Server configured with External Repository.
When set to
--internal-only, Tableau Server uses SSL between the repository and other server components, and it supports but does not require SSL for direct connections through tableau or readonly users.If this option is not set, Tableau Server requires SSL for traffic between the repository and other server components, as well as for direct connections from Tableau clients (for connections through the tableau or readonly users).
When you specify this option, you must also complete the steps described in Configure Postgres SSL to Allow Direct Connections from Clients.
-c, --certificate
Optional. Added in version 2021.4. This option is only applicable to Tableau Server configured with External Repository and can be used to enable or disable SSL connections post installation.
This option allows you to enable the use of SSL/TSL connections between Tableau Server and the External Repository. When using this option, provide the full path to the SSL certificate file including the file name for the External Repository. This file is the same as the one used when enabling the external repository.
tsm security repository-ssl get-certificate-file
Get the public certificate file used for SSL communication with the Tableau repository. SSL must be enabled for repository communication before you can retrieve a certificate. The certificate file is distributed automatically to internal clients of the repository in the Tableau Server cluster. To enable remote clients to connect over SSL to the repository, you must copy the public certificate file to each client.
This command works only for Tableau Server that uses a local Repository and will result in an error when Tableau Server is configured with an External Repository.
Synopsis
tsm security repository-ssl get-certificate-file [global-options]
Options
-f, --file
Required.
Full path and file name (with .cert extension) where the certificate file should be saved. If a duplicate file exists it will be overwritten.
tsm security repository-ssl list
Returns the existing repository (Postgres) SSL configuration.
Synopsis
tsm security repository-ssl list [global-options]
tsm security rotate-coordination-service-secrets
Version: Added in version 2022.1
Generates new certificates, keys and trust stores used by the Coordination Service for secure connections.
Synopsis
tsm security rotate-coordination-service-secrets [options][global options]
Options
--coord-svc-restart-timeout <seconds>
Optional.
Wait the specified number of seconds for Coordination Service to restart. Default: 1200 (20 minutes).
--ignore-prompt
Optional.
Perform a restart (if necessary) without prompting.
--request-timeout <seconds>
Optional.
Wait the specified number of seconds for the command to finish. Default: 1800 (30 minutes).
Global options
-h, --help
Optional.
Show the command help.
-p, --password <password>
Required, along with
-uor--usernameif no session is active.Specify the password for the user specified in
-uor--username.If the password includes spaces or special characters, enclose it in quotes:
--password "my password"-s, --server https://<hostname>:8850
Optional.
Use the specified address for Tableau Services Manager. The URL must start with
https, include port 8850, and use the server name not the IP address. For examplehttps://<tsm_hostname>:8850. If no server is specified,https://<localhost | dnsname>:8850is assumed.--trust-admin-controller-cert
Optional.
Use this flag to trust the self-signed certificate on the TSM controller. For more information about certificate trust and CLI connections, see Connecting TSM clients.
-u, --username <user>
Required if no session is active, along with
-por--password.Specify a user account. If you do not include this option, the command is run using credentials you signed in with.