SAML Requirements


Before you configure SAML on Tableau Server, make sure your environment meets the requirements.

Important: SAML configurations, both with the IdP and on Tableau Server, are case sensitive. For example, URLs configured with the IdP and on Tableau Server must match exactly.

Certificate and identity provider (IdP) requirements

To configure Tableau Server for SAML, you need the following:

  • Certificate file. A PEM-encoded x509 certificate file with a .crt extension. This file is used by Tableau Server, not the IdP. If you have an SSL certificate, it is possible in some circumstances to use the same certificate with SAML. For more information, see Using SSL certificate and key files for SAML later in this article.

    Tableau Server requires a certificate-key pair to sign the request that is sent to the IdP. This reduces the threat of a man-in-the-middle attack given the difficulty of spoofing a signed request. Additionally, Tableau Server verifies that the AuthNResponse it receives from the trusted IdP. Tableau Server verifies the AuthNResponse by using the signature produced by the IdP. The IdP certificate metadata is provided to Tableau Server as part of the initial SAML configuration process.

    Signed requests are not always necessary for all IdPs. By default, Tableau Server requires signed requests. We recommend this configuration to ensure a more secure communication transmission with the IdP. Work with your IdP team to understand if disabling signed requests is necessary. To disable signed requests see samlSettings Entity.

  • Signature algorithm. The certificate must use a secure signature algorithm, for example SHA-256. If you attempt to configure Tableau Server for SAML with a certificate that uses SHA-1 signature hash, Tableau Server will reject the certificate. You can configure Tableau Server to accept the less-secure SHA-1 hash by setting the tsm wgserver.saml.blocklisted_digest_algorithms configuration key.

  • RSA key and ECDSA curve sizes. The Tableau Server certificate must have an RSA key strength of 2048, and the IdP certificate must have either an RSA key strength of 2048 or ECDSA curve size of 256.

    You can configure Tableau Server to accept the less-secure sizes by setting the respective configuration keys, wgserver.saml.min_allowed.rsa_key_size and wgserver.saml.min_allowed.elliptic_curve_size.

  • Certificate key file. An RSA or DSA private key file that has the .key extension. RSA keys must be in in PKCS#1 or PKCS#8 format.

    Password protection requirements are as follows:

    • The PKCS#1 RSA key file cannot be password protected.

    • To use a password-protected key file, you must configure SAML with a RSA PKCS#8 file. Note: A PKCS#8 file with a null password is not supported.

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

    Summary of support

    Key file formatServer-Wide SAML SupportSite-Level SAML Support
    PKCS#8 RSAYesNo
    PKCS#8 (no/null password)NoNo
    PKCS#1 RSAYesYes
    PKCS#1 RSA (password)NoNo
    PKCS#1 DSA (password)NoNo

  • IdP must sign SAML assertions with a secure signature algorithm. By default, Tableau Server will reject SAML assertions signed with the SHA-1 algorithm. You can configure Tableau Server to accept assertions signed with the less-secure SHA-1 hash by setting the tsm wgserver.saml.blocklisted_digest_algorithms configuration key.

  • IdP account that supports SAML 2.0 or later. You need an account with an external identity provider. Some examples are PingFederate, SiteMinder and Open AM.

  • IdP provider that supports import and export of XML metadata. Although a manually created metadata file might work, Tableau Technical Support cannot assist with generating the file or troubleshooting it.

  • Username: Required. The IdP configuration must include the "username" attribute or claim, and the corresponding SAML configuration attribute on Tableau Server must be set to "username" as well.

SSL off-loading

If your organisation terminates SSL connections from the IdP at a proxy server before sending the authentication request to Tableau Server, then you may need to make a proxy configuration. In this scenario, SSL is "off-loaded" at the proxy server, which means the https request is terminated at the proxy server and then forwarded to Tableau Server over http.

Tableau Server validates the SAML response message returned from the IdP. Since SSL is off-loaded at the proxy, Tableau Server will validate with the protocol that it receives (http), but the IdP response is formatted with https, so validation will fail unless your proxy server includes the X-Forwarded-Proto header set to https. See Configure Tableau Server to work with a reverse proxy server and/or load balancer.

Using SSL certificate and key files for SAML

If you are using a PEM-encoded x509 certificate file for SSL, you can use the same file for SAML. For SSL, the certificate file is used to encrypt traffic. For SAML, the certificate is used for authentication.

