External Identity Store Configuration Reference

Tableau Server supports connecting to an external directory using LDAP. In this scenario, Tableau Server imports users from the external LDAP directory into the Tableau Server repository as system users.

This topic provides a description of all LDAP-related configuration options Tableau Server supports. If you are connecting to Active Directory, we strongly recommend that you automatically configure the LDAP connection with Tableau Server as part of Setup, rather than configuring the connection manually. See Configure Initial Node Settings.

The options listed in this reference can be used for any LDAP-compliant directory. If you do not have experience configuring LDAP, then work with your directory administrator, or with an LDAP expert.

This is a reference topic. For more information about how Tableau Server stores and manages users, start with Identity Store.

Configuration methods

Configuration parameters that enable Tableau Server to connect to your LDAP directory are stored in .yml files. These files are managed and synchronized by various services in Tableau Server. Updating the .yml files must be done using a Tableau Services Manager (TSM) interface.

Do not attempt to update .yml files directly with a text editor. TSM must manage all updates for proper operation.

The .yml configuration files are composed of key-value pairs. For example, the key, wgserver.domain.username, takes a username as a value. This key defines the username that will be used to authenticate to the LDAP directory during the bind operation.

There are four different TSM methods that can set yml key values. The four methods are described here, using the wgserver.domain.username key as an example to illustrate the different methods:

  • configKey key-value pairs—You can update a .yml configuration file key by updating the wgserver.domain.username key running tsm configuration set Options, or by including the key in a JSON configuration file under a configKey entity. See Configuration File Example.

    The configKey key-value pairs in a JSON configuration file are the same as those used for tsm configuration set but they are set differently. This topic refers to both of these methods as configKey.

    Unlike when using configEntities and native tsm commands that are described below, configKey input is not validated. When you set an option with a configKey, the value that you enter is copied as a literal string to the underlying .yml configuration files. For example, for a key where true or false are the valid inputs, when you configure the key using a configKey key-value pair, you can enter an arbitrary string value and it will be saved for the key. In such cases, invalid values will undoubtedly lead to LDAP configuration errors.

    We recommend using configKeys only when no option exists to set the configuration with the other three options listed below (configEntities, a native tsm command, or the TSM Web UI). When using configKeys be sure to double-check your values and be sure to mind case-sensitivity.

  • configEntities JSON—You can update a .yml configuration file by passing the username option in a configEntities JSON.

    When you configure a value using configEntities options in a JSON file, the values are validated before they are saved. Values are case-sensitive. For details on how to configure a value using configEntities, see the identityStore Entity example. The JSON file is imported with the tsm settings import command. The options available for configEntities are a subset of all the .yml key-value pairs.

    Validation means that the import command will only succeed if all the values in the JSON file are valid data types. For example, if you enter no for a value that only accepts true or false, then you will receive an error and the configuration is not imported.

    You can only import JSON configuration files only as part of the initial configuration. If you need to make LDAP changes after you have imported the JSON configuration file and initialized Tableau Server, do not attempt to re-import the JSON file. Instead, make individual key changes with native tsm commands if available, or using configKeys and tsm configuration set.

  • Native tsm commands—You can update a .yml configuration file by passing the ldapuser option with the native tsm commandtsm user-identity-store. As with configEntities, values that you enter with the native tsm command are validated before they are saved.

    Not all key-value pairs in a .yml file can be set using native tsm commands.

  • TSM GUI—You can set configuration values during Setup, using the TSM GUI. If you are connecting to Active Directory, and configure the Tableau identity store during Setup, with the GUI, then you are prompted for an account with AD read access. The wgserver.domain.username key is set when you enter credentials.

    This scenario only works if you are connecting to Active Directory. Tableau Server does not support arbitrary LDAP configuration as part of the GUI Setup process.

Consider using the Tableau Identity Store Configuration Tool(Link opens in a new window) to generate your LDAP json configuration file. The Tableau Identity Store Configuration Tool will also generate a list of key/value pairs that you can set by running tsm configuration set Options. The tool itself is not supported by Tableau. However, using a JSON file created by the tool instead of creating a file manually does not change the supported status of your server.

Configuring Active Directory

If you are configuring Tableau Server to use Active Directory, we recommend using the TSM Web UI during installation. The TSM Web UI is optimized to configure Tableau Server for Active Directory with the minimum necessary input. See Configure Initial Node Settings.

Configuration reference table

configEntities option

(Options are case sensitive)

Native tsm command

configKey

(Used with tsm configuration set command or in the configKeys section of a JSON file)

Scenario

Notes

type N/A wgserver.authenticate AD, LDAP, Local Where you want to store user identity information. Values: local or activedirectory.

If you want to connect to any LDAP server, enter activedirectory.

