Tableau Server on Windows Help

To create and manage identity pools, you are required to programmatically make calls against the Identity Pools Methods(Link opens in a new window) using the Tableau REST OpenAPI. To add or manage users in an identity pool, you can use Tableau Server user interface (UI) directly or through the Tableau REST API.

The identity pools setup process is summarized in the following steps.

1. Configure Tableau Server and establish a session.
2. Provision users by setting up a new local identity store instance. Note: You can skip this step to use an existing local identity store or the external identity store you configured in TSM during Tableau Server setup.
   
3. Set up authentication to authenticate your users to Tableau Server using OpenID Connect (OIDC).
4. Create an identity pool that uses the identity store and OIDC authentication you configured.
5. Add users to an identity pool by using Tableau Server UI or REST API to enable users to sign in to Tableau Server.

After setup, you can test, manage, and troubleshoot your identity pools.

Note: You can use the Identity Pools(Link opens in a new window) Postman collection in the Salesforce Developer's Postman workspace to learn about, develop, and test the methods described in this topic.

Prerequisites

Before getting started with identity pools, the following requirements must be met:

• Integration with an OIDC identity provider (IdP), such as Okta, is already configured
• You are running Tableau Server 2023.1 or later
• You have performed the identity migration(Link opens in a new window) if you are running Tableau Server after upgrading from version 2021.4 or earlier

Get started

Step 1: Configure Tableau Server and establish a session

Enabling changes associated with setting up identity pools require a one-time TSM configuration and a declaration of session and host variables.

1. Open a command prompt as an administrator on the initial node (where TSM is installed) in the cluster.

2. Run the following command:

   1. tsm configuration set -k gateway.external_url -v http://<host>
   2. tsm pending-changes apply

   For example, you can run the following commands to configure your Tableau Server, http://myco:

   tsm configuration set -k gateway.external_url -v http://myco
tsm pending-changes apply

   For more information, see gateway.external_url(Link opens in a new window).

3. (Optional) Run the following commands to add a description for the initial pool (TSM configured):

   1. tsm configuration set -k wgserver.authentication.identity_pools.default_pool_description -v "<description>"
   2. tsm pending-changes apply

   For example, you can run the following commands to add a "Sign-in for MyCo employees" description:

   tsm configuration set -k wgserver.authentication.identity_pools.default_pool_description -v "Sign-in for MyCo employees"
tsm pending-changes apply

   For more information, see wgserver.authentication.identity_pools.default_pool_description(Link opens in a new window).
   

4. Sign in to Tableau Server as an administrator and do the following:

   1. Go to the browser’s developer tools and navigate to the application’s cookies.
   2. Note the workgroup_session_id value.

   For example, if working in Chrome, right-click anywhere on the Tableau Server homepage, right-click and select Inspect. Click Application from the top navigation pane and click Cookies from the left navigation pane. Under Cookies, click your Tableau Server name, like http://myco.com, and note the workgroup_session_id value in the center pane.

5. In the script or API developer tool you’re using to make identity pools requests using the Tableau REST OpenAPI, do the following:

   1. Add the workgroup_session_id value as a global variable.
   2. In addition, add port 80, host (your Tableau Server URL), and protocol (HTTP or HTTPS) to your global variables.

   For example, the following table shows the global variables necessary for your Tableau Server, http://myco.

Step 2: Set up an identity store

Tableau Server requires you to configure an identity store to source or provision your Tableau Server users.

When setting up an identity pool, you can use a new or existing local identity store(Link opens in a new window), or you can use an external identity store(Link opens in a new window), either Active Directory (AD) or Lightweight Directory Access Protocol (LDAP) if that external identity store was configured during Tableau Server setup.

Note: New AD or LDAP instances that are not the AD or LDAP instance you configured in TSM during Tableau Server setup (also referred to as the initial pool (TSM configured)), are not configurable with identity pools.

To set up a new local identity store, use the procedure below. Skip to Step 3: Set up authentication if you want to use an existing local identity store or the identity store you configured during Tableau Server setup.

1. Make a Sign In(Link opens in a new window) request to the Tableau REST API to generate a credentials token.

   Example

   URI

   POST https://myco/api/3.19/auth/signin

2. After the credentials token is generated, add the credentials token to the header of all subsequent API requests.

3. Configure the identity store by calling the Configure Identity Store(Link opens in a new window) endpoint using the Tableau REST API OpenAPI.