In addition to the requirements listed in Certificate and identity provider (IdP) requirements above, to use the same certificate for both SSL and SAML, the certificate must also meet the following condition to work for SAML:

  • Confirm that the certificate includes only the certificate that applies to Tableau Server and not any other certificates or keys.

    To do this, you can create a backup copy of the certificate file, and then open the copy in a text editor to review its contents.

User management requirements

When you enable SAML, user authentication is performed outside of Tableau, by the IdP. However, user management is performed by an identity store: either an external identity store (Active Directory or LDAP) or by Tableau Server in a local identity store. For more information about planning for user management with Tableau Server, see Identity Store.

When you configure the identity store during Setup, you must select the option that reflects how you want to use SAML. Note, if you want to use site-specific SAML, you must configure server-wide SAML before you configure individual sites.

  • For site-specific SAML: If you have multiple sites on Tableau Server and want to set up each site for a particular IdP or IdP application (or configure some sites not to use SAML), configure Tableau Server to manage user with a local identity store. For site-specific SAML, Tableau Server relies on the IdP for authentication and does not use passwords.

  • For server-wide SAML: If you configure server-wide SAML with a single IdP, you can configure Tableau Server to use the local identity store or an external identity store. If you are using Active Directory (AD), you must disable the Enable automatic log-on (Microsoft SSPI) option.

  • For both server-wide SAML authentication and site-specific SAML authentication:

    • When using a local identity store, it is important that you use a username that has email address formatting. Using a complete email address helps to guarantee the uniqueness of the username in Tableau Server, even when two users have the same email prefix but have different email domains. To ensure uniqueness in identities, leverage full email address formatting across both systems or upgrade Tableau Server to version 2022.1.x or later and run the identity migration background job.

    • In a multi-site environment, all users authenticate through a SAML IdP configured at the site level. In this scenario, you specify a server-wide default SAML IdP for users who belong to multiple sites. To configure this scenario, Tableau Server must be configured with a local identity store.

    • Ignore domain when matching SAML username attribute. Beginning in Tableau Server versions 2021.4.21, 2022.1.17, 2022.3.9 and 2023.1.5, you can configure Tableau Server to ignore the domain portion of the username attribute when matching the identity provider (IdP) user name to a user account on Tableau Server. For example, the username attribute in the IdP might be alice@example.com to match a user named alice in Tableau Server. Ignoring the domain portion of the username attribute might be useful if you already have users defined in Tableau Server that match the prefix portion of the username attribute but not the domain portion of the username attribute.

      Important: We do not recommend ignoring the domain name without taking precautions. Specifically, verify that user names are unique across the configured domains that you've created in your IdP. Configuring Tableau Server to ignore the domain name has the potential to result in unintended user sign-in. Consider the case where your IdP has been configured for multiple domains (e.g. example.com and tableau.com). If two users with the same first name, but different user accounts (e.g., alice@tableau.com and alice@example.com) are in your organisation, then you could have a mapping mismatch.

      To configure Tableau Server to ignore domain names in the username attribute from the IdP, set wgserver.ignore_domain_in_username_for_matching to true. For more information, see wgserver.ignore_domain_in_username_for_matching.

      Notes:

      • This command only works in Tableau Server deployments that are in legacy-identity-mode or deployments that have not been updated through the identity migration(Link opens in a new window) to use the Identity Service.
      • When you change the tsm command to ignore the domain name in the username attribute, all user names in Tableau Server must have a domain name.

Note: The REST API and tabcmd do not support SAML single-sign (SSO). To sign in, you must specify the name and password of a user who has been created on the server. The user may be managed by the local identity store or an external identity store, depending on how you have configured Tableau Server. REST API or tabcmd calls will have the permissions of the user you sign in as.

