Manage the Identity Migration

Applies to: Tableau Server

As an administrator, you can monitor and manage the identity migration, including changing when the migration jobs run, through the dedicated Identity Migration page available from Tableau Server’s Users page. This page is available for the duration of the migration process.

The migration jobs are designed to run in the background without interrupting or interfering with the use of Tableau Server. If needed, however, you can make adjustments that affect how frequently migration jobs run, when the migration jobs run, and how long the migration jobs can run.

Generally, the migration can take anywhere from 3 minutes to 10 days, depending on the size of your Tableau Server deployment and any changes to the default settings you make during the migration. For example, if you have 10,000 users, the migration can take about 30 minutes.

Note: While the migration jobs are running, all authentication and user-related capabilities work normally.

Manage identity migration jobs

You can manage the following aspects of the identity migration.

Resolve identity conflicts

To review the identity conflicts you might encounter during the migration, see Resolve Identity Migration Conflicts.

Change daily migration job schedule

  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.

  1. Next to the Migration Overview heading, click the Edit Schedule button.

  2. In the Edit Schedule dialog box, change when and how frequently jobs can run.

    Note: You can ignore the Priority and Execution options in this dialog box.

  3. When finished, click Update.
Initiate a migration job

  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.

  1. From any tab, select a user or multiple users.

  2. From the Actions menu, select Retry Migration or Acknowledge, depending on what you need to do.

  3. Next to the Migration Overview heading, click the Edit Schedule drop-down arrow.

  4. Select Run Now.

Pause the identity migration

  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.

  1. Next to the Migration Overview heading, click the Edit Schedule drop-down arrow.

  2. Select Disable.

Restart the identity migration

  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.

  1. Next to the Migration Overview heading, click the Edit Schedule drop-down arrow.

  2. Select Enable.

Change identity migration settings

To reduce any potential strain the identity migration might have on your Tableau Server, the migration is configured to run with the default settings listed below.

Migration settings

Type tsm command Default Procedure
Jobs schedule N/A 3:00 AM, daily until complete Configurable from the Identity Migration page, see Change daily migration job schedule above.
User identity requests per second (rate) tsm authentication identity-migration configure -–rate Up to 5

If needed, you can use the tsm authentication identity-migration command to change the migration settings listed above using the steps below.

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

  2. Run one or both of the commands described in tsm authentication identity-migration.

    For example, to change the individual job runtime and rate from their default values, you can run the following command:

    tsm authentication identity-migration configure --job-run-time 180 --rate 3

Individual job runtime tsm authentication identity-migration configure -–job-run-time 120 minutes
Enable identity migration tsm configuration set -k features.IdentityMigrationBackgroundJob false

By enabling the identity migration, Tableau Server can use the Identity Service to store and manage user identity information.

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

  2. Run the command the following command:

    tsm configuration set -k features.IdentityMigrationBackgroundJob -v true

Note: The identity migration and the Identity Service is a prerequisite for certain capabilities like identity pools(Link opens in a new window). For more information about the tsm command, see features.IdentityMigrationBackgroundJob.

Disable identity migration

If you’ve upgraded to Tableau Server versions 2021.4.21, 2022.1.17, 2022.3.9, and 2023.1.5, you might need to disable the identity migration. By disabling the identity migration, Tableau Server cannot use the Identity Service to store and manage user identity information.

  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.IdentityMigrationBackgroundJob -v false

Note: The identity migration and the Identity Service is a prerequisite for certain capabilities like identity pools(Link opens in a new window).

Complete the identity migration and configure the Identity Service

After all user conflicts are resolved or addressed and migration jobs run, you must configure Tableau Server to use the Identity Service to complete the identity migration process.

Step 1: Validate and complete the identity migration

  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.

Step 2: Configure Tableau Server to use the Identity Service

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

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

Back to top
Thanks for your feedback!Your feedback has been successfully submitted. Thank you!