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

SAML Requirements

Before you configure SAML on Tableau Server, make sure your environment meets the requirements described 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. See About the certificate and key files later in this topic for details.

  • Certificate key file. An RSA or DSA private key file that is not password protected, and that has the .key extension. This file is used by Tableau Server, not the IdP. The certificate key file must not have the passphrase. If you have an SSL certificate key file, you can use it for SAML as long as it does not have a passphrase. See About the certificate and key files later in this topic for details.

  • 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. The IdP must support SAML 2.0 or later.

  • 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. When it's used for SSL, the certificate file is used to encrypt traffic. When it's used 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).

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.

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 use multiple IdPs, configure Tableau Server to use local authentication rather than Active Directory. When using 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.

SAML compatibility requirements and notes

Note the following about using SAML with Tableau Server:

  • Multiple external authentication types: Tableau Server does not support using more than 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.

  • IdP provider must support forms-based authentication: You can allow SAML sign-in from Tableau Desktop or Tableau Mobile client applications. To do this, your IdP must support forms-based authentication.

    If it does not, you can disable SAML sign-in for Tableau clients using the wgserver.authentication.desktop_nosaml command. See tabadmin set options.

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

    For more information, see Configure a Server Cluster for SAML.

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

    http(s)://<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:

    http(s)://<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 in Tableau client applications

Tableau Server users with SAML credentials can also 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.

Notes

  • Connecting to Tableau Server from Tableau Desktop or Tableau Mobile uses a service provider initiated connection.

  • To connect with site-specific SAML, users must run version 10.0 or later of the Tableau client application.

XML data requirements

You configure SAML using XML metadata documents that are generated by Tableau Server and by the IdP. During the authentication process, the IdP and Tableau Server exchange authentication information using these XML documents. If the XML does not meet the following requirements, 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.

    The SAML metadata XML document that is exported by Tableau Server should contain the following elements, with the Binding attribute set to HTTP-POST.

    • Verify the following element which 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="http(s)://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="http(s)://<tableauserver>/wg/saml/SingleLogout/index.html/>

    • Verify the following element which specifies the URL for signin in:

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

  • Attribute named username: You must configure the IdP to return an assertion that includes the username value 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.