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

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

Before you begin

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

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.

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

    Tableau Services Manager user authentication settings

  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 checkbox above Step 1 in the GUI.

  6. Complete the remaining SAML settings.

    1. For Steps 2 and 3, 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.

      Screen shot highlighting the area of the TSM UI where you upload SAML IDP metadata

    3. For Step 5, in some cases, you might 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, 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, do the following:

    7. (Optional) For Step 8, select the Enable capture of user attributes during SAML authentication checkbox. For more information about user attributes, see Customize and control data access using user attributes.

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

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

    Tableau Server Manager toolbar indicating that there are pending changes.

  9. Click Apply Changes and Restart.

Test the configuration

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

    A blank web browser window displays "http://tableau_server" in the address bar.

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

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

    SAML log in diaglog with fields for username and password.

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

Customize and control data access using user attributes

User attributes are user metadata defined by your organization. User attributes can be used to determine access in a typical attribute-based access control (ABAC) authorization model. User attributes can be any aspect of the user profile, including job roles, departmental membership, management level, etc. They might also be associated with run-time user contexts like where the user is signed in or their language preference.

By including user attributes in your workflow, you can control and customize the user experience through data access and personalization.

  • Data access: User attributes can be used to enforce data security policies. This ensures that users only see the information they are authorized to see.
  • Personalization: By passing user attributes like location and role, your content can be customized to display only the information relevant to the user accessing it, making it easier for them to find the information they need.

Summary of steps to pass user attributes

The process of enabling user attributes in a workflow is summarized in the following steps:

  1. Enable the user attributes setting
  2. Include user attributes in the assertion
  3. Ensure the content author includes user attribute functions and relevant filters
  4. Review the content

Step 1: Enable the user attributes setting

For security purposes, user attributes are only validated in an authentication workflow when the user attribute setting is enabled by a server admin.

  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 > Authentication Method.

  3. Under Authentication Method, select SAML in the drop-down menu.

  4. Under Step 8, select the Enable capture of user attributes during SAML authentication checkbox.

  5. When done, do the following:

    1. Click Save Pending Changes.

    2. Click the Pending Changes button at the top of the page.

    3. Click Apply Changes and Restart.

Step 2: Include user attribute in the assertion

Make sure the assertion contains the user attributes.

Note: Attributes in the SAML response are subject to 4096 character limit, with the exception of scope or scp attributes. If the attributes in the response, including user attributes, exceed this limit, Tableau removes the attributes and passes the ExtraAttributesRemoved attribute instead. The content author can then create a calculation with the ExtraAttributesRemoved attribute to determine how to display the content to users when the attribute has been detected.

Example

Suppose you have an employee, Fred Suzuki, who is a manager located in the South region. You want to ensure that, when Fred reviews reports, he is only able to see data for the South region. In a scenario like this, you might include the Region user attribute in the SAML response like in the example below.

<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
	<saml;Issuer">https://myidp.okta.com/saml</saml:Issuer">
   <saml;Subject">
	  <saml:NameId Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"fsuzuki@example.com</saml:NameID">
   <saml:AttributeStatement xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
  		<saml:Attribute Name="Region" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
  			<saml:AttributeValue">South</saml:AttributeValue">
    	</saml:Attribute">
   </saml:AttributeStatement">
</saml:Assertion">

Step 3: Ensure the content author includes attribute functions

Ensure the content author includes the user attribute functions and related filters to control what data can display in their content. To ensure the user attribute assertions are passed to Tableau, the content must contain one of the following user attribute functions:

  • USERATTRIBUTE('attribute_name')
  • USERATTRIBUTEINCLUDES('attribute_name', 'expected_value')

The function that the content author uses depends on whether the user attributes are expected to return a single value or multiple values. For more information about these functions and examples of each, see User Functions(Link opens in a new window) in the Tableau Help.

Notes:

  • Preview of the content with these functions are not available when authoring in Tableau Desktop or in Tableau Cloud. The function will return NULL or FALSE. To ensure the user functions work as expected, we recommend the author review the functions after making the content available.
  • To ensure content renders as expected, the content author might consider including a calculation that uses the ExtraAttributesRemoved that 1) checks for this attribute and 2) determines what to do with the content if it does, such as show a message. Tableau will only add the ExtraAttributesRemoved attribute and removes all other attributes (except scp or scope) when the attributes in the SAML XML exceed 4096 characters. This is to ensure optimal performance and to respect storage limitations.

Example

Continuing the example introduced in Step 2: Include user attribute in the assertion above, to pass the “Region” user attribute assertion to a workbook, the author can include USERATTRIBUTEINCLUDES. For example, USERATTRIBUTEINCLUDES('Region', [Region]), where ‘Region’ is the user attribute and [Region] is a column in the data. Using the new calculation, the author can create a table with Manager and Sales data. When the calculation is added, the workbook returns “False” values as expected.

To show only the data associated with the South region in the embedded workbook, the author can create a filter and customize it to show values when the South region is “True.” When the filter is applied, the workbook becomes blank as expected because the function is returning “False” values and the filter is customized to show “True” values only.

Step 4: Review the content

Review and validate the content.

Example

To conclude the example from Step 3: Ensure the content author includes attribute functions above, you can see the Sales data in the view is customized to Fred Suzuki because his user context is the South region.

Managers from the regions represented in the workbook should see the value associated with their region. For example, Sawdie Pawthorne from the West region sees data specific to her region.

Managers whose regions are not represented in the workbook see a blank workbook.

Known issues and limitations

There are a few known issues and limitations you should consider when working with user attribute functions.

Back to top