sslPort N/A wgserver.domain.ssl_port AD, LDAP Use this option to specify the secure port of the LDAP server. We recommend secure LDAP for simple bind. LDAPS is usually port 636.
N/A N/A wgserver.domain.ldap.starttls.enabled AD, LDAP

This key is new in version 2021.1. Values: true or false.

port N/A wgserver.domain.port AD, LDAP Use this option to specify the non-secure port of the LDAP server. Plaintext is usually 389.
domain domain wgserver.domain.default AD In Active Directory environments, specify the domain where Tableau Server is installed, for example, "example.lan".

For non-AD LDAP: the string you enter for this value is displayed in the "Domain" column of user management tools. You can enter an arbitrary string, but the key cannot be blank.

This key is redundant with wgserver.domain.fqdn. The values for both keys must be the same.

Native tsm command: Uses tsm user-identity-store set-connection [options] command.

username ldapusername wgserver.domain.username AD, LDAP The user name that you want to use to connect to the directory service.

The account that you specify must have permission to query the directory service.

For Active Directory, enter the username, for example, jsmith.

For LDAP servers, enter the distinguished name (DN) of the user that you want to use to connect. For example, "cn=jsmith,dc=example,dc=lan".

Native tsm command: Uses tsm user-identity-store set-connection [options] command.

password ldappassword wgserver.domain.password AD, LDAP The password of the user account that you will use to connect to the LDAP server.

Native tsm command: Uses tsm user-identity-store set-connection [options] command.

directoryServiceType N/A wgserver.domain.directoryservice.type AD, LDAP The type of LDAP directory service that you want to connect to. Values:activedirectory or openldap.
kerberosPrincipal kerbprincipal wgserver.domain.ldap.principal AD, LDAP The service principal name for Tableau Server on the host machine. The keytab must have permission for this principal. Do not use the existing system keytab at /etc/krb5.keytab. Rather, we recommend that you register a new service principal name. To see principals in a given keytab, run the klist -k command. See Understanding Keytab Requirements.

Native tsm command: Uses tsm user-identity-store set-connection [options] command.

hostname hostname wgserver.domain.ldap.hostname AD, LDAP The hostname of the LDAP server. You can enter a hostname or an IP address for this value. The host that you specify here will be used for user/group queries on the primary domain. In the case where user/group queries are in other domains, Tableau Server will query DNS to identify the appropriate domain controller.

Native tsm command: Uses tsm user-identity-store set-connection [options] command.

membersRetrievalPageSize N/A wgserver.domain.ldap.members.retrieval.page.size AD, LDAP

This option determines the maximum number of results returned by an LDAP query.

For example, consider a scenario where Tableau Server is importing an LDAP group that contains 50,000 users. Attempting to import such a large number of users in a single operation is not a best practice. When this option is set to 1500, Tableau Server imports the first 1500 users in the first response. After those users are processed, Tableau Server requests the next 1500 users from the LDAP server, and so forth.

We recommend that you modify this option only to accommodate the requirements of your LDAP server.

N/A N/A wgserver.domain.ldap.connectionpool.enabled AD, LDAP When this options is set to true, Tableau Server will attempt to reuse the same connection when sending queries to the LDAP server. This behavior decreases the overhead of having to re-authenticate with the LDAP server on each new request. Connection pooling only works with simple bind and TSL/SSL bind connections. Connection pooling is not supported for GSSAPI bind connections.
N/A N/A wgserver.domain.accept_list AD Allows connection from Tableau Server to secondary Active Directory domains. A secondary domain is one that Tableau Server connects to for user synchronization, but is a domain where Tableau Server is not installed. To ensure that Tableau Server can connect to other Active Directory domains, you must specify the trusted domains by setting the wgserver.domain.accept_list option with TSM. For more information, see wgserver.domain.accept_list .
N/A N/A

wgserver.domain.whitelist

AD

Important: Deprecated as of version 2020.4.0. Use wgserver.domain.accept_list instead.

Allows connection from Tableau Server to secondary Active Directory domains. A secondary domain is one that Tableau Server connects to for user synchronization, but is a domain where Tableau Server is not installed. To ensure that Tableau Server can connect to other Active Directory domains, you must specify the trusted domains by setting the wgserver.domain.whitelist option with TSM. For more information, see wgserver.domain.whitelist .

kerberosConfig

kerbconfig

No direct mapping AD, LDAP

The path to the Kerberos configuration file on the local computer. If you are installing into Active Directory, we don't recommend using the existing Kerberos configuration file or keytab file that may already be on the domain-joined computer. See Identity Store

Native tsm command: Uses tsm user-identity-store set-connection [options] command.

kerberosKeytab kerbkeytab No direct mapping AD, LDAP

The path to the Kerberos keytab file on the local computer. It is recommended that you create a keytab file with keys specifically for Tableau Server service and that you do not share the keytab file with other applications on the computer. For example, on Linux, you might place the keytab file in the /var/opt/tableau/keytab directory.