4. In the request, specify the following:

   1. Type. The type value is always 0 for a local identity store type. If you want to use an existing local identity store or the identity store you configured in TSM during Tableau Server setup, you don't need to set up a new local identity store instance. Instead, skip to Step 3: Set up authentication, below.
   2. Name. The name must be unique.
   3. Display name. This is optional.

   Example

   URI

   https://myco/api/services/authn-service/identity-stores/

   Request body (JSON)

   {
   "type": "0",
   "name": "Local identity store #1",
   "display_name": "Local identity store #1"
   }

   Response body

   None

Step 3: Set up authentication

You can configure OpenID Connect (OIDC) authentication method to authenticate your users.

Note: OIDC is currently the only authentication method configurable with identity pools, regardless of the identity store type you use with the identity pool.

1. After setting up an identity store, call the Create Authentication Configuration(Link opens in a new window) endpoint using the Tableau REST API OpenAPI.

2. In the request, specify the following:

   1. Authentication type. The authentication type values is "OIDC".

   2. iFrame. The iFrame's default value is "false".

   3. The required OIDC client ID, client secret, configuration URL, ID claim, client authentication, and username claim.

      • The client ID, client secret is provided by your OIDC IdP.
      • The configuration URL is also provided by your IdP. The URL and can typically use the following format: https://<idp_url>/.well-known/openid-configuration.
      • The ID claim's default value is "sub". For more information, see Changing the sub claim.
      • The client authentication's default value is "CLIENT_SECRET_BASIC".
      • The username claim's default value is "email". For more information, see Default: using email claim to map users.

      About username claim

      Tableau uses the username claim for identity matching purposes. If you provide identifiers when adding users to Tableau Server, the identifier is used to match the value provided in the username claim. If no identifiers are provided, Tableau defaults to the username set in Tableau Server.

      Notes:

      • If you intend to use this authentication configuration with an identity pool that uses AD as its identity store, make sure that the assigned user has the AD sAMAccountName value in the username claim.
      • If you intend to use this authentication configuration with an identity pool that uses LDAP as its identity store, make sure that the assigned user has the LDAP username value in the username claim.

{
"auth_type": "OIDC",
"iframed_idp_enabled": true,
"oidc": {
	"client_id": "0oa1hotzhjv4tyCd08",
	"client_secret": "EsKd2NCxY-BiLu_zcIwr2lJZLziT_7sw9Fi6HV3",
	"config_url": "https://dev-532601-admin.oktapreview.com/.well-known/openid-configuration",
	"custom_scope": "",
	"id_claim": "sub",
	"username_claim": "email",
	"client_authentication": "CLIENT_SECRET_BASIC",
	"essential_acr_values": "",
	"voluntary_acr_values": "",
	"prompt": "login,consent",
	"connection_timeout": 100,
	"read_timeout": 100,
	"ignore_domain": false,
	"ignore_jwk": false
	}
}

Step 4: Create an identity pool

Depending on the identity store that you configured during Tableau Server setup, the identity pool you create can have only one of the following identity store and authentication method combinations:

• AD identity store + OIDC authentication
• LDAP identity store + OIDC authentication
• Local identity store + OIDC authentication

The first two combinations require that the initial pool (TSM configured) is configured to use AD or LDAP.

The procedure described below creates an identity pool with last combination, "local identity store + OIDC authentication".

1. After configuring OIDC authentication, call the Create Identity Pool(Link opens in a new window) endpoint using the Tableau REST API OpenAPI.

2. In the request, specify the following:

   1. Name and description for the identity pool. Both the identity pool name and description are visible to all users on the Tableau Server landing page.
      

   2. Identity store instance ID and authentication type instance ID.

      Notes:

      • To get the identity store instance ID and authentication type instance ID, you can call the List Identity Stores(Link opens in a new window) and List Authentication Configurations(Link opens in a new window) endpoints.

      • If you want to create an identity pool that uses the identity store you configured in TSM during Tableau Sever setup, the identity store instance value is always '1'.

   Example

   URI

   https://myco/api/services/authn-service/identity-pools/

   Request body (JSON)

   {
   "name": "MyCo contractors",
   "identity_store_instance": "2",
   "auth_type_instance": "0",
   "is_enabled": true,
   "description": "Sign-in for MyCo contractors"
   }

   Example response body

   None

3. After creating the identity pool, go to your IdP configurations and set the sign-in redirect URI to http://<host>/authn-service/authenticate/oidc/<identity_pool_id>/login.

   For example, http://myco/authn-service/authenticate/oidc/57tgfe21-74d2-3h78-bdg6-g2g6h4734564/login

   Note: To get the identity pool ID, you can call the List Identity Pools(Link opens in a new window) endpoint.

