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:

  1. Review the following two sections that describe the template and how it’s structured (Template categories and definitions and samlSettings configuration template).

  2. Paste the JSON code shown in the template into a new text file, and save it using a .json extension.

  3. Use the SAML configuration entity reference to help you provide values where required.

  4. 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.

  5. Pass the configuration file to Tableau Server.

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:

"C:\ProgramData\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:

"C:\ProgramData\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:

"C:\ProgramData\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 specify domain 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 to true.

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 to false, Tableau Server will sign messages with SHA 1. Default is true.

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.

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 to true, then your IdP will accept signed requests.

Default value is true. To disable signed requests, set this option to false.

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>.

 

Back to top
Thanks for your feedback!Your feedback has been successfully submitted. Thank you!