identityStore Entity

Tableau Server requires an identity store to store user and group information. Review Authentication and Identity Store topics before configuring the identity store for the first time. After you have installed the identity store on Tableau Server, you cannot change it without reinstalling the server.

Important: All entity options are case sensitive.

Before you begin

Review the following information:

If you will not be using the local identity store, then you will be using some version of LDAP. In this case, work with your directory/LDAP administrator to configure Tableau Server for your LDAP schema and bind requirements.
Tableau Server configuration is optimised for Active Directory. If you are installing into Active Directory, we recommend configuring the identity store with Configure Initial Node Settings.
LDAP bind is independent of user authentication. For example, you can configure Tableau Server to use simple bind to authenticate to the LDAP directory and then configure Tableau Server to authenticate users with Kerberos after installation.
Do not connect to LDAP with simple bind over an unsecured connection. By default, LDAP with simple bind sends data in cleartext. Use LDAPS to encrypt traffic with simple bind. See Configure Encrypted Channel to LDAP External Identity Store.
To use Kerberos authentication for the LDAP bind with Tableau Server service, then you'll need a keytab file for GSSAPI bind, as described in the sections below. See also, Understanding Keytab Requirements. In the context of Kerberos, GSSAPI bind is all you need during the base installation of Tableau Server. After you install the server, you can then configure Kerberos for user authentication and Kerberos delegation to data sources.
In this topic, we make the distinction between LDAP (the protocol for connecting to directory services) and an LDAP server (an implementation of a directory service). For example, slapd is an LDAP server that is part of the OpenLDAP project.
Validate the LDAP configuration before initialising the server, see Configure Initial Node Settings.
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 initialised Tableau Server, do not attempt to re-import the JSON file. Rather, make individual key changes with native tsm commands or with tsm configuration set. See External Identity Store Configuration Reference.

Configuration templates

The JSON templates in this section are used to configure Tableau Server with different identity store scenarios. Unless you're configuring a local identity store, you will need to select and edit a configuration file template that is specific to your LDAP environment.

Consider using the Tableau Identity Store Configuration Tool(Link opens in a new window) to help generate your LDAP JSON configuration file. 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.

Select an identity store configuration template to edit:

Local
LDAP - Active Directory
OpenLDAP - GSSAPI Bind
OpenLDAP - Simple Bind

For more explanation about configuration files, entities and keys see Configuration File Example.

Local

Configure local as the identity store type if your organisation does not already have an Active Directory or LDAP server for user authentication. When you select local as the identity store type, you use Tableau Server to create and manage users.

An alternative way to configure Tableau Server for local identity store is to run Setup GUI and select "Local" during the installation process. See Configure Initial Node Settings.

{
  "configEntities": {
    "identityStore": {
       "_type": "identityStoreType",
       "type": "local"
     }
   }
}

Important

The LDAP configuration templates below are examples. The templates, as presented, will not configure LDAP connectivity in your organisation. You must work with your directory administrator to edit the LDAP template values for a successful deployment.

Additionally, all files that are referenced in configEntities must be located on the local computer. Do not specify UNC paths.

LDAP - Active Directory

Tableau Server configuration is optimised for Active Directory. If you are installing into Active Directory, configure the identity store with Configure Initial Node Settings.

An encrypted connection to Active Directory is required.See Configure Encrypted Channel to LDAP External Identity Store.

If for some reason you are unable to configure the identity store to communicate with Active Directory with TSM web interface, use this JSON template to configure Tableau Server to connect to Active Directory. This template uses GSSAPI (Kerberos) bind to authenticate Tableau Server service to Active Directory. Tableau Server includes support for Active Directory schema. Therefore, if you set the "directoryServiceType" option to "activedirectory" then you do not need to provide schema info in the "identityStoreSchemaType" option.

If you are installing Tableau Server for Linux into Active Directory, and the computer where you are installing Tableau Server is already joined to the domain, then the computer will already have a Kerberos configuration file and a keytab file. Strictly speaking, you can use these files for GSSAPI bind, but we don't recommend using them. Instead, contact your Active Directory administrator and request a keytab specifically for the Tableau Server service.

{
  "configEntities":{
    "identityStore": {
		"_type": "identityStoreType",
		"type": "activedirectory",
		"domain": "your-domain.lan",
		"nickname": "YOUR-DOMAIN-NICKNAME",
		"directoryServiceType": "activedirectory",
		"bind": "gssapi",
		"kerberosKeytab": "<path to local key tab file>",
		"kerberosConfig": "/etc/krb5.conf",
		"kerberosPrincipal": "your-principal@YOUR.DOMAIN"
		}
	}
}

We recommend binding to Active Directory with GSSAPI. However, you can connect with simple bind and LDAPS. To connect with simple bind, change bind to simple, remove the three Kerberos entities, and add the port/sslPort, username, and password options. The following example shows Active Directory with simple bind json.

{
  "configEntities":{
	"identityStore": {
		"_type": "identityStoreType",
		"type": "activedirectory",
		"domain": "your-domain.lan",
		"nickname": "YOUR-DOMAIN-NICKNAME",
		"directoryServiceType": "activedirectory",
		"hostname": "optional-ldap-server", 
		"sslPort": "636",
		"bind": "simple",
		"username": "username",
		"password": "password"	
		}
	}
}

OpenLDAP - GSSAPI bind

Use the template below to configure OpenLDAP with GSSAPI bind. Do not use this template if your organisation is running Active Directory. If you are installing into Active Directory, use the template above, LDAP - Active Directory.

In most cases, organisations that use OpenLDAP with GSSAPI (Kerberos) will use a keytab file to store credentials. In the following example, a keytab file is used for authentication credentials.

