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.
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 certificate must either have 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 that a PKCS#8 file with a null password is not supported.
- Password-protected key files are not supported in site-specific SAML deployments.
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.
If your organization 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 Configuring Proxies for Tableau Server.
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.
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. 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, you must disable the Enable automatic logon option.
Server-wide SAML authentication and site-specific SAML authentication. 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.
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. 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 configured user name 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.
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 user name and domain attributes for a user in the SAML assertion. Both these user name and domain attributes must match exactly the user name and domain stored in Tableau Server. Use the
domain\usernameformat for the user attribute and the fully qualified domain name (FQDN) for the domain attribute. If the domain attribute isn't included, the domain of the Tableau Server computer, also referred to as the default domain, will be used for all users. If users are not in the same domain as the Tableau Server computer, the exclusion of the domain attribute will cause sign in errors.
Signature algorithm: Many IdPs default to SHA256. A mismatch between the IdP and Tableau Server signature algorithms will cause SAML authentication failures. For example, your idP may have required SHA-256 signed assertions, but your incoming assertions or uploaded certificates are signed with SHA-1, you can force outgoing SAML assertions to be signed with SHA-256.
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
Single Log Out (SLO): Tableau Server supports service provider (SP)-initiated SLO for both server-wide SAML and site-specific SAML. However, Tableau Server does not support identity provider (IdP)-initiated SLO.
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:When 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.
When 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.
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:
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:
Note: SP-initiated SLO is supported for server-wide and site-specific SAML. However, IdP-initiated SLO is not supported.
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.
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 behavior: 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
AuthNContextClassRefattribute 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.
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 only supports 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
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
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.