About the Identity Migration

Applies to: Tableau Server

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

Note: If you do not plan to use the identity pools capability, we recommend you do not run the identity migration. Running the identity migration without plans to use identity pools will not 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.

Summary of steps for existing deployments

For 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: Start the identity migration

Step 3: Complete the identity migration

Step 4: Configure Tableau Server to use the Identity Service

Key terms

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

Purpose of the identity migration

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.

What happens during the identity migration

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.

Step 1: Before you begin

Before you begin, identify your Tableau Server upgrade method below to determine next steps in the identity migration.

If you’re performing a Blue/Green upgrade or manually upgrading Tableau Server by 1) installing Tableau Server on a new machine and then 2) backing up and restoring Tableau Server using the tsm maintenance (backup and restore) commands, you’re required to take some additional steps to initiate the migration.

For next steps, see Troubleshoot Issues with the Identity Migration.
If you’re doing an “in-place” single-server or multi-node upgrade of Tableau Server using the method described here, there are no additional steps required from you to initiate the migration. The migration initiates after Tableau Server upgrade to version 2022.1 (or later) is complete.

Skip to Step 2.
If you’re manually upgrading Tableau Server by 1) installing Tableau Server on a new machine and then 2) exporting and importing configuration and topology information using tsm settings (export and import) commands, there are also no additional steps required from you to initiate the migration. The migration initiates after the import process completes on the new Tableau Server machine.

Skip to Step 2.

Step 2: Start the identity migration

To start the identity migration, you must enable the identity migration capability by using the tsm command features.IdentityMigrationBackgroundJob.

Note: If you’ve upgraded to Tableau Server versions 2021.4.21, 2022.1.17, 2022.3.9, and 2023.1.5, the identity migration starts by default and you can skip to Step 3: Complete the identity migration.

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

tsm configuration set -k features.IdentityMigrationBackgroundJob -v true

After the identity migration begins, you’ll see a notification in Tableau Server that links you to the Identity Migration page. The Identity Migration page is where you can monitor the status of the identity migration and identity conflicts that need to be resolved.

Step 3: Complete the identity migration

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

Sign in to Tableau Server as an administrator.
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.
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.
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.
After the migration completes, from the Identity Migration page, validate that the Migration Overview shows 100% complete.

Step 4: Configure Tableau Server to use the Identity Service

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.

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

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

Note: After running the commands above, the dedicated Identity Migration page is removed and no longer accessible. The page is accessible only when 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.

Tableau Server on Linux Help