Configure Site-Specific SAML


Use site-specific SAML in a multi-site environment when you want to enable single sign-on, and you also use multiple SAML identity providers (IdPs) or IdP applications. When you enable site SAML, you can specify the IdP or IdP application for each site, or configure some sites to use SAML and the others to use the default server-wide authentication method.

If you want all server users to use SAML and sign in through the same IdP application, see Configure Server-Wide SAML.

Prerequisites for enabling site-specific SAML

Before you can enable SAML single sign-on at the site level, complete the following requirements:

  • The Tableau Server identity store must be configured for local identity store.

     You cannot configure site-specific SAML if Tableau Server is configured with an external identity store such as Active Directory or OpenLDAP.

  • Make sure your environment and your IdP meet the general SAML Requirements.

    Some features are supported only in server-wide SAML deployments, including but not limited to:

    • Password-protected key files, which are not supported in site-specific SAML deployments.

  • You must configure server-wide SAML before you configure site-specific SAML. You do not need to enable server-wide SAML, but site-specific SAML requires the server-wide configuration. See Configure Server-Wide SAML.

  • Note the location of the SAML certificate files. You will provide this when you Configure the server to support site-specific SAML.

    For more information, see Put metadata and certificate files in place in the topic on configuring server-wide SAML.

  • Add Tableau Server as a service provider to your IdP. You can find this information in the documentation the IdP provides.

  • Confirm that the system clocks of the computer hosting the site-SAML IdP and the computer hosting Tableau Server are within 59 seconds of each other. Tableau Serer does not have a configuration option to adjust the response skew (time difference) between the Tableau Server computer and the IdP.

Return URL and entity ID: In the settings for configuring site-specific SAML, Tableau provides a site-specific return URL and entity ID based on these settings. The site-specific return URL and entity ID cannot be modified. These configurations are set by TSM as described in Configure Server-Wide SAML.

Authentication age and response skew: Server-wide settings, maximum authentication age and response skew, do not apply to site-specific SAML. These configurations are hard-coded:

  • The maximum authentication age refers to how long an authentication token from the IdP is valid after it is issued. The hard-coded maximum authentication age site-specific SAML is 24 days.
  • The response skew is the maximum number of seconds difference between Tableau Server time and the time of the assertion creation (based on the IdP server time) that still allows the message to be processed. The hard-coded site-specific value for this is 59 seconds.

Username: Required. In addition to the server-wide SAML configuration attribute, the site-specific SAML configuration attribute must be set to "username."

Note: For site-specific SAML to operate successfully with a server-wide SAML default, the username attribute configured for server-wide SAML with the wgserver.saml.idpattribute.username configuration key must be "username". The IdP used for server-wide SAML must deliver the username in an attribute named "username."

A form for matching attributes from an identity provider.

HTTP POST and HTTP REDIRECT: For site-specific SAML, Tableau Server supports HTTP-POST, HTTP-REDIRECT, and HTTP-POST-SimpleSign.

Configure the server to support site-specific SAML

After you complete the prerequisites listed above, you can run the following commands to configure the server to support site-specific SAML.

  1. Configure Server-Wide SAML. At a minimum, you must run the following TSM command (if you have already configured server-wide SAML, skip to Step 2):

    tsm authentication saml configure --idp-entity-id <tableau-server-entity-id> --idp-return-url <tableau-server-return-url> --cert-file <path-to-saml-certificate.crt> --key-file <path-to-saml-keyfile.key>

  2. Enable site SAML. Run the following commands:

    tsm authentication sitesaml enable

    tsm pending-changes apply

About the commands

The sitesaml enable command exposes the Authentication tab on each site’s Settings page in the Tableau Server web UI. After you configure the server to support site SAML, you can continue to Configure SAML for a site to work through the settings on the Authentication tab.

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.

If you want to review the commands and settings that will be carried out when you run pending-changes apply, you can run the following command first:

tsm pending-changes list --config-only

Configure SAML for a site

This section takes you through the configuration steps that appear on the Authentication tab in the Tableau Server Settings page. In a self-hosted Tableau Server installation, this page appears only when support for site-specific SAML is enabled at the server level.

Note: To complete this process, you will also need the documentation your IdP provides. Look for topics that refer to configuring or defining a service provider for a SAML connection, or adding an application.

Step 1: Export metadata from Tableau

To create the SAML connection between Tableau Server and your IdP, you need to exchange required metadata between the two services. To get metadata from Tableau Server, choose one of the following methods. See the IdP’s SAML configuration documentation to confirm the correct option.

  • Select Export metadata button to download an XML file that contains the Tableau Server SAML entity ID, Assertion Consumer Service (ACS) URL, and X.509 certificate.

    The entity ID is site-specific, and based on the server-wide entity ID that you specified when you enabled site SAML on the server. For example, if you specified https://tableau_server, you might see the following entity ID for the site:

    https://tableau_server/samlservice/public/sp/metadata?alias=48957410-9396-430a-967c-75bdb6e002a0

    You cannot modify the site-specific entity ID or ACS URL that Tableau generates.

  • Select Download certificate if your IdP expects the required information in a different way. For example, if it wants you to enter the Tableau Server entity ID, ACS URL, and X.509 certificate in separate locations.

    The following image has been edited to show that these settings are the same in Tableau Cloud and Tableau Server.

    A form with options for retrieving metadata.

Step 2 and Step 3: External steps

For step 2, to import the metadata you exported in step 1, sign in to your IdP account, and use the instructions provided by the IdP’s documentation to submit the Tableau Server metadata.

For step 3, the IdP’s documentation will guide you also in how to provide metadata to a service provider. It will instruct you to download a metadata file, or it will display XML code. If it displays XML code, copy and paste the code into a new text file, and save the file with a .xml extension.

Step 4: Import IdP metadata to the Tableau site

On the Authentication page in Tableau Server, import the metadata file that you downloaded from the IdP or configured manually from XML it provided.

Note: If editing the configuration, you will need to upload the metadata file so Tableau knows to use the correct IdP entity ID and SSO service URL.

Step 5: Map attributes

Attributes contain authentication, authorization, and other information about a user. In the Identity Provider (IdP) Assertion Name column, provide the attributes that contain the information Tableau Server requires.

  • Username or Email: (Required) Enter the name of the attribute that stores user names or email addresses.

  • Display name: (Optional) Some IdPs use separate attributes for first and last names, and others store the full name in one attribute. If you're using SAML with local authentication, the display name attribute isn't synchronized with the SAML IdP.

    Select the button that corresponds to the way your IdP stores the names. For example, if the IdP combines first and last name in one attribute, select Display name, and then enter the attribute name.

    Screen shot of step 5 for configuring site SAML for Tableau Server -- matching attributes

Step 6: Manage users

Select existing Tableau Server users, or add new users you want to approve for single sign-on.

When you add or import users, you also specify their authentication type. On the Users page, you can change users’ authentication type any time after adding them.

For more information, see Add Users to a Site or Import Users and Set the User Authentication Type for SAML.

Important: Users that authenticate with site-specific SAML can belong only to one site. If a user needs to access multiple sites, set their authentication type to the server default. Depending on how site-specific SAML was configured by the server administrator, the server default is either local authentication or server-wide SAML.

Step 7: Troubleshooting

Start with the troubleshooting steps suggested on the Authentication page. If those steps do not resolve the issue, see Troubleshoot SAML.

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