Native tsm command: Uses tsm user-identity-store set-connection [options] command.

nickname N/A wgserver.domain.nickname AD, LDAP

The nickname of the domain. This is also referred to as the NetBIOS name in Windows/Active Directory environments. The nickname option is required for all LDAP entities. The value cannot be null. If your organization does not require a nickname/NetBIOS, then pass a blank key, for example: "".

root N/A wgserver.domain.ldap.root LDAP If you do not use a dc component in the LDAP root or you want to specify a more complex root you need to set the LDAP root. Use the "o=my,u=root" format. For example, for the domain, example.lan, the root would be "o=example,u=lan".
serverSideSorting N/A wgserver.domain.ldap.server_side_sorting LDAP Whether the LDAP server is configured for server-side sorting of query results. If your LDAP server supports server-side sorting, set this option to true. If you are unsure whether your LDAP server supports this, enter false, as misconfiguration may cause errors.
rangeRetrieval N/A wgserver.domain.ldap.range_retrieval LDAP Whether the LDAP server is configured to return a range of query results for a request. This means that groups with many users will be requested in small sets instead of all at once. LDAP servers that support range retrieval will perform better for large queries. If your LDAP server supports range retrieval, set this option to true. If you are unsure whether your LDAP server supports range retrieval, enter false, as misconfiguration may cause errors.
bind N/A wgserver.domain.ldap.bind LDAP The way that you want to secure communication to the directory service. Enter simple for LDAP unless you are connecting to an LDAP server with Kerberos. For Kerberos, enter gssapi.
N/A N/A wgserver.domain.ldap.domain_custom_ports LDAP

Note: This key is only supported for Tableau Server on Linux.

Allows you to map child domains and their LDAP ports. Domain and port are separated by a colon (:) and each domain:port pair is separated by a comma (,) using this format: FQDN1:port,FQDN2:port

Example: tsm configuration set -k wgserver.domain.ldap.domain_custom_ports -v childdomain1.lan:3269,childdomain2.lan:3269,childdomain3.lan:389

distinguishedNameAttribute N/A wgserver.domain.ldap.dnAttribute LDAP

The attribute that stores the distinguished names of users. This attribute is optional, but it greatly improves the performance of LDAP queries.

Important:  Do not set this option as part of the initial configuration. Only set this after you have validated overall LDAP functionality. You must have a dnAttribute set in your organization before setting this key.

groupBaseDn N/A wgserver.domain.ldap.group.baseDn LDAP

Use this option to specify an alternative root for groups. For example, if all of your group are stored in the base organization called "groups," then enter "o=groups".

N/A classnames wgserver.domain.ldap.group.classnames LDAP

By default Tableau Server looks for LDAP group object classes containing the string “group”. If your LDAP group objects do not fit the default class name, override the default by setting this value. You can provide multiple classnames separated by commas.

If your group names include commas, you must escape them with a backslash (\). For example, if you have a group name, groupOfNames, top, then enter "groupOfNames\, top".

Tableau LDAP implementation interprets LDAP objects as either user or group. Therefore, be sure that you are entering the most specific class name. Overlapping class names between users and groups may cause conflicts.

Native tsm command: Uses tsm user-identity-store set-group-mappings [options] command.

groupBaseFilter basefilter wgserver.domain.ldap.group.baseFilter LDAP

The filter that you want to use for groups of users of Tableau Server. You might specify an object class attribute and an organization unit attribute. For example:

"(&(objectClass=groupofNames)(ou=Group))"

If "(&(objectClass=inetOrgPerson)(ou=People))" doesn't work in your LDAP implementation, then specify the base filter that works for your Tableau user base.

This is a required key. It cannot be blank.

Native tsm command: Uses tsm user-identity-store set-group-mappings [options] command.

groupName groupname wgserver.domain.ldap.group.name LDAP

The attribute that corresponds to group names on your LDAP server.

Native tsm command: Uses tsm user-identity-store set-group-mappings [options] command.

groupEmail groupemail wgserver.domain.ldap.group.email LDAP

The attribute that corresponds to group email addresses on your LDAP server.

Native tsm command: Uses tsm user-identity-store set-group-mappings [options] command.

groupDescription description wgserver.domain.ldap.group.description LDAP

The attribute that corresponds to group descriptions on your LDAP server.

Native tsm command: Uses tsm user-identity-store set-group-mappings [options] command.

member member wgserver.domain.ldap.group.member LDAP

Specify the LDAP attribute that contains a list of distinguished names of users that are part of that group.

Native tsm command: Uses tsm user-identity-store set-group-mappings [options] command.

