Before you configure SAML on Tableau Server, make sure your environment meets the 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.
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 that a PKCS#8 file with a null password is not supported.
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).
Note: If you run Tableau Server on Linux, all external directory communication is configured and managed with a LDAP identity store. In the context of user and group synchronization, Tableau Server configured with LDAP identity store is equivalent to Active Directory. Active Directory synchronization features in Tableau Server function seamlessly with properly configured LDAP directory solutions.
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.
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.
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
firstname.lastname@example.org, we recommend using
For more information, see User Management in Active Directory Deployments.
Default signature algorithm: Tableau Server uses SHA1 signature algorithm. Many IdPs default to SHA256. A mismatch between the IdP and Tableau Server signature algorithms will cause SAML authentication failures. To change to SHA256, set the
sHA256Enabledconfiguration entity to
trueduring your initial configuration. See samlSettings Entity. You can also change to SHA256 by running the following TSM command:
tsm configuration set -k wgserver.saml.sha256 -v true
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: By default, both Tableau Desktop and the Tableau Mobile app allow SAML authentication.
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
--mobile-access disableoption is ignored by devices running Tableau Mobile app version 19.225.1731 and higher. To disable SAML for devices running these versions you must disable SAML as a client login option on Tableau Server.
For more information, see tsm authentication saml <commands>.
Distributed installations: Tableau Server clusters configured for SAML must have the same SAML certificate, SAML key, and SAML IdP metadata files on each node configured for an Application Server (vizportal) process. These files should also be in the same file path on each node.
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.
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. 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
This element appears in Tableau Server metadata and specifies the URL that the IdP will use for Tableau Server's logout endpoint:
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<tableauserver>/wg/saml/SingleLogout/index.html/>
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
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>
By default, Tableau Server will read the
usernameattribute in the AuthNResponse returned from the Idp. However, some IdPs may return a different attribute that is intended to identify the user. In this case, you may need to change the attribute that Tableau Server reads for the username. To authenticate successfully, the attribute's value that is returned from the IdP must match an actual username value of a Tableau Server user.
To change the SAML attribute that passes the
usernamevalue, run the following TSM command:
tsm authentication saml map-assertions --user-name <USER-NAME>.
See tsm authentication.