Tableau Server on Linux Help

Beginning in version 2022.1, Tableau Server stores and manages identity information using the Identity Service. With the Identity Service, Tableau Server uses a more modern, more secure, and immutable identity structure for the user provisioning and authentication process. Identity migration is a prerequisite for configuring and using identity pools(Link opens in a new window).

Important: If you don't plan to use the identity pools capability, we recommend that you don't run the identity migration. Running the identity migration without plans to use identity pools won't provide benefits to your Tableau Server deployment.

For existing deployments, if upgrading Tableau Server to version 2022.1 (or later) and restoring a backup of Tableau 2021.4 (or earlier), you can start the identity migration after Tableau Server upgrade completes to populate the new Identity Service. The identity migration populates supplemental Identity Service tables for all Tableau Server users, which are then used to authenticate users through the Identity Service. The migration runs in the background and won’t interrupt or interfere with your users' use of Tableau Server.

As an administrator, you can monitor and manage the migration, including changing when the migration runs or resolving any potential migration conflicts, through a dedicated Identity Migration page available from Tableau Server’s Users page. This page is available for the duration of the migration process.

For new and existing deployments, you must configure Tableau Server to use the Identity Service after the migration completes to take advantage of the identity structure improvements and configure identity pools.

Step 1: Before you begin

Step 2: Enable new schema and sign-in capability

Step 3: Start the identity migration

Step 4: Complete the identity migration

Step 5: Configure Tableau Server to use the Identity Service

Step 6: Enable identity pools

• Identity Service - a service in Tableau Server 2022.1 (and later) that is responsible for the administration of user identities, including authentication and provisioning. The service uses an identity schema where user identities are represented by Identity Service tables and the legacy "system_users" table.
• Identity pools - an identity management tool that uses provisioning and authentication information to enable user access to Tableau Server. Identity pools enable a more centralized and flexible identity management workflow built on the Identity Service for the storage and management of user identities in Tableau Server.
• Legacy identity store mode - a limited identity schema used by Tableau Server 2021.4 (and earlier), where user identities are only represented by the legacy "system_users" table.
• Identity migration - the auditing process that evaluates existing Tableau Server user identities, queries the upstream external identity stores for additional identity information (as appropriate), and imports that additional identity information to the Identity Service.
• External identity store - an identity store type external and upstream to Tableau Server where all identity information is stored and managed by an external directory service (Active Directory (AD) or LDAP). If configured, Tableau Server synchronizes to the external directory so that a copy of the identity information exists in Tableau Server.
• Local identity store - an identity store type provided by Tableau Server. If configured, Tableau Server stores and manages identity information in the Tableau Server repository without any configured external directory for this information.
• System user - a Tableau Server user. A user corresponds to a sign-in record ("system_users") in both the Identity Service (through the "system_users_identities" table) and legacy identity store mode. A "system_users" record can potentially have multiple user identities associated with it and enabled to sign in to multiple sites. The link between a "system_users" record and sites is defined in the "users" table.

When you create a Tableau Server backup, identity information is saved in the identity schema used by the version of Tableau Server the backup was created for. The migration is necessary to populate identity information from the identity schema used in the backup to the identity schema used by the Identity Service.

Identity schema of Tableau Server 2021.4 and earlier

The identity schema used by the legacy identity store mode consists of two tables, "system_users" and "domains."

Identity schema of Tableau Server 2022.1 and later

The identity schema used by the Identity Service includes the legacy "system_users" tables and supplemental Identity Service tables (*_identity_stores and *identities) that capture more identity information. The additional tables help reduce issues that can be caused by upstream changes in the external identity stores.

When information about user identities are migrated, identity information stored in the legacy "system_users" table are supplemented with the Identity Service tables.

The type of Identity Service tables that the identity information is supplemented with depends on which identity store type Tableau Server is configured for: local, Active Directory (AD), or Lightweight Directory Access Protocol (LDAP).

• For AD identity store types, Identity Service tables only inherit unambiguous attributes or attributes that are not stored in the same database record.

  For example, sAMAccountNAme and userPrincipalName (UPN) can be stored in the same name record of a legacy "systems_users" table, which can occur as a result of a complex series of rules. In most cases, the migration is able to correctly interpret and successfully migrate the user identity. However, if the migration produces ambiguous results, you must either manually acknowledge the ambiguity or manually resolve the conflict using the dedicated Identity Migration page. For more information, see Resolve Identity Migration Conflicts.

