Was this page helpful?
Yes No

LDAP Configuration Reference

Tableau Server on Windows now includes Tableau Services Manager (TSM), which replaces the Configuration Utility and the tabadmin command line tool. If you need help for an earlier version of Tableau Server, see the Tableau Help page.

This topic provides a description of all LDAP-related configuration options. The option name that you specify is dependent on the tool that you use to configure LDAP:

  • configEntities: Options are set with a JSON file as described in identityStore Entity. Values that you enter as configEntites are validated before they are saved.

  • tsm CLI: Options are set with the tsm command line tool as described in tsm user-identity-store. Values that you enter with tsm CLI are validated before they are saved.

  • configKey: Options are set by running tsm configuration set Options. Alternatively, they may be included in a JSON configuration file as described in Configuration File Example. When you set an option with a configKey, the value that you enter is copied straight to the underlying .yml configuration file. Tableau Server does not validate the value. For this reason, we recommend using configKeys only when no option exists to set the configuration with configEntites, tsm CLI, or the TSM Web UI.

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

Consider using the Tableau Identity Store Configuration Tool 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.

configEntities

(Options are case sensitive)

tsm CLI configKey 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.
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, LDAP

In Windows Active Directory environments, specify the domain where Tableau Server is installed, for example, "example.lan". In LDAP directories, specify the root domain name in the same format. For example, if your root is "dc=my,dc=root", specify "my.root".

If your root does not use a dc component, see the root configEntity option below.

tsm CLI: 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".

tsm CLI: 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.

tsm CLI: 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 an existing keytab for the system. 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.

tsm CLI: 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.

tsm CLI: 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.
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

tsm CLI: 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.

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

nickname N/A wgserver.domain.nickname AD

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. 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.
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.
groupBaseDn basefilter 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".

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

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

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

groupBaseFilter N/A 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))"

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

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

tsm CLI: 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.

tsm CLI: 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.

tsm CLI: 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.

tsm CLI: 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".
userClassNames 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".

tsm CLI: 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))"

tsm CLI: 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.

tsm CLI: 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.

tsm CLI: 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.

tsm CLI: 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.

tsm CLI: 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.

tsm CLI: 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.

tsm CLI: 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.

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

Calculated configKeys

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

Calculated configKey To use the TSM CLI: 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 YAML 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