Tableau Server on Windows Help

This procedure requires that you upload the SAML certificates to TSM so that they are properly stored and distributed in the server configuration. The SAML files must available to the browser on the local computer where you are running the TSM web interface in this procedure.

If you have gathered and saved the SAML files to the Tableau Server as recommended in the previous section, then run the TSM web interface from the Tableau Server computer where you copied the files.

If you are running the TSM web interface from a different computer, then you will need to copy all SAML files locally before proceeding. As you follow the procedure below, browse to the files on the local computer to upload them to TSM.

1. Open TSM in a browser:

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

2. On the Configuration tab, select User Identity & Access, and then select the Authentication Method tab.

   

3. For Authentication Method, select SAML.

4. In the SAML section that appears, complete Step 1 in the GUI, entering the following settings (do not yet select the check box to enable SAML for the server):

   • Tableau Server return URL—The URL that Tableau Server users will access, such as https://tableau-server.

     Using https://localhost or a URL with a trailing slash (for example, http://tableau_server/) is not supported.

   • SAML entity ID—The entity ID uniquely identifies your Tableau Server installation to the IdP.

     You can enter your Tableau Server URL again here. If you plan to enable site-specific SAML later, this URL also serves as the base for each site’s unique ID.

   • SAML certificate and key files— Click Select File to upload each of these files.

     If you are using a PKCS#8 passphrase-protected key file, you must enter the passphrase with TSM CLI:

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

     After you provide the information required in Step 1 in the GUI, the Download XML Metadata File button in Step 2 in the GUI becomes available.

5. Now select the Enable SAML authentication for the server check box above Step 1 in the GUI.

6. Complete the remaining SAML settings.

   1. For Steps 2 and 3 in the GUI, exchange metadata between Tableau Server and the IdP. (Here’s where you might need to check in with the IdP’s documentation.)

      Select Download XML Metadata File, and specify the file location.

      If you are configuring SAML with AD FS, you can return to Step 3: Configure AD FS to accept sign-in requests from Tableau Server of “Configure SAML with AD FS on Tableau Server.”

      For other IdPs, go to your IdP account to add Tableau Server to its applications (as a service provider), providing the Tableau metadata as appropriate.

      Follow the instructions in the IdP’s website or documentation to download the IdP’s metadata. Save the .xml file to the same location that holds your SAML certificate and key files. For example:

      C:\Program Files\Tableau\Tableau Server\SAML\idp-metadata.xml

   2. Return to the TSM web UI. For Step 4 in the GUI, enter the path to the IdP metadata file, and then click Select File.

      

   3. For Step 5 in the GUI: In some cases, you may need to change the assertion values in the Tableau Server configuration to match the assertion names that are passed by your IdP.

      You can find assertion names in the IdP's SAML configuration. If different assertion names are passed from your IdP, then you must update Tableau Server to use the same assertion value.

      Tip: “Assertions” are a key SAML component, and the concept of mapping assertions can be tricky at first. It might help to put this in a tabular-data context, in which the assertion (attribute) name is equivalent to a column heading in the table. You enter that “heading” name, rather than an example of a value that might appear in that column.

   4. For Step 6 in the GUI, select the Tableau applications in which you want to give users a single sign-on experience.

      Note: The option to disable mobile access is ignored by devices running Tableau Mobile app version 19.225.1731 and higher. To disable SAML for devices running these versions you must disable SAML as a client login option on Tableau Server.

   5. For the SAML sign-out redirect, if your IdP supports single logout (SLO), enter the page you want to redirect users to after they sign out, relative to the path you entered for the Tableau Server return URL.

   6. (Optional) For Step 7 in the GUI, do the following:

      • Add a comma-separated value for the AuthNContextClassRef attribute. For more information about how this attribute is used, see SAML compatibility notes and requirements.

      • Specify a domain attribute if not sending the domain as part of the username (i.e., domain\username). For more information, see When running multiple domains.

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

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

   

9. Click Apply Changes and Restart.

Before you begin

Before you begin, do the following:

• Go to your 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"/>

• Gather the certificate files and place them on Tableau Server.

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

  C:\Program Files\Tableau\Tableau Server\SAML

  This is the recommended location because the user account that runs Tableau Server has the necessary permissions to access this folder.

Step 1: Configure return URL, SAML entity ID, and specify certificate and key files

1. Open the command prompt shell and configure the SAML settings for the server (replacing placeholder values with your environment path and file names).

   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>"

   For more information, see tsm authentication saml configure.

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

   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.

Step 2: 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.

Step 3: Match assertions

In some cases, you may need to change the assertion values in the Tableau Server configuration to match the assertion names that are passed by your IdP.

You can find assertion names in the IdP's SAML configuration. If different assertion names are passed from your IdP, then you must update Tableau Server to use the same assertion value.

Tip: “Assertions” are a key SAML component, and the concept of mapping assertions can be tricky at first. It might help to put this in a tabular-data context, in which the assertion (attribute) name is equivalent to a column heading in the table. You enter that “heading” name, rather than an example of a value that might appear in that column.

The following table shows the default assertion values and the configuration key that stores the value.

Assertion	Default value	Key
Username	username	wgserver.saml.idpattribute.username
Display name	displayName	Tableau does not support this attribute type.
Email	email	Tableau does not support this attribute type.
Domain	(not mapped by default)	wgserver.saml.idpattribute.domain

To change a given value, run the tsm configuration set command with the appropriate key:value pair.

For example, to change the username assertion to the value, name, run the following commands:

tsm configuration set -k wgserver.saml.idpattribute.username -v name

tsm pending-changes apply

Alternatively, you can use the tsm authentication saml map-assertions command to change a given value.

For example, to set the domain assertion to a value called domain and specify its value as "example.myco.com," run the following commands:

tsm authentication saml map-assertions --domain example.myco.com

tsm pending-changes apply

Optional: Disable client types from using SAML

By default, both Tableau Desktop and the Tableau Mobile app allow SAML authentication.

If your IdP does not support this functionality, you can disable SAML sign-in for Tableau clients using the following commands:

tsm authentication saml configure --desktop-access disable

tsm authentication saml configure --mobile-access disable

Note: The --mobile-access disable option is ignored by devices running Tableau Mobile app version 19.225.1731 and higher. To disable SAML for devices running these versions you must disable SAML as a client login option on Tableau Server.

tsm pending-changes apply

Optional: Add AuthNContextClassRef value

Add a comma-separated value for the AuthNContextClassRef attribute. For more information about how this attribute is used, see SAML compatibility notes and requirements.

To set this attribute run the following commands:

tsm configuration set -k wgserver.saml.authcontexts -v <value>

tsm pending-changes apply