Migrate Workbooks and Data Sources with Embedded Credentials

Starting in version 2023.1, authorized users can migrate workbooks and published data sources with embedded credentials from Tableau Server to Tableau Cloud or to another Tableau Server. Additional configuration is required before migrating with Content Migration Tool.

Note:Content Migration Tool does not support embedded credential migration for OAuth connections. For more information, see Migration Limitations.

Overview

Migrating embedded credentials using Content Migration Tool (CMT) is available when connecting to Tableau Server as the source site and Tableau Cloud or Tableau Server as the destination site. Both sites must have an Advanced Management license.

Note: Although you can migrate workbooks and published data sources from one Tableau Server to another, this topic focuses on migrating these resources from Tableau Server to Tableau Cloud.

Now that we’ve covered the requirements, let’s discuss how migration works. You’ll need to work closely with the Tableau Cloud site administrator and TSM administrator (sometimes the same person) to allow the feature and authorize a site user. After the feature is activated, the authorized site user builds a migration plan and selects the publish options Migrate Embedded Credentials for Workbooks and Migrate Embedded Credentials for Data Sources.

When running the migration plan, all required content credentials are transmitted in an encrypted content manifest from Tableau Server to Tableau Cloud. As CMT publishes content, the destination Tableau Cloud site embeds matched credentials securely from the manifest into the content (workbooks or published data sources). Any problems that occur during migration will appear in the Errors and Warnings tab in CMT. For more information, see Migration Plan Overview.

Allow embedded credential migration

Use the following steps to allow embedded credential migration from Tableau Server to Tableau Cloud.

Tableau Cloud

  1. Open a browser window and sign in to Tableau Cloud as a site administrator.

  2. Select Settings > General, and scroll down to Manage Content Migration.

  3. Click Create new key to generate an encryption key pair.

    Note: The public key is only displayed once. If you lose the key before completing the configuration, you’ll need to generate a new key.

  4. In the resulting window, click Copy to clipboard and then close the window.

  5. Paste the public key to a file and store it in a safe location. The TSM administrator will use the public key to allow migration. You can view the public key expiration date on the Settings page.

TSM Command Line Interface

  1. Depending on your operating system, do one of the following:

    • Tableau Server on Windows: Open Windows Command Prompt with an account that is a member of the Administrators group on a node in the cluster.

    • Tableau Server on Linux: Open a command prompt with an account that is a member of the tsmadmin group on a node in the cluster.

  2. Use tsm security authorize-credential-migration to allow embedded credential migration to the Tableau Cloud site. For more information, see tsm security(Link opens in a new window) in Tableau Server help.

    tsm security authorize-credential-migration --source-site-url-namespace <Tableau Server site ID> --destination-site-url-namespace <Tableau Cloud site ID> --destination-server-url <Tableau Cloud site url> --authorized-migration-runner <username> --destination-public-encryption-key <public key>

    Note: When running TSM commands from a remote node, use tsm login to authenticate a session with the Tableau Server Administration Controller service before running tsm security authorize-credential-migration.

  3. (Optional) Use tsm security cancel-credential-migrations to cancel granted authorizations. By default, migration authorization will expire in 7 days or the number of days specified with the --expiration-time-in-days option.

Content Migration Tool

  1. Open Content Migration Tool and select Create New Plan or Browse for a Plan.

  2. On the Sites page, click Sign in to Tableau, and connect to Tableau Server as the source and Tableau Cloud as the destination. Embedded credential migration is only available when migrating from Tableau Server to Tableau Cloud.

  3. Build your migration plan and select the following Publish Options:

  4. When you are ready, click Verify & Run to start the migration.

The workbooks and published data sources you selected are migrated to your Tableau Cloud site and should not prompt for authentication. If you experience issues while migrating embedded credentials, see Troubleshooting.

Troubleshooting

This section includes some common migration issues you might encounter and suggestions to resolve them.

There is no option to migrate embedded credentials

You can only migrate embedded credentials from a Tableau Server to a Tableau Cloud site. Tableau Server and Content Migration Tool must be running versions 2023.1 or later. For more information, see Install Tableau Content Migration Tool.

Migrating embedded credentials failed

In the Errors and Warnings tab of CMT, you may receive an error indicating that migrating the embedded credentials failed. This can occur when the public key used to authorize migration has expired.

As a Tableau Cloud site administrator, go to the Settings page and verify that the public key is valid. You’ll have to create a new encryption pair to authorize the migration if the public key expires. For more information, see Allow embedded credential migration.

Who can do this?

  • Tableau Cloud site administrator and TSM administrator are required to allow embedded credential migration.

  • The authorized site user must have an Explorer role or higher. They must also have View and Download/Save a Copy capabilities for workbooks on the source site and View and Publish capabilities for target projects on the destination site.

For more information, see Permissions.

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