Was this page helpful?
Yes No
Tableau Help > Tableau Server on Windows Help > 

SAML Requirements

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

In this article

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, you can use the same certificate with SAML. For more information, see About the certificate and key files later in this article.

  • Certificate key file. An RSA or DSA private key file that is not password protected, and that has the .key extension. RSA keys must be in in PKCS#1 format.

    The key file is used by Tableau Server, not the IdP. If you have an SSL certificate key file, you can use it for SAML as long as it is in PKCS#1 format and does not have a passphrase. For more information, see About the certificate and key files later in this article.

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

About the certificate and key files

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.

Tableau Server does not support certificate and certificate key files for SAML if the certificate and key require a chain file. If your SSL certificate and key files require a chain file, you need to generate new certificate and key files to use for SAML.

User management requirements

When you enable SAML, user authentication is performed outside of Tableau, with the IdP. However, the user management is performed either by Active Directory or by Tableau Server (called local authentication even though Tableau Server is not performing authentication in this scenario).

When you configure user authentication, you select the option that reflects how you want to use SAML:

  • 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, configure Tableau Server to use local authentication rather than Active Directory. 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 local authentication or Active Directory for user management. If you select Active Directory, you must disable the Enable automatic logon option.

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 could have a local or Active Directory account, depending on how you have configured Tableau Server. For Tableau Online, you can specify the TableauID credentials of the user. REST API or tabcmd calls will have the permissions of the user you sign in as.

SAML compatibility notes and requirements

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

  • Encryption and site-specific SAML assertions: Although Tableau Server does not support encrypted SAML assertions from the IdP, all SAML requests and responses are sent over HTTPS.

  • 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 clients: You can allow SAML sign-in from Tableau clients such as Tableau Desktop and Tableau Mobile.

    If your IdP does not support this functionality, you can disable SAML sign-in for Tableau clients using the wgserver.authentication.desktop_nosaml command. See tabadmin configuration options.

    See also Using SAML SSO with Tableau client applications.

  • Distributed installations: Clusters configured for SAML must have the same SAML certificate, SAML key, and SAML IdP metadata files on each Tableau Server that runs an Application Server process.

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

  • 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 tabadmin set wgserver.saml.logout.redirect_url command.

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

      tabadmin set wgserver.saml.logout.redirect_url http://example.com

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

      tabadmin set wgserver.saml.logout.redirect_url /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.

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.

Using site-specific SAML with Tableau Server

This section does not apply to Tableau Online.

If you have a multi-site environment and want to configure separate IdPs or IdP applications for individual sites, be aware that some of the server-wide settings do not apply to site-specific SAML.

For example, in the server’s workgroup.yml file, wgserver.saml.maxauthenticationage and wgserver.saml.responseskew.

Server-wide settings that do apply to site-specific SAML include:

  • wgserver.saml.returnurl
  • wgserver.saml.protocol
  • wgserver.saml.domain
  • wgserver.saml.port
  • wgserver.saml.entityid
  • wgserver.saml.cert.file
  • wgserver.saml.key.file

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: Tableau Server accepts only HTTP POST requests for SAML communications. HTTP Redirect is not supported.

  • With the Binding attribute 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:

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

    • Verify the following element, which specifies the URL that the IdP will use for the logout endpoint:

      <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<tableauserver>/wg/saml/SingleLogout/index.html/>

    • Verify the element that specifies the URL for signing in:

      <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<tableauserver>/wg/saml/SSO/index.html/>

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

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

    To change the SAML attribute that passes the username value, use the tabadmin set command. Set the wgserver.saml.idpattribute.username value to the new attribute name (case sensitive). You must change this attribute if you use a global ID.

  • Matching usernames: The user name stored in Tableau Server must match the user name stored in the IdP. 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.

    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.

    If you use Active Directory authentication with Tableau Server and have multiple Active Directory domains (that is, users belong to multiple domains, or your Tableau Server installation includes multiple domains), the IdP must send both the user name and domain for a user, and they must match exactly in Tableau Server. Although these can be sent as either domain/usernameor username@domain.com, we recommend using domain/username.

    For more information, see User Management in Active Directory Deployments.