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 command tsm 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	Values: `true` or `false`. Beginning with version 2021.2, this key is set to `true` by default when Tableau Server is configured to connect to Active Directory. As a result, simple bind to LDAP directory is encrypted when a valid SSL/TLS certificate is present in the Tableau key store. For more information, see Configure Encrypted Channel to LDAP External Identity Store. This key is set to `false` by default when Tableau Server is configured to connect to a an arbitrary (but not Active Directory) LDAP server. This key was introduced (but not set) in version 2021.1.
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:

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.

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!

Your feedback has been successfully submitted. Thank you!

Tableau Server on Linux Help