Configure Server-Wide SAML

Configure server-wide SAML when you want all single sign-on (SSO) users on Tableau Server to authenticate through a single SAML identity provider (IdP), or as the first step to configuring site-specific SAML in a multi-site environment.

If you have configured server-wide SAML and are ready to configure a site, see Configure Site-Specific SAML.

The SAML configuration steps we provide make the following assumptions:

  • You are familiar with the options for configuring SAML authentication on Tableau Server, as described in the SAML.

  • You have verified that your environment meets the SAML Requirements, and obtained the SAML certificate files described in those requirements.

SAML configuration overview

To configure SAML for Tableau Server, you complete the following sets of steps.

  1. Put certificate and IdP metadata files in place — This section includes information for configuring SAML for a Tableau Server cluster.

  2. Choose the SAML configuration method — Here you can get the steps for the configuration method you’re most comfortable with: Tableau Services Manager (TSM) web UI, TSM CLI, or samlSettings entity with JSON file.

  3. Generate Tableau Server metadata and configure the IdP — Add Tableau Server as a Service Provider.

  4. Test the configuration — Sign in to the Tableau Server web UI.

Put certificate and IdP metadata files in place

In this phase, you gather files you’ll need for the SAML configuration into the designated location on the Tableau Server computer. These files include:

  • Copies of the SAML certificate and key files.

    To review the certificate file requirements again, see SAML Requirements.

  • If you want to configure SAML using the TSM CLI or samlSettings entity, you also will obtain the IdP’s metadata XML file.

    If you plan to Configure SAML Using the TSM Web UI, you will get IdP metadata when you go through the steps in the UI.

Gather the certificate and metadata files

  1. In the Tableau Server folder, create a new folder named SAML, and place copies of the SAML certificate files in that folder. For example:

    /var/opt/tableau/tableau_server/data/saml

    (Keep the certificate files in a safe location outside of the Tableau Server directory tree as well.)

    Note: If you use the same certificate files for SSL, you could alternatively use the existing certificate location for configuring SAML, and add the IdP metadata file to that directory when you download it later in this procedure. For more information, see Using SSL certificate and key files for SAML in the SAML requirements.

    If you are running Tableau Server in a cluster, then the SAML certificates, keys, and metadata file will be automatically distributed across the nodes when you enable SAML.

  2. Do one of the following:

    If you plan to configure SAML in the TSM web UI, skip this step. You will complete it as you go through the UI steps.

    If you plan to configure SAML using the TSM CLI or TSM samlSettings entity, go to the IdP’s website or application, and export the IdP’s metadata XML file.

    Confirm that the metadata XML from the IdP includes a SingleSignOnService element, in which the binding is set to HTTP-POST, as in the following example:

    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://SERVER-NAME:9031/idp/SSO.saml2"/>

Choose the SAML configuration method

You have the following options for configuring server-wide SAML:

Use the samlSettings entity with a configuration file

The TSM entities use JSON and key-value pairs. Use the configuration file template below to create a .json file. Provide values for the appropriate keys for your environment, and then pass the .json file to Tableau Server with the following commands:

tsm settings import -f <path-to-file.json>

tsm pending-changes apply

The SAML template shows the minimum required keys for enabling server-wide SAML.

You will need to replace the placeholder values for returnUrl, entityId, certFile, keyFile, idpMetadataFile, and idpUsernameAttribute.

For example, for idpMetadataFile, you might enter the following:

/var/opt/tableau/tableau_server/data/saml/idp-metadata.xml

{ "configEntities": { "samlSettings": { "_type": "samlSettingsType", "enabled": true, "returnUrl": "https://your-tableau-server", "entityId": "https://your-server-entity-id", "certFile": "/path/to/file/crt", "keyFile": "/path/to/file.key", "idpMetadataFile": "/path/to/metadata.xml", "idpUsernameAttribute": "username-attr" } } }

If you are using a PKCS#8 key that is protected with a passphrase, enter the passphrase as follows:

tsm configuration set -k wgserver.saml.key.passphrase -v <passphrase>

tsm pending-changes apply

The passphrase will be encrypted and saved. See Manage Server Secrets.

To learn more, see samlSettings Entity.

Next, Generate Tableau Server metadata and configure the IdP

Use the TSM CLI

Run the following commands:

  1. Using the location you created if you followed the steps in Put certificate and IdP metadata files in place, and including all parameters that are required for initial configuration, configure the SAML settings for the server (replacing placeholder values with your environment path and file names).

    Linux

    tsm authentication saml configure --idp-entity-id https://tableau-server --idp-metadata /var/opt/tableau/tableau_server/data/saml/<metadata-file.xml> --idp-return-url https://tableau-server --cert-file /var/opt/tableau/tableau_server/data/saml/<file.crt> --key-file /var/opt/tableau/tableau_server/data/saml/<file.key>

    Windows

    tsm authentication saml configure --idp-entity-id https://tableau-server --idp-metadata "C:\Program Files\Tableau\Tableau Server\SAML\<metadata-file.xml>" --idp-return-url https://tableau-server --cert-file "C:\Program Files\Tableau\Tableau Server\SAML\<file.crt>" --key-file "C:\Program Files\Tableau\Tableau Server\SAML\<file.key>"

  2. If you are using a PKCS#8 key that is protected with a passphrase, enter the passphrase as follows:

    tsm configuration set -k wgserver.saml.key.passphrase -v <passphrase>

  3. If SAML is not already enabled on Tableau Server; for example, you’re configuring it for the first time, or you have disabled it, enable it now:

    tsm authentication saml enable

  4. Apply the changes:

    tsm pending-changes apply

    The pending-changes apply command displays a prompt to let you know this will restart Tableau Server if the server is running. The 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. For more information, see tsm pending-changes apply.

Next, Generate Tableau Server metadata and configure the IdP

Generate Tableau Server metadata and configure the IdP

  1. Run the following command to generate the required XML metadata file for Tableau server.

    tsm authentication saml export-metadata -f <file-name.xml>

    You can specify a file name, or omit the -f parameter to create a default file named samlmetadata.xml.

  2. On your IdP’s website or in its application:

    • Add Tableau Server as a Service Provider.

      Refer to your IdP’s documentation for information about how to do this. As part of the process of configuring Tableau Server as a Service Provider, you will import the Tableau Server metadata file you generated from the export-metadata command.

    • Confirm that your IdP uses username as the attribute to verify users.

Test the configuration

  1. In your web browser, open a new page or tab, and enter the Tableau Server URL.

    The browser redirects you to the IdP’s sign-in form.

  2. Enter your single sign-on user name and password.

    The IdP verifies your credentials and redirects you back to your Tableau Server start page.

Thanks for your feedback! There was an error submitting your feedback. Try again or send us a message.