Notes:

• You can create as many identity pools as your organization needs.
• Other identity store types and authentication methods are supported by the initial pool (TSM) configured. For more information, see Authentication.

Step 5: Add users to identity pool

You can use Tableau Server directly to add users to an identity pool. Users must belong to the initial pool (TSM configured) or be added to an identity pool to sign in to Tableau Server. When adding users to an identity pool, your workflow can change depending on the identity store that was configured with the identity pool.

The procedure below describes how to add users to an identity through the Tableau Server UI. However, you can add users to an identity pool using the Tableau REST API by calling the Add User to Identity Pool(Link opens in a new window) endpoint.

1. Sign in to Tableau Server UI as an administrator.

2. From the left navigation pane, select Users (or All Sites > Users for a multi-site Tableau Server).

3. Click the Add Users button, and select Create new user or Import users from file.

   For Create new user:

   1. Select the identity pool you want to add the new user to, and then click Next.

      1. If you selected an identity pool that’s configured with an AD or LDAP identity store, enter usernames, assign site membership, and site roles. When finished, click the Import Users button.

      2. If you selected an identity pool that’s configured with a local identity store, enter the username. The dialog box expands so that you can add a display name, an identifier (in most cases), email address, and set site and site roles. When finished, click the Create User button.

         For more information about usernames and how to assign site membership and site roles, see Set Users’ Site Roles.

         About usernames and identifiers in Tableau

         A username is the information that represents the system user. An identifier is used to supplement the username information and can be used by external identity stores as alternatives to usernames.

         In Tableau, a username is an immutable value that is used to sign in to Tableau and identifiers are mutable values used in Tableau’s identity structure as a way to match users to their usernames. Identifiers enable Tableau to be more flexible because they can deviate from the username. If there are changes to the username in the external identity store, Tableau Server administrators can update the identifier to ensure users are matched to the correct usernames.

         When you add an existing user to an identity pool, you might expect the ability to set an identifier. For example, if an existing user belongs to an identity pool configured with a local identity store and you want to add them to an identity pool configured with an AD identity store, we ask you to provide the username to search for identifiers associated with that user. On the other hand, if an existing user belongs to an identity pool configured with an AD identity store and you want to add them to an identity pool configured with a local identity store, we ask you to provide an optional identifier. An exception to this is if you want to add a user to the initial pool (TSM configured) that's configured with a local identity store and local authentication. You will be unable to set an identifier for that user.

   For Import users from file:

   1. Upload a .csv file that contains the following columns in the order listed:

      username, password, display name, license level, admin level, publishing capability, email address, identity pool name, identifier

      Note: Username and password are the only required columns. However, if you don’t specify the identity pool name, the user will be added to the initial pool (TSM configured). For more information, see CSV Import File Guidelines.

      For example, suppose you want to add Henry Wilson and Fred Suzuki to the General Contractors identity pool. Your .csv might contain the following values:

      henryw,henrypassword,Henry Wilson,Viewer,None,yes,hwilson@myco.com,General Contractors,hwilson
freds,fredpassword,Fred Suzuki,Creator,None,no,fsuzuki@myco.com,General Contractors,fsuzuki

Note: When one or more identity pools are created, the Tableau Server landing page updates to include sign-in options for users that are members of those identity pools. For more information, see Provision and Authenticate Users Using Identity Pools.

Test identity pools

After setting up an identity pool, we recommend you test it by signing out of Tableau Server and signing in again as a user that belongs to the identity pool. Make sure you complete the sign in process to ensure that OIDC authentication was configured correctly.

Note: If you've configured an optional description for the initial pool (TSM configured) in Step 1: Configure Tableau Server and establish a session or have a Server Settings (General and Customization) note for Tableau Server, we suggest that the description is specific to users who sign in using the initial pool (TSM configured) and the Sign In Customization note applies to all users who sign in to Tableau Server.

Manage identity pools

You can manage the users in identity pools from both the server-level and site-level Users page. On the Users page, you can see which identity pools users belong to and summary details about the identity pool.

For all other identity pools management tasks, including updating an authentication configuration or identity pool and deleting a local identity store or identity pool, use the Tableau REST API OpenAPI described in the Identity Pools Methods(Link opens in a new window).

Troubleshoot identity pools

tsm configuration set -k features.IdentityPools -v true
tsm configuration set -k features.NewIdentityMode -v true
tsm configuration set -k wgserver.authentication.legacy_identity_mode.enabled -v false
tsm pending-changes apply