Before you configure SAML on Tableau Server, make sure your environment meets the requirements.
In this article
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 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 might be able to use it for SAML if 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.
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 conditions to work for SAML:
If your SSL certificate and key files require a chain file, you must generate new certificate and key files to use for SAML. Tableau Server does not support certificate and certificate key files for SAML if the certificate and key require a chain file.
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.
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 (or configure some sites to not use SAML), configure Tableau Server to use local authentication. 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.
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. For more information, see Using SAML SSO with Tableau client applications later on this page.
If your IdP does not support this functionality, you can disable SAML sign-in for Tableau clients using the following commands:
tsm authentication saml configure --desktop-access disable
tsm authentication saml configure --mobile-access disable
For more information, see tsm authentication saml <commands>.
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:
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:
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 configurecommand with the
To specify an absolute URL, use a fully-qualified URL starting with
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.
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.
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
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.
Bindingattribute 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
usernameattribute in the
saml:AttributeStatementelement. The assertion’s attribute type must be
xs:string(it should not be typed as
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
usernamevalue, use the following command:
tsm authentication saml map-assertions --user-name <USER-NAME>
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
email@example.com, we recommend using
For more information, see User Management in Active Directory Deployments.