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, 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.
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.
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 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.
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.
IdP 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_nosamlcommand. 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:
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
tabadmin set wgserver.saml.logout.redirect_urlcommand.
To specify an absolute URL, use a fully-qualified URL starting with
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.
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, 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
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
Bindingattribute set to
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
usernamevalue 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 tabadmin set command. Set the
wgserver.saml.idpattribute.usernamevalue 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
email@example.com, we recommend using
For more information, see User Management in Active Directory Deployments.