SAML compatibility notes and requirements

  • Matching usernames: The username stored in Tableau Server must match the configured username attribute sent by the IdP in the SAML assertion. By default, Tableau Server expects the incoming assertion to contain an attribute called "username" with that user's information. For example, if the user name for Jane Smith is stored in PingFederate as jsmith, it must also be stored in Tableau Server as jsmith.

    When configuring SAML during authentication

    If you are configuring SAML as part of the initial Tableau Server setup, make sure the account you plan to use exists in your IdP before you run setup. During Tableau Server setup you create the server administrator account.

    When running multiple domains

    If you use an Active Directory or LDAP external identity store and you are running in multiple domains (that is, users belong to multiple domains, or your Tableau Server installation includes multiple domains), the IdP must send both the username and domain attributes for a user in the SAML assertion. Both these username and domain attributes must match exactly the username and domain stored in Tableau Server. Do one of the following:

    • Set domain\username in the username field
    • Set domain in the domain field and set user name in the username field

    When setting the domain attribute, you can use the fully qualified domain name (FQDN) or the shortname.

    Where the domain isn't specified, it will be considered the default domain.

    For more information, see Support for multiple domains and the "Match Assertions" section in the Use TSM CLI tab of Configure Server-Wide SAML.

  • Signature algorithm: Tableau Server uses SHA256 signature algorithm.

  • Single Log Out (SLO): Tableau Server supports both service provider (SP)-initiated SLO and identity provider (IdP)-initiated SLO for both server-wide SAML and site-specific SAML.

  • External authentication types: Tableau Server supports using one external authentication type at a time.

  • Mutual SSL: Tableau Server does not support mutual SSL (two-way SSL) and SAML together. If you want to use mutual SSL, you can configure it on the IdP.

  • Assertions encoding: Assertions must be UTF-8 encoded.

  • Encryption and SAML assertions:

    • Server-wide SAML: When Tableau Server is configured for server-wide SAML, Tableau Server supports encrypted assertions from the IdP. Encryption assertions are enabled by the certificate that you upload as part of the initial configuration for server-wide SAML. SAML requests and responses can be sent over HTTP or HTTPS.

    • Site-specific SAML: When Tableau Server is configured for site-specific SAML, Tableau Server does not support encrypted assertions from the IdP. However, all SAML requests and responses are sent over HTTPS to secure communication with the IdP. HTTP requests and responses are not supported.

  • User identity in Tableau Server for tabcmd users: As described in User management requirements section above, to use tabcmd, you must sign in as a user defined on the server. You cannot use SAML accounts with tabcmd.

  • Using SAML SSO with Tableau Desktop: By default, Tableau Desktop allows SP-initiated SAML authentication.

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

    tsm authentication saml configure --desktop-access disable

    For more information, see tsm authentication saml <commands>.

  • Distributed installations: TSM versions of Tableau Server (2018.2 and newer) use the Client File Service to share files in a multi node cluster. After you have configured SAML on the initial node in your cluster, the Client File Service will distribute certificate and key files to the other nodes.

  • Login URL: For users to be able to sign in, your IdP must be configured with SAML Login endpoint that sends a POST request to the following URL:

    https://<tableauserver>/wg/saml/SSO/index.html.

  • Logout URL: To enable users to sign out after signing in with SAML (single logout, or SLO), your IdP must be configured with a SAML Logout endpoint that sends a POST request to the following URL:

    https://<tableauserver>/wg/saml/SingleLogout/index.html.

    Note: Tableau Server supports both service provider (SP)-initiated SLO and identity provider (IdP)-initiated SLO for both server-wide SAML and site-specific SAML.

  • Post-logout redirect URL: By default, when a user signs out of Tableau Server, the sign-in page is displayed. 

    To display a different page after sign-out, use the tsm authentication saml configure command with the -su or --signout-url option.

    • To specify an absolute URL, use a fully-qualified URL starting with http:// or https://, as in this example:

      tsm authentication saml configure -su https://example.com

    • To specify a URL relative to the Tableau Server host, use a page starting with a / (slash):

      tsm authentication saml configure -su /ourlogoutpage.html

  • Active Directory Federation Service (AD FS): You must configure AD FS to return additional attributes for Tableau authentication with SAML. The Name ID and username attributes can be mapped to the same AD attribute: SAM-Account-Name.

    For configuration information, see Configure SAML with AD FS on Tableau Server.

  • AuthNContextClassRef : AuthNContextClassRef is an optional SAML attribute that enforces validation of certain authentication "contexts" in IdP initiated flows. You can set comma-separated values for this attribute with TSM. When this attribute is set, Tableau Server validates that the SAML response contains at least one of the values listed. If the SAML response does not contain one of the configured values, authentication will be rejected, even if the user has successfully authenticated with the IdP.

    Leaving this optional attribute blank will result in default behaviour: any successfully authenticated SAML response will result in a user being granted a session within Tableau Server.

    This value is only evaluated for server-wide SAML. If site-SAML is configured, the AuthNContextClassRef attribute will be ignored.

    To set this value with TSM web interface, see Configure Server-Wide SAML.

    To set this value with tsm configuration set, use the key, wgserver.saml.authcontexts, to set a comma-separated list of values.

    To set this value with a JSON configuration file, see samlSettings Entity.