However, you can provide credentials through the username and password entities.

You can also specify both a keytab and a username and password pair. In this case, Tableau Server will attempt to use the keytab, but if authentication fails for any reason it will fallback and use the username and password credentials.

{
  "configEntities":{
		"identityStore": {
			"_type": "identityStoreType",
			"type": "activedirectory",
			"domain": "your-domain.lan",
			"nickname": "YOUR-DOMAIN-NICKNAME",
			"directoryServiceType": "openldap",
			"bind": "gssapi",
			"kerberosKeytab": "<path to local key tab file>",
			"kerberosConfig": "/etc/krb5.conf",
			"kerberosPrincipal": "your-principal@YOUR.DOMAIN",
			"identityStoreSchemaType": {
			   "userBaseFilter": "(objectClass=inetOrgPerson)",
			   "userUsername": "user",
			   "userDisplayName": "displayname",
			   "userEmail": "email",
			   "userCertificate": "certificate",
			   "userThumbnail": "thumbnail",
			   "userJpegPhoto": "photo",
			   "groupBaseFilter": "(objectClass=groupofNames)",
			   "groupName": "groupname",
			   "groupEmail": "groupemail",
			   "groupDescription": "groupdescription",
			   "member": "member",
			   "distinguishedNameAttribute": "",
			   "serverSideSorting": "",
			   "rangeRetrieval": "",
			   "userClassNames": ["inetOrgPerson","someClass2"],
			   "groupClassNames": ["groupOfUniqueNames1","groupOfUniqueNames2"]
			   }
		   }			
	  }			
}

OpenLDAP - Simple bind

{
  "configEntities":{
		"identityStore": {
			"_type": "identityStoreType",
			"type": "activedirectory",
			"domain": "my.root",
			"nickname": "",
			"hostname": "optional-ldap-server",
			"port": "389",
			"directoryServiceType": "openldap",
			"bind": "simple",
			"username": "cn=username,dc=your,dc=domain",
			"password": "password",
			"identityStoreSchemaType": {
			   "userBaseFilter": "(objectClass=inetOrgPerson)",
			   "userUsername": "user",
			   "userDisplayName": "displayname",
			   "userEmail": "email",
			   "userCertificate": "certificate",
			   "userThumbnail": "thumbnail",
			   "userJpegPhoto": "photo",
			   "groupBaseFilter": "(objectClass=groupofNames)",
			   "groupName": "groupname",
			   "groupEmail": "groupemail",
			   "groupDescription": "groupdescription",
			   "member": "member",
			   "distinguishedNameAttribute": "",
			   "serverSideSorting": "",
			   "rangeRetrieval": "",
			   "userClassNames": ["inetOrgPerson","someClass2"],
			   "groupClassNames": ["groupOfUniqueNames1","groupOfUniqueNames2"]
			   }
		 }
  }
}

Configuration template reference

Shared identity store options

type: Where you want to store user identity information. Either local or activedirectory. (If you want to connect to any LDAP server, select activedirectory.)

domain: The domain of the computer where you installed Tableau Server.

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

LDAP GSSAPI bind options

directoryservicetype: The type of directory service that you want to connect to. Either activedirectory or openldap.

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

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

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

LDAP simple bind options

directoryservicetype: The type of directory service that you want to connect to. Either activedirectory or openldap.

hostname: 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 only. If user/group queries are in other domains (not in the primary domain), Tableau Server will not use this value, but instead will query DNS to identify the appropriate domain controller.

port: Use this option to specify the non-secure port of the LDAP server. Plaintext is usually 389.

sslPort: Use this option to enable LDAPS. Specify the secure port of the LDAP server. LDAPS is usually port 636. To use LDAPS you must also specify hostname option. See Configure Encrypted Channel to LDAP External Identity Store.

username: 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, you might enter cn=username,dc=your-local-domain,dc=lan.

password: The password of the user that you want to use to connect to the LDAP server.

LDAPS and subdomains

If you're enabling LDAPS in Active Directory and connecting to subdomains, you'll need to run the following TSM command to configure the LDAPS port (TCP 636) for subdomains. The command takes arguments that specify subdomainFQDN:port.

Example: tsm configuration set -k wgserver.domain.ldap.domain_custom_ports -v subdomain1.lan:636,subdomain2.lan:636,subdomain3.lan:636

For more information, see tsm configuration set Options.

Shared LDAP options

The following options can be set for generic LDAP, OpenLDAP, or Active Directory implementations.

bind: The way that you want to authentication communication from the Tableau Server service to the LDAP directory service. Enter gssapi for GSSAPI (Kerberos).

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

root

LDAP only. Do not specify for Active Directory.

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

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

`identityStoreSchemaType` options

If you configure an LDAP connection to an LDAP server, you can enter schema information specific to your LDAP server in the identityStoreSchemaType object.

Important If you are connecting to Active Directory ("directoryServiceType": "activedirectory"), then do not configure these options.

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

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

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

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

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

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

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

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

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

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

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

member: The attribute that describes the list of users in a group.

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

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

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

userClassNames: 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. 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”].

Importing the JSON file

After you have finished editing the JSON file, pass the file and apply settings with the following commands:

tsm settings import -f path-to-file.json

tsm pending-changes apply

If the pending changes require a server restart, the pending-changes apply command will display a prompt to let you know a restart will occur. This prompt displays even if the server is stopped, but in that case, there is no restart. You can suppress the prompt using the --ignore-prompt option, but this does not change the restart behaviour. If the changes do not require a restart, the changes are applied without a prompt. For more information, see tsm pending-changes apply.

Thanks for your feedback!

Your feedback has been successfully submitted. Thank you!

Tableau Server on Linux Help