N/A N/A wgserver.domain.ldap.group.memberURL LDAP Specify the name of the LDAP attribute that stores the LDAP query for dynamic groups.
userBaseDn N/A wgserver.domain.ldap.user.baseDn LDAP Use this option to specify an alternative root for users. For example, if all of your users are stored in the base organization called "users," then enter "o=users".
N/A classnames wgserver.domain.ldap.user.classnames LDAP

By default Tableau Server looks for LDAP user object classes containing the string “user” and “inetOrgPerson”. If your LDAP user objects do not use these default class names, override the default by setting this value. You can provide multiple classnames separated by commas. For example: "userclass1, userclass2".

If your names include commas, you must escape them with a backslash (\). For example, if you have a name, Names, top, then enter "Names\, top".

Native tsm command: Uses tsm user-identity-store set-user-mappings [options] command.

userBaseFilter basefilter wgserver.domain.ldap.user.baseFilter LDAP

The filter that you want to use for users of Tableau Server. You might specify an object class attribute and an organization unit attribute.

For example:

"(&(objectClass=inetOrgPerson)(ou=People))"

Native tsm command: Uses tsm user-identity-store set-user-mappings [options] command.

userUsername ldapusername wgserver.domain.ldap.user.username LDAP

The attribute that corresponds to user names on your LDAP server.

Native tsm command: Uses tsm user-identity-store set-user-mappings [options] command.

userDisplayName displayname wgserver.domain.ldap.user.displayname LDAP

The attribute that corresponds to user display names on your LDAP server.

Native tsm command: Uses tsm user-identity-store set-user-mappings [options] command.

userEmail email wgserver.domain.ldap.user.email LDAP

The attribute that corresponds to user email addresses on your LDAP server.

Native tsm command: Uses tsm user-identity-store set-user-mappings [options] command.

userCertificate certificate wgserver.domain.ldap.user.usercertificate LDAP

The attribute that corresponds to user certificates on your LDAP server.

Native tsm command: Uses tsm user-identity-store set-user-mappings [options] command.

N/A thumbnail wgserver.domain.ldap.user.thumbnail LDAP

The attribute that corresponds to user thumbnail images on your LDAP server.

Native tsm command: Uses tsm user-identity-store set-user-mappings [options] command.

userJpegPhoto jpegphoto wgserver.domain.ldap.user.jpegphoto LDAP

The attribute that corresponds to user profile images on your LDAP server.

Native tsm command: Uses tsm user-identity-store set-user-mappings [options] command.

memberOf memberof wgserver.domain.ldap.user.memberof LDAP

Group that the user is a member of.

Native tsm command: Uses tsm user-identity-store set-user-mappings [options] command.

groupClassNames N/A wgserver.domain.ldap.group.classnames LDAP

By default Tableau Server looks for LDAP group object classes containing the string “group”. If your LDAP group objects do not fit the default class name, override the default by setting this value.

For configEntity: This option takes a list of strings, which requires passing each class in quotes, separated by a comma (no space) and within brackets. For example: ["basegroup","othergroup"].

For configKey: Enter each class, separated by a comma (no space) and within double quotes. For example: "basegroup,othergroup”.

userClassNames N/A wgserver.domain.ldap.user.classnames LDAP

By default Tableau Server looks for LDAP user object classes containing the string “user” and “inetOrgPerson”. If your LDAP user objects do not use these default class names, override the default by setting this value.

For configEntity: This option takes a list of strings, which requires passing each class in quotes, separated by a comma (no space) and within brackets. For example: ["userclass1",userclass2”].

For configKey: Enter each class, separated by a comma (no space) and within double quotes. For example: "userclass1,userclass2”.

Calculated configKeys

The following Kerberos-related configKeys are calculated and set according to multiple environmental inputs. As such, they must be set by the native tsm command or configEntities. Do not attempt to set these configKeys manually.

Calculated configKey To use the native TSM command: To use configEntity json:

wgserver.domain.ldap.kerberos.conf,

cfs.ldap.kerberos.conf

Set the Kerberos configuration file location with the kerbconfig option of tsm user-identity-store set-connection [options] command.

Set the Kerberos configuration file location with the kerberosConfig configEntity option.

wgserver.domain.ldap.kerberos.keytab,

cfs.ldap.kerberos.keytab

Set the Kerberos keytab file location with the kerbkeytab option of tsm user-identity-store set-connection [options] command. Set the Kerberos ketytab file location with the kerberosKeytab configEntity option.

Unsupported configKeys

Some unsupported configKeys are present in underlying .yml configuration files. The following keys are not intended for standard deployments. Do not configure these keys:

  • wgserver.domain.ldap.kerberos.login
  • wgserver.domain.ldap.guid
  • wgserver.domain.fqdn: this key is redundant with wgserver.domain.default. The values for both keys must be the same. Only update wgserver.domain.fqdn if the value does not match wgserver.domain.default.
Thanks for your feedback!