• For LDAP identity store types, like AD identity store types, Identity Service tables only inherit unambiguous attributes. In most cases, the migration is able to correctly interpret and successfully migrate the user identity. However, if the migration produces ambiguous results, you must either manually acknowledge the ambiguity or manually resolve the conflict using the dedicated Identity Migration page. For more information, see Resolve Identity Migration Conflicts.

• For Local identity store types, Identity Service tables inherit the user and domain fields directly. This means, no additional information or manual resolution is required from you. When Tableau Server is configured for this type of identity store, migration of users identities happens after the Tableau Server backup restore process.

Before you begin, identify your Tableau Server version and upgrade method (if applicable) below to determine next steps in the identity migration.

Before starting the identity migration, the new identity schema must be enabled by the tsm command features.NewIdentityMode; and to continue allowing sign-in to Tableau Server while the identity migration process takes place by the wgserver.authentication.legacy_identity_mode.enabled or tsm authentication legacy-identity-mode <commands> tsm commands.

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

2. Run the following command:

   tsm configuration set -k features.NewIdentityMode -v true

3. Run the following commands depending on the version of Tableau Server you're running:

   • For Tableau Server versions 2022.1.8 (and later), 2022.3.10 (and later), 2023.1.6 (and later), and later:

     tsm configuration set -k wgserver.authentication.legacy_identity_mode.enabled -v true
     tsm pending-changes apply

   • For Tableau Server versions 2022.1.0-2022.1.7, 2022.3-2022.3.9, or 2023.1-2023.1.5:

     tsm authentication legacy-identity-mode enable
     tsm pending-changes apply

   Note: Running these commands causes Tableau Server to restart.

Note: Skip this step for new installations.

To complete the identity migration, all identity conflicts must be resolved or acknowledged before you can enable the Identity Service for Tableau Server.

1. Sign in to Tableau Server as an administrator.

2. From the left navigation pane, select Users (or All Sites > Users for a multi-site Tableau Server) and then click the Identity Migration page to verify the migration has started.

   You can monitor and manage its progress using the dedicated Identity Migration page available from Tableau Server’s Users page. For more information, see Manage the Identity Migration.

3. Resolve or acknowledge all identity conflicts as described in Resolve Identity Migration Conflicts so that All failures tab displays "0" like in the image below.

   

4. Do one of the following:

   • To run the identity migration job now, next to the Migration Overview heading, click the Edit Schedule drop-down arrow, and then select Run Now.

     

   • Alternatively, you can wait for the migration job to run during the next scheduled time.

5. After the migration completes, from the Identity Migration page, validate that the Migration Overview shows 100% complete.

   

After the identity migration is complete, configure Tableau Server to use the Identity Service to ensure a more secure and immutable identity structure for the user provisioning and authentication process.

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

2. Run the following commands depending on the version of Tableau Server version you are running:

   • For Tableau Server versions 2022.1.8 (and later), 2022.3.10 (and later), 2023.1.6 (and later), and later:

     tsm configuration set -k wgserver.authentication.legacy_identity_mode.enabled -v false

   • For Tableau Server versions 2022.1-2022.1.7, 2022.3-2022.3.9, or 2023.1-2023.1.5:

     tsm authentication legacy-identity-mode disable

   Note: After running one of the commands above, the dedicated Identity Migration page is removed and no longer accessible. The page is accessible only when tsm configuration set -k wgserver.authentication.legacy_identity_mode.enabled is true or tsm authentication legacy-identity-mode is enabled.

After Tableau Server is configured to use the Identity Service, when users sign in to Tableau Server, Tableau Server searches for their user identities using their identifiers in the configured identity store. From the identifiers, the universal unique identifiers (UUID) are returned and used to match existing Tableau Server user identities. This process then generates sessions for the users and completes the authentication workflow.

When you’ve completed the identity migration and enabled the Identity Service, enable the identity pools capability in preparation for configuring identity pools(Link opens in a new window).

1. Run the following commands:

   tsm configuration set -k features.IdentityPools -v true
   tsm pending-changes apply

Note: Running these commands causes Tableau Server to restart.

• Manage the Identity Migration
• Resolve Identity Migration Conflicts
• Troubleshoot Issues with the Identity Migration