How to Migrate Tableau Server from Local Authentication to Active Directory by Using Site Migration

Version 2


    Tableau Server administrators



    A step-by-step how-to guide, complete with best practices, to guide Tableau administrators in switching their Tableau Server installation from using Local Authentication to Active Directory (AD). This procedure could be required when scaling Tableau Server from a proof-of-concept or departmental deployment up to an enterprise-class deployment with Single Sign On (SSO) and robust integrated security.


    Table of Contents


    Many Tableau Server installations begin life as a data visualization and collaboration solution for a team or department. Due to their more agile security requirements, often times smaller scale customers initially opt to install Tableau Server with the Local authentication option selected, because it’s a streamlined way for a team to self-manage security for granting access to published Tableau workbooks.


    As an organization’s Tableau Server footprint evolves into a large, standardized corporate analytics platform, Active Directory (AD) typically becomes the most attractive authentication choice. AD authentication offers several benefits over Local authentication:


    1. Standardization. AD leverages existing corporate security standards, and it provides more flexible options for achieving Single Sign On (SSO) flexibility.
    2. Delegation. AD enables partial delegation of security responsibilities to IT security.


    For these and other reasons, Active Directory is frequently the de facto authentication choice for the majority of larger-scale Tableau Server deployments. It’s a natural progression for Tableau Server deployments to make the jump from Local Authentication to AD as they mature.


    Switching the authentication type for an existing Tableau Server deployment requires a reinstallation of Tableau Server. Reinstallation is a straight forward task, but it raises several questions:


    1. Corporate content. How do I migrate my existing corporate content to the reinstalled environment?
    2. Personal content. How do I preserve my users’ personal workbooks and data sources when we transition to the new Active Directory accounts?
    3. Hardware. Will I have new dedicated hardware (or cloud/virtual machines) for the reinstalled environment? And if so, will I require new SSL certificates (if applicable)?
    4. Software upgrades. Is this also a good time to upgrade the operating system and/or Tableau Server to a higher patch level?


    This TabWiki article explains step-by-step how to accomplish changing the authentication type for an existing Tableau Server deployment while using site migration to preserve existing user content. While most of this information can be gleaned in pieces from other online help articles, we have consolidated the steps here and included additional information to help accelerate your tasks and clarify ambiguous areas.


    Preparation Checklist

    The following checklist is intended to guide you in under

    1. Determine your approach. Read the Changing Authentication article to understand the high-level options. The TabWiki article you’re reading now addresses method 1 (using site export and import). The site import/export method is the most elegant way to preserve existing Local users’ personal workbooks and data sources when migrating to Active Directory.
    2. Obtain new hardware and install Tableau Server with the Active Directory authentication method selected. The migration process is vastly simplified if you can leave your existing Tableau Server environment intact and migrate the content over to a new environment. This method requires that you obtain new hardware or virtual/cloud machines for the environment that will use Active Directory authentication. This is the perfect opportunity to rebuild Tableau Server on the latest supported version of your operating system, as well as an excellent chance to increase the amount of RAM, disk space, or other server specs (however, if you have core licenses, be mindful not to exceed your license count).
    3. Obtain new or updated SSL certificates. If your existing Local authentication Tableau Server has SSL enabled and you use a load balancer or a friendly DNS name for the Server URL instead of a Gateway machine name, then you can probably reuse the existing SSL certificates provided you keep using the same load balancer or DNS name.
    4. Install required data source drivers on target system. Your new AD-enabled Tableau Server will need to have all required data source drivers installed, otherwise the migrated content will not be able to refresh or make live connections. The latest certified data source drivers can be obtained from Tableau’s Driver Download page.


    High-Level Overview

    1. Set up new Tableau Server environment with Active Directory authentication enabled and all required data source drivers installed (this blog article assumes you have already done that).
    2. Export site(s)
    3. Map users and schedules
    4. Import site(s)
    5. Validate the migrated content



    • Use consistent Tableau Server versions between source and target environments. Your source (Local authentication) and target (AD authentication) environments must run the same minor version (e.g., 10.x or 2018.x) and the same or higher maintenance version (e.g., 10.4.x or 2018.1.x). For example, if your source Tableau Server runs 10.4.3, site migration will only succeed if your target Server is running 10.4.3, 10.4.4, 10.4.5, etc. On the other hand (in this example), site migration would fail if your target is running a lower incremental release, such as Tableau Server 10.5 or 2018.1. Refer to Version Compatibility Between Tableau Desktop and Tableau Server for more information.


    Site Migration Process


    Prepare Target Server

    1. On your target Tableau Server, create empty site(s) with the same names as those you intend to migrate from your Source environment.
    2. Configure Active Directory authentication and add the required AD users and/or AD groups to each new site you created. For example, if your source site with local authentication contains 964 users, you need to make sure that all 964 users have a matching account in Active Directory that’s been mapped to the new empty target “shell” site you create in step 1. It’s OK if the AD account names are different than the old Local account names, but each incoming user account must have a unique matching AD account associated with the target site. (You cannot map multiple incoming Local users to the same AD account.)


    Prepare Source Server

    1. On your source Tableau Server, cleanup all inactive/invalid user accounts. Delete any Local accounts from each site that cannot be mapped to Active Directory accounts in the target system. If an account that needs to be deleted owns any content, however, you will need to change the owner of that content to be a different valid Local user account. Use the Owner dropdown list in Tableau Server to assist in identifying content owned by users that you know need to be deleted (it is also possible to reassign ownership en-masse using the Actions dropdown menu, making this process fairly quick and painless, even if you have to delete several dozen users).
    2. Do not proceed until you are confident that all Local user IDs in the source site are valid and will have matching Active Directory accounts in the target system’s corresponding site. If you export a site with an inactive Local user account that doesn’t have a unique corresponding AD account to map to in the target, then your site export cannot be imported into the target system. It will fail. Spend some time making sure your users list, content, and schedules are as accurate and cleaned-up as possible so that you don’t run into challenges migrating outdated objects.

    Export Site(s)

    1. On your source system’s Primary server, start a Command prompt by right-clicking and selecting Run As Administrator.
    2. Determine which site(s) you want to export and get a feel for their size, in terms of number of users and content storage space required. Small sites of up to 100 users and a few hundred megabytes of content should take only a few minutes to export. Larger sites of a thousand or more users and/or gigabytes of content can take an hour or longer (for example, a 980 user site with 36GB of content required about five hours on an 8-core physical server in my experience). Performance will vary considerably depending on your hardware, content, and the server’s multitasking workload.
    3. Export each of your sites from the command prompt. Note that sites are locked during export, so coordinate an outage beforehand with your users. Use the command:

      tabadmin exportsite "YourSite" --file "D:\YourPath\"
    4. Repeat this procedure for each site you need to migrate.


    Generate Import Mapping Files

    1. On your target system’s Primary server, start a Command prompt by right-clicking and selecting Run As Administrator.
    2. You’ll now generate the import mapping files. For the purposes of a Local-to-AD migration, import mapping performs a lightweight, uncommitted “dry run” comparison of the content in your export zip file with the target system’s content—specifically in our case, the users and schedules content in the payload. Use the command:

      tabadmin importsite "YourSite" --file "C:\YourPath\"
    3. Note: Small sites of up to 100 users and a few hundred megabytes of content should take only a few minutes to import. Larger sites of a thousand or more users and gigabytes of content can take an hour or longer (for example, a 980 user site with 36GB of content required about 2 1/2  hours to generate the mappings files on an 8-core physical server in my experience). Performance will vary considerably depending on your hardware, content, and the server’s multitasking workload.
    4. Navigate to the folder you are instructed by the final response from the command above (the precise folder location will differ depending on whether you have installed Tableau Server to C: or a non-OS drive).
    5. Inspect each of your mappings files in an advanced text editor with flexible carriage return, word wrap, and character encoding handling, such as Notepad++). In particular, look at mappingsScheduleMapper.csv and mappingsSystemUserNameMapper.csv as these two files are most applicable to converting a site from Local to AD authentication.
    6. Warning: Files stored in the data\tabsvc\temp folder are volatile! If you restart or reboot your target server, or run tabadmin cleanup, you will lose your mappings files because Tableau Server deletes everything in this temp folder. Be sure to back up your mappings files to a safe place to reuse them later if needed. The user mapping file in particular can sometimes take many hours of labor to prepare and validate for large sites, so be sure to periodically safeguard your labor investment in the following steps!
    7. Open mappingsScheduleMapper.csv and inspect its contents. If you see ??? or ???,??? appear in the file, this indicates that a schedule in the source export doesn’t have a matching schedule in the target system. Schedules need to be manually created. If your schedule mapper looks similar to the one below, manually re-create each missing schedule in the target system using exactly the same name and definition as the schedule has in the source system.
      Next, either regenerate the site import mapping file and reinspect it, or manually edit file right now, and replace the ???,??? with the name of the schedule to map to, as well as the schedule type. The contents of this file are case-sensitive. When finished, your schedule mapping file will not contain any ??? entries and should look similar to this:
    8. Open mappingsSystemUserNameMapper.csv and inspect its contents. If you see ??? or ???,??? appear in the file, this indicates that a Local user in the source export doesn’t have a matching AD user and/or domain in the target system. Auto-matching of names by the site import process is performed with case-sensitivity, which means that Local user “GrantE” will not auto-match to AD user “grante” and will need to have its matching AD account and domain name manually entered in this file. If you have hundreds or thousands of names to match, consider using lightweight data prep tools such as Microsoft Excel’s vLookup function or even Tableau Desktop to join the CSV user mapping file up with an AD username record table to help match Local names with their precise unique AD counterpart. Remember that precise case-sensitivity is required, and each incoming Local user must have a unique AD user that hasn’t been used for any other mapping. The domain name that appears in the fourth column of the user mapping file should also exactly match the one from your Tableau Configuration Manager.

    9. The entire import will fail if even a single user (or schedule) mapping is invalid. For systems with hundreds or thousands of user mappings that are difficult to accurately verify manually, it is a best practice to leverage Tableau Desktop to machine-verify the accuracy of your mapping file. (For a large site that takes many hours to import, this step can save you hours of wasted time if an import were to fail at the end.) When you think your mappingsSystemUserNameMapper.csv is ready, try connecting to it with Tableau Desktop’s CSV data source method, and join it to your target system’s PostgreSQL repository, specifically the system_users table, which will contain entries for each mapped Active Directory user. Establish a left-outer join between mappingsSystemUserNameMapper.csv and system_users and use this to create a new sheet which then verifies that each incoming Local user’s Target Name column truly has a valid, matching Active Direcotry account Name in system_users:
    10. After you’re satisfied that your site mapping files are 100% accurate with no ??? entries whatsoever, you may proceed with the final migration steps.
    11. Did you remember to backup your mapping files? Otherwise, they will be deleted if you restart Tableau Server.


    Import the Verified Mapped Site Content to the Target Site

    1. On your target system’s Primary server, start a Command prompt by right-clicking and selecting Run As Administrator.
    2. Run the command:

      tabadmin importsite_verified "YourSite" --importjobdir "YourPath\Tableau\Tableau Server\data\tabsvc\temp\import_YourSiteImportName"
    3. If the mappings files are correct, everything should finish successfully. However, if you receive any errors, such as:

      org.springframework.orm.jpa.JpaSystemException: org.hibernate.TransactionException: commit failed; nested exception is javax.persistence.PersistenceException: org.hibernate.TransactionException: commit failed

      Then inspect the tabsvc-tabadmin-java.log for more details. Search that file for the same error message above, and within a few dozen lines following its appearance, check to see if you have errors that look like this:

      Caused by: org.postgresql.util.PSQLException: ERROR: insert or update on table "tasks" violates foreign key constraint "tasks_schedule_id_fkey"
  Detail: Key (schedule_id)=(-17) is not present in table "schedules".

      The error mentioned above could instead reference different tables, too, such as system_users. If you find errors similar to this, it’s a strong indication that either your users or schedules mappings files contain bad mapping content. Consider using Tableau Desktop to join to the PostgreSQL repository (as described earlier in this procedure) to 100% vet the correctness of your mappings files.


    Validate Your Migrated Content

    1. If your site import succeeded, verify that you can log on to Tableau Server using AD accounts and access all migrated content. Verify that extract refreshes succeed for all required data sources.
    2. Also spot-check performance. Do refreshes complete in the expected amount of time? Do workbooks load as promptly as before?
    3. Invite users to spot-check content as well. After you’re satisfied everything is working, you can disable your old Local authentication environment and make the new AD authentication environment your active (production) system.