samlSettings Entity
This article contains a template and reference for configuring server-wide SAML on Tableau Server, using a configuration file with keys and values for the samlSettings
entity. This information supplements the SAML configuration steps in Configure Server-Wide SAML.
To create a SAML configuration template and apply it to Tableau Server, complete the following steps:
Review the following two sections that describe the template and how it’s structured (Template categories and definitions and samlSettings configuration template).
Paste the JSON code shown in the template into a new text file, and save it using a .json extension.
Use the SAML configuration entity reference to help you provide values where required.
Add optional key/value pairs specific to your environment. For example, if your SAML certificate key file requires a passphrase, you will need to specify the password in the
wgserver.saml.key.passphrase
parameter using the tsm configuration set command.
Template categories and definitions
The template uses placeholders for each key value. These placeholders are categorised as follows:
Required: Attributes with the
"required"
value must be replaced with valid data before you run the configuration command. Review the configuration file reference for valid values.Hard-coded: Attribute names that are prepended with an underscore (_), for example
"_type"
hold hard-coded values. Do not change these values.Default values: Attributes that are set to a value that is not
"required"
are default values. These are required attributes that you can change as appropriate for your environment.Empty sets: Values that are empty (
""
) can be passed as they are, or you can provide a value for your installation.
Important: All entity options are case sensitive.
samlSettings configuration template
Paste this code into a text file and customise it for your environment, using the reference below.
{ "configEntities": { "samlSettings": { "_type": "samlSettingsType", "enabled": true, "returnUrl": "required", "entityId": "required", "certFile": "required", "keyFile": "required", "idpMetadataFile": "required", "idpDomainAttribute": "", "idpUsernameAttribute": "required" } } }
SAML configuration entity reference
The following list includes all of the options you can include with the "samlSettings"
entity set.
idpMetadataFile
Required. The path and file name for the XML file generated by the IdP. The XML metadata must include the user name attribute (assertion).
If you completed the steps described in Configure Server-Wide SAML the value you enter here would be:
/var/opt/tableau/tableau_server/data/saml/<metadata-file.xml>
enabled
true | false
Required. Indicates whether SAML authentication is enabled. Do not set this option to
true
before setting other required SAML configuration options.
returnURL
This is typically the external URL that Tableau Server users enter in their browser to access the server, such as
https://tableau_server.example.com
. This value is used to create the ACS URL attribute when configuring the IdP.
entityId
Required. Service provider (in this case, Tableau Server) entity ID value.
Identifies your Tableau Server configuration to the IdP. We recommend that you enter the same value as the
returnURL
option.
idpUsernameAttribute
Required. In the IdP metadata, find the attribute that is used to specify user name values, and enter the name of that attribute. Default is
username
.
certFile
Required. Enter the location and file name of the x509 certificate (.crt) file for SAML. For example:
/var/opt/tableau/tableau_server/data/saml/<file.crt>
For more information, see SAML Requirements and Configure Server-Wide SAML.
keyFile
Required. Specify the location of the private key (.key) file that accompanies the certificate file. For example:
/var/opt/tableau/tableau_server/data/saml/<file.key>
Note: If you are using a RSA PKCS#8 key that requires a passphrase, you must set the passphrase using a configKey entity (see Configuration File Example) or with tsm configuration set. The key for the passphrase using these methods is
wgserver.saml.key.passphrase
. The value must be a non-null string.
idpDomainAttribute
For organisations that use LDAP or Active Directory, this value specifies which SAML attribute Tableau Server will reference to determine the domain name. For example, if your IdP specifies the domain name in the
domain
attribute, then you would specifydomain
for this value. Note: For organisations that have users signing in from multiple domains, this value is required.If you do not provide a value for this key, the value used depends on the Tableau Server identity store setting:
For local identity store, the
idpDomainAttribute
value is ignored.For Active Directory or LDAP identity stores, Tableau uses the FQDN from the configuration setting
wgserver.domain.default
.To get the value for
wgserver.domain.default
, you can run the following command:tsm configuration get --key wgserver.domain.default
desktopNoSAML
true | false
Optional. Allow users to use SAML authentication when they sign in from Tableau Desktop.
By default this is not set, so the effective behaviour is equivalent to setting it to false. If single sign-on from Tableau client applications does not work with your IdP, you can set this to true to disable SAML authentication through Tableau Desktop.
appNoSAML
true | false
Optional. Allow using SAML to sign in from older versions of Tableau Mobile app. Devices running Tableau Mobile app version 19.225.1731 and higher ignore this option. To disable devices running Tableau Mobile app version 19.225.1731 and higher, disable SAML as a client login option on Tableau Server.
logoutEnabled
true | false
Optional. Enables single logout for users who have logged on with SAML. The default is
true
.The IdP configuration metadata must include a single logout endpoint with POST binding.
This setting applies only for server-wide SAML
When set to
false
, Tableau Server will not attempt single logout.
logoutUrl
Optional. Enter the URL to redirect to after users sign out of the server. Setting this option requires that
logoutEnabled
is set totrue
.By default this is the Tableau Server sign-in page. You can specify an absolute or a relative URL.
maxAuthenticationAge
Optional. Specifies the maximum number of seconds allowed between a user’s authentication with the IdP and processing of the AuthNResponse message. The default value is -1, which means maxAuthenticationAge is unset or ignored by default. Prior to February 2022, the default value was 7200 (2 hours).
To optimise session length, use the same timeout value as is set on the IdP.
maxAssertionTime
Optional. Specifies the maximum number of seconds, from creation, that a SAML assertion is usable. Default value is 3000 (50 minutes).
sha256Enabled
true | false
Optional. The type of signature Tableau Server will use when sending messages to the IdP. When set to
true
, Tableau Server will sign messages with the SHA 256 signature algorithm. When set tofalse
, Tableau Server will sign messages with SHA 1. Default istrue
.This option sets the signature algorithm to the following messages that Tableau Server signs:
- AuthnRequest messages when
signRequests
is enabled. - LogoutRequest messages if
logoutEnabled
is enabled.
- AuthnRequest messages when
signRequests
true | false
Optional. Specifies whether Tableau Server will sign the AuthnRequests that are sent to the IdP. Signed requests are not always necessary for all IdPs. We recommend signing requests to ensure the most secure option when configuring SAML. To verify whether your IdP accepts signed request, inspect the IdP metadata: if
wantAuthnRequestsSigned
is set totrue
, then your IdP will accept signed requests.Default value is
true
. To disable signed requests, set this option tofalse
.
acceptableAuthnContexts
Optional. Sets the
AuthNContextClassRef
SAML attribute. This optional attribute enforces validation of certain authentication ‘contexts’ in IdP initiated flows. Set a comma-separated set of values for this attribute. 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 option blank will result in default behaviour: any successfully authenticated SAML response will result in a user being granted a session within Tableau Server.
iFramedIdpEnabled
true | false
Optional. Default value is
false
, meaning that when users select the sign-in button on an embedded view, the IdP’s sign-in form opens in a pop-up window.When you set it to true, and a server SAML user who is already signed in navigates to a web page with an embedded view, the user will not need to sign in to see the view.
You can set this to true only if the IdP supports signing in within an iframe. The iframe option is less secure than using a pop-up, so not all IdPs support it. If the IdP sign-in page implements clickjack protection, as most do, the sign-in page cannot display in an iframe, and the user cannot sign in.
If your IdP does support signing in via an iframe, you might need to enable it explicitly. However, even if you can use this option, it disables Tableau Server clickjack protection for SAML, so it still presents a security risk.
Pass the configuration file to Tableau Server
After you have provided an appropriate value for each entity you include in the configuration template, use the following commands to pass the .json file and apply settings to Tableau Server.
tsm settings import -f path-to-file.json
tsm pending-changes apply
See also
After you complete the initial SAML configuration, use tsm authentication mutual-ssl <commands> to set additional values.
For the command-line reference for configuring SAML, see tsm authentication saml <commands>.