Using SAML SSO with Tableau client applications

Tableau Server users with SAML credentials can sign in to the server from Tableau Desktop or the Tableau Mobile app. For full compatibility, we recommend that the Tableau client application version matches that of the server. To connect using site-specific SAML, users must run version 10.0 or later of the Tableau client application.

Connecting to Tableau Server from Tableau Desktop or Tableau Mobile uses a service provider (SP) initiated connection.

Redirecting authenticated users back to Tableau clients

When a user signs in to Tableau Server, Tableau Server sends a SAML request (AuthnRequest) to the IdP, which includes the Tableau application’s RelayState value. If the user has signed in to Tableau Server from a Tableau client such as Tableau Desktop or Tableau Mobile, it’s important that the RelayState value is returned within the IdP’s SAML response back to Tableau.

When the RelayState value is not returned properly in this scenario, the user is taken to their Tableau Server home page in the web browser, rather than being redirected back to the application they signed in from.

Work with your Identity Provider and internal IT team to confirm that this value will be included as part of the IdP’s SAML response, and then preserved by any network appliance (such as a proxy or load balancer) that resides between your IdP and Tableau Server.

XML data requirements

As part of SAML configuration, you exchange XML metadata between Tableau Server and the IdP. This XML metadata is used to verify a user’s authentication information when the user initiates the Tableau Server sign-in process.

Tableau Server and the IdP each generates its own metadata. Each set of metadata must contain the information described in the following list. If either set is missing information, errors can occur when you configure SAML or when users try to sign in.

  • HTTP POST and HTTP REDIRECT: Tableau Server supports HTTP POST and HTTP REDIRECT requests for SAML communications. In the SAML metadata XML document that is exported by the IdP, the Binding attribute can be set to HTTP-POST or HTTP-REDIRECT.

  • When the Binding attribute is set to HTTP-POST, the SAML metadata that Tableau Server and the IdP each export must contain the following elements.

    • The element that specifies the URL that the IdP redirects to after successful authentication. This is required in the Service Provider metadata, not the Identity Provider metadata.

      <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<tableau-server>/wg/saml/SSO/index.html index="0" isDefault="true"/>

      For Site SAML, the Location endpoint is /samlservice/public/sp/metadata?alias=<site alias>.

    • The logout endpoint element appears in Tableau Server metadata and specifies the URL that the IdP will use for Tableau Server's logout endpoint. If this element is not in the IdP metadata, Tableau Server cannot negotiate a logout endpoint with the IdP, and the SAML Logout feature will not be available within Tableau Server:

      <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://SERVER-NAME:9031/idp/slo"

      Note: SP-initiated SLO is supported for both server-wide and site-specific SAML. However, IdP-initiated SLO is not supported.

    • Verify 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"/>

    • This element should appear in IdP metadata and specifies the URL that Tableau Server will use for the IdP's logout endpoint.

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

  • Attribute named username: You must configure the IdP to return an assertion that includes the username attribute in the saml:AttributeStatement element. The assertion’s attribute type must be xs:string (it should not be typed as xs:any).

    The following example shows what this might look like.

    <saml:Assertion assertion-element-attributes>
  <saml:Issuer>issuer-information</saml:Issuer>
  <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
    ...
  </Signature>
  <saml:Subject>
    ...
  </saml:Subject>
  <saml:Conditions condition-attributes >
    ...
  </saml:Conditions>
  <saml:AuthnStatement authn-statement-attributes >
    ...
  </saml:AuthnStatement>

  <saml:AttributeStatement>
    <saml:Attribute Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
          user-name
    </saml:AttributeValue>
    </saml:Attribute>
  </saml:AttributeStatement>
</saml:Assertion>

    By default, Tableau Server will read the username attribute in the AuthNResponse returned from the Idp. However, some IdPs may return a different attribute that is intended to identify the user.

    To change the SAML attribute that passes the username value, run the following TSM command:

    tsm authentication saml map-assertions --user-name <USER-NAME>.

    See tsm authentication.

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