Configure Site-Specific SAML

Tableau Server on Windows now includes Tableau Services Manager (TSM), which replaces the Configuration Utility and the tabadmin command line tool. If you need help for an earlier version of Tableau Server, see the Tableau Help page.

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:

  • Configure the default server-wide authentication method that can be used with site-specific SAML. This method will apply to users that do not belong to a site, or that belong to multiple sites.

    With site-specific SAML, you can use server-wide local authentication or server-wide SAML authentication. You cannot use Active Directory with the SAML-enabled sites.

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

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

In the server’s workgroup.yml file, server-wide settings that are used in some way for site-specific SAML include:

  • wgserver.saml.returnurl and wgserver.saml.entityid: 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.

  • wgserver.saml.domain, wgserver.saml.port, and wgserver.saml.protocol are used for SAML requests at the site level.

Server-wide settings wgserver.saml.maxauthenticationage and wgserver.saml.responseskew do not apply to site-specific SAML.

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 SAML.
    • If you have already configured server SAML, do not run the tsm authentication saml configure command. Skip to Step 2.
    • If you have not yet configured server SAML, run the following command to provide the SAML certificate location and file names, along with the other required attributes. For more information, see tsm authentication saml <commands>.

      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.

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.

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 page in the Tableau Server web UI. In a self-hosted Tableau Server installation, this page appears only when support for site-specific SAML is enabled at the server level. It is enabled by default in Tableau Online.

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, do either of the following steps. See the IdP’s SAML configuration documentation to confirm the correct option.

  • Select Export metadata 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 signing and encryption 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 Online and Tableau Server.

Steps 2 and 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.

Step 5: Match 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 but recommended) Some IdPs use separate attributes for first and last names, and others store the full name in one attribute.

    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 issues, see Troubleshoot SAML.

Default authentication type for embedded views

Part of enabling SAML on your site is to specify how users access views embedded in web pages.

  • Allow users to choose their authentication type

    When you select this, two sign-in options appear where a view is embedded: a sign-in button that uses single sign-on authentication and a link to use TableauID as an alternative.

    Tip: With this option, users need to know which alternative to choose. As part of notification you send your users after you add them to the single sign-on site, let them know which type of authentication to use for a variety of sign-in scenarios. For example, embedded views, Tableau Desktop, Tableau Bridge, Tableau Mobile, and so on.

  • TableauID

    This option requires users to sign in using a TableauID even if SAML is enabled on the site. Generally it’s reserved for administrators for troubleshooting issues with embedded views and SAML.

  • Single sign-on with SAML

    If your IdP doesn't support signing in from an iframe, select Authenticate in a separate pop-up window. When a user goes to the web page with the embedded view, the pop-up window appears when they select the sign-in button.

    If your IdP supports signing in from an iframe, select Authenticate using an inline frame (less secure; not supported by all IdPs). Iframe embedding can provide a more seamless user experience. For example, if a user is already authenticated with your IdP, and iframe embedding is enabled, the user seamlessly authenticates with Tableau Server when browsing to pages that contain embedded Tableau views.

    Caution: Because iframes can be vulnerable to clickjacking attacks, not all IdPs support signing in through an iframe. With clickjacking, the attacker tries to lure users into clicking or entering content. They do this by displaying the page to attack in a transparent layer over an unrelated page. For Tableau Server, an attacker might try to capture user credentials or to get an authenticated user to change settings. For more information, see Clickjacking on the Open Web Application Security Project website.

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