Infrastructure or business changes may require you to change the authentication type on Tableau Server. In this context, authentication refers to the core authentication type that you've configured on Tableau Server: local authentication or Active Directory. See Authentication to learn more.
You can change from local authentication to Active Directory or you can change from Active Directory to local authentication. In either case, to change the authentication type, you complete these steps:
- Uninstall (including manual deletion of directories) and then reinstall of Tableau Server. The procedure for full uninstall and clean install are at the end of this topic.
- Restore content and permissions.
Changing the authentication type on Tableau Server can be a complicated and time-consuming process. To avoid data loss or orphaning of content or users, you'll need to plan this process carefully. In all cases, user filters applied to workbooks and data sources will need to be updated manually after the change.
Most importantly, determine how you will transition content and permissions to the new authentication model after you reinstall Tableau Server.
Methods for restoring content and permissions
The following list describes three methods for restoring content and permissions after you reinstall Tableau Server. Select the method that best fits with your environmental requirements.
Method 1: Use site export and import—In this method, you start by exporting each site in your existing deployment. Then, you install the new server and configure it for the new authentication type. You then create new users in the default site on the new server. Finally, you import all the original sites. During the import stage, you can map the original identities to the new users that you created in the default site.
Because this method exports all content and permissions at each site, it is the best method for organizations that require a high fidelity replica of the content and permissions after the authentication change is complete. In most cases where organizations need to change the authentication type, a different user name syntax is a often a requirement. This method, which includes a process of mapping original user names to new names, provides flexibility for such scenarios.
Method 2: Fresh installation; users republish content—In this method, you install a new version of Tableau Server and select the new authentication method during setup. You also create new sites. You then create users and give them access, and they republish their workbooks and data sources. Unlike the other methods, in this one, you do not reuse any of your existing Tableau Server infrastructure.
This method is most appropriate for smaller deployments with fairly autonomous and data savvy users. From an administrative perspective, this method is the simplest, since you're not actively porting over content. However, because you rely entirely on users to republish content, this method may not be successful for large organizations or for those where centralized oversight of content is required.
Method 3: Restore and manually assign content—In this method, you begin by documenting the content ownership model. Then you take a backup of the server, uninstall the existing Tableau instance, delete the install directory and then install a new instance with the new authentication type. After installation, you manually create new users that correspond to users on the original system. You then restore the backup to upload content. Lastly, you reassign content to users as appropriate. This method requires careful planning and implementation to avoid orphaned users and content.
This method is best if you are archiving more content than you are reassigning. In this context, "archiving" content means that you're reassigning old content to a single administrative user rather than to individual users.
On the other hand, if all (or most) of your users need to maintain control over the content that they have on the existing system, then you must manually reassign all of the content to match the original ownership model. Embedded credentials in workbooks and data sources will automatically be deleted when ownership changes. See Manage Content Ownership. Therefore, in addition to the cost of reassigning content after the change, you must also document content ownership and assets with embedded credential before the change.
User filters are domain-specific. Therefore, when the domain of Tableau Server changes or authentication type changes, filters no longer function as expected. Although the user filters are generated by Tableau Server, after they are set by the user, the filters are stored in the workbooks and data sources. None of the methods for changing authentication modify the contents of the workbooks or data sources.
As you plan the authentication change, you must also include a final task to correct user filtering in all workbooks and data sources with Tableau Desktop.
User names and the Tableau Identity store
Unless you select Method 2 above, it's helpful to understand how Tableau Server stores user names in the Tableau identity store. Tableau stores all user identities in the repository, which coordinates content permissions and site membership with various services in Tableau Server. Generally, servers configured with Active Directory authentication store user names in the format,
domain\username. Some organizations use a UPN (firstname.lastname@example.org). On the other hand, organizations that configure Tableau Server with local authentication usually create standard, truncated user names, such as jsmith.
In all cases, these user names are literal strings that must be unique in Tableau identity store for the purpose of identity management. If you are changing from one authentication type to another, then your target authentication, SSO, or user provisioning solution may require a specific user name format.
Therefore, to maintain all permissions, content, and user viability, one of the following must be true after you change the authentication type:
- The new user names must match the original user names.
- The original user names must be updated to match a new format.
In most cases, your new authentication plan will impose a user name syntax that is different than your original user names. In that case, we recommend using Method 1 - site import to change authentication type. The site import method includes a process where you can map original user names to new user names.
It's possible that the original user name format will work with the new authentication type. For example, if you used UPN names in a local authentication deployment, you might be able to use the same user names in an Active Directory deployment. You could also use the
domain\username format for local authentication, as long as users continued to use that format to sign in to Tableau Server. For these cases, Method 3 might be the most efficient way to change the authentication type.
If you are changing from local authentication to Active Directory authentication, review the topic, User Management in Active Directory Deployments, as part of your planning process.
Method 1: Use site export and import
- Export all sites on your server. See Export or Import a Site.
- Back up, uninstall, and then reinstall .
- Create new users on Tableau Server. You should have a new user that corresponds to each user on the original server.
- Import the sites that you exported in Step 1. See Export or Import a Site. During import, you will be prompted to map the new users to the original users.
Method 2: Fresh installation—users republish content
Even if you do not plan to port content as part of your authentication change, we recommend that you back up the server.
- Back up, uninstall, and then reinstall .
- Create users, sites, and groups.
- Inform your users of the new Tableau Server, provide them with credentials, and allow them to republish their content.
Method 3: Restore and manually assign content
Before you begin this method, we recommend that you document the existing deployment. Specifically, gather the following information from the existing server:
- User information: user names, display names
- Sites: site names and users in each site
- Groups: group names and permissions
- Content: workbooks, views, data sources
After you have gathered this information, follow these steps:
Follow the procedures detailed below (Back up, uninstall, and then reinstall . However, when you are prompted to create a new administrative account, close the browser without creating the account. You will create a new administrative account later in this procedure.
Open Windows Command Prompt as an administrator and navigate to the Tableau Server bin directory by typing the following command:
cd C:\Program Files\Tableau\Tableau Server\<version>\bin
Type the following command to restore the backup file without inheriting the previous configurations:
tabadmin restore [path\file name] --no-config
After restoring your backup file, a browser window will display and you will be prompted to create a new administrator account again. Ignore this, and close the browser window. If you are prompted to enter the Run As User password, type the password and continue with the next step. You will not see a password confirmation.
In the Command Prompt window, from the Tableau Server bin directory, type the following command to reset Tableau Server back to a state that requires an administrator account to be created:
Open a browser window, and enter
http://localhostin the address bar to create the administrator account for Tableau Server.
If you are using Active Directory authentication, the account for the Tableau Server administrator account must be an existing Active Directory user.
Sign in to Tableau Server. Users from your previous installation have been migrated. These users are not valid and will need to be deleted.
Create new users and assign content to those users as appropriate.
All methods include the following steps:
- Back up Tableau Server
- Uninstall Tableau Server.
- Reinstall Tableau Server with the new authentication type.
Step 1: Back up Tableau Server
Follow the procedure, Creating a regular backup. Run the
backup command with the
–v options. The
–d option adds the datestamp, and the
–v option verifies the state of the database for backup and restore.
When you are finished, copy the backup file (
.tsbak) to a safe location that is not a part of your Tableau Server installation.
Step 2: Uninstall Tableau Server
- From the Start menu, go to Control Panel > Programs and Features. Select Tableau Server, and then click Uninstall.
- When Tableau Server has been uninstalled, open Windows Explorer and navigate to
- Delete the Tableau Server folder.
- While still in Windows Explorer, navigate to
\ProgramData\Tableau(this is a hidden directory), and then delete the Tableau Server folder.
Note: If you have installed Tableau Server on a drive other than the system drive, the folder paths will be different than those shown here. See Installation directory for more information.
Step 3: Reinstall Tableau Server with new authentication type
- Go to the Tableau Customer Portal, sign in with your Tableau user name and password, and then download Tableau Server.
- Install Tableau Server. See Install and Configure for more information. During installation, you will select the new authentication method. See Configure General Server Options. If you are running Method 3, then ignore the prompts (close the browser window) to create a new administrative account on reinstall.