Migrating TFS to a new data center

Premier Developer


This post is provided by App Dev Manager, Steve Keeler who outlines an approach for performing TFS migrations to a new data center in a different domain and where there is limited or no connectivity between the current and target environments.

Applies to: TFS 2013 | TFS 2015 | TFS 2017 – This article outlines an approach for performing TFS migrations to a new data center (in a different domain) where there is limited or no connectivity between the current and target environments. In this context, migrating the TFS deployment includes restoring backups of the TFS (config & collections), SharePoint (content), and SSRS (reports) databases in the new domain environment. If you are faced with this scenario, read on. Even if this does not match your scenario, some parts of the information covered here may still be useful when dealing with large numbers of changes to existing TFS, SharePoint, and SSRS user identities and permissions.


There are two documented types of moves you can perform on Team Foundation Server: hardware and environment. In a hardware move, you are moving (or cloning) an existing TFS implementation to a new set of servers in the same domain. In an environment move, you are changing the domain of the TFS deployment. Documentation for both types of moves is available here:

Both of these articles have the following important note:

“In some situations you might want to change the domain of a TFS deployment as well as its hardware. Changing the domain is an environment-based move, and you should never combine the two move types. First complete the hardware move, and then change the environment.”

But what if your migration is to a new data center or servers located in a different domain, with restricted or no connectivity to the original domain? This scenario can occur when changing data centers, for example during mergers of separate organizations or transfer of responsibility for services. With limited or no connectivity between environments, it is not possible to join the existing TFS deployment to the new domain. In this case, the hardware move is the closer match for what we need to achieve. Following the instructions in the hardware move documentation gets us through most of the migration process. After the hardware move has been completed we will still need to remap user identities/permissions for TFS, SharePoint, and SSRS. A common element to each of these three areas is the mapping of your user identities from the old domain into the new domain. We’ll look at this requirement in the User Mapping File section below. One thing you should pay special attention to during the process is ensuring that any TFS user identities in the new domain that you will be mapping TFS users from the old domain into are not part of the Local Administrators group. This is important because the TFS identity synchronization service will automatically create TFS user identities for members of this group. Once a TFS user identity has been created in the new domain, it is not possible to map a TFS user identity from the old domain into it.

User Mapping File

To support the user identity and permission changes needed in the three identified areas, we will create a common user mapping text file. In this schema, OldDomain represents the name of the original domain, OldAccount represents the user account names in the original domain, NewDomain represents the name of the target domain, and NewAccount represents the user account names in the target domain. The following illustrates a user mapping file for a sample scenario where TFSDEV is the original domain and TFSPRD is the target domain:


The first line of this file contains the attribute names, which must match exactly for the PowerShell scripts provided later to operate correctly. In this sample file, we are mapping the Developer1 account in the TFSDEV domain to the same account name in the TFSPRD domain. The Developer3 user account in the TFSDEV domain is mapped to Developer2 in the TFSPRD domain. We’ve chosen the CSV format for the user mapping file in this example as it is relatively easy to manage with a wide range of application tools and utilities. However, you could also use other formats, with the appropriate changes to the sample scripts. For example, JSON and XML are two possible alternatives. Once the user mapping file has been created, we can proceed with the changes detailed in the following three sections:

  1. Remap TFS user identities
  2. Remap SharePoint user identities
  3. Update SSRS user permissions

TFS Identities

Remapping TFS identities is accomplished using the TfsConfig Identities /change command. The TfsConfig.exe utility is installed with Team Foundation Server, under the \Tools folder of the installation path. If all (or most) of your account names match between the two domain environments, then you can run the command directly, omitting the /account and /toaccount parameters. Often times however, you will need to map many user accounts that have different names in each domain.


The following PowerShell script illustrates how you can handle the more complex account mapping scenario, using the user mapping file created in the previous section. The $TfsConfig parameter in this sample script points to the location of the TfsConfig.exe application in a default installation of TFS 2015. If its location is different in your environment, you will need to either change the default value in the script, or provide the location as a parameter value when invoking the script.

Running this script with the user mapping file created in the previous section displays the following output:

The script executes the TfsConfig Identities /change command for each entry in the user mapping file, and will display the Changed value on success. Changed TFS identities will not match the Windows user identities until the next identity synchronization has occurred – by default, this happens at the top of every hour. It is possible to force an identity synchronization to happen immediately by invoking a web service call.

SharePoint Identities

After moving your SharePoint content database for TFS to a new domain, the SharePoint user permissions still reference user identities in the original domain environment.


It is relatively easy to remap the SharePoint user identities by using the Move-SPUser PowerShell cmdlet. The following PowerShell script illustrates how you can use the previously created User Mapping File to remap the SharePoint user identities into the new domain environment.

Run the above script, supplying the URL of the SharePoint web application associated with the TFS SharePoint site collections, and location of the user mapping file. Typically you will run this on the SharePoint server in the new environment, which should already have the Microsoft.SharePoint.Powershell module present. Running this script produces the following sample output:

After remapping your SharePoint user identities, login with a user in the new domain and navigate to a SharePoint site associated with one or more of your TFS team projects to validate that the SharePoint user was remapped successfully.

SSRS Permissions

The last area we’ll address is SQL Server Reporting Services (SSRS) permissions for your TFS team project reports. Managing SSRS user permissions (roles) can be done through the Report Manager web interface as documented in Grant user access to a report server, or via the command-line with the RS.exe utility. This section describes a PowerShell-based solution to simplify the replication of hundreds (or thousands) of distinct SSRS user permissions between different domain environments. We will once again leverage the User Mapping File already created, combined with two PowerShell scripts to: 1) retrieve existing user permissions in the original domain environment, and 2) reapply those permissions in the new domain environment.


The first step is to generate a textual representation of user permissions in the original domain environment. It takes two parameters: the SSRS report server starting path, and an SSRS instance name if this is not a default SSRS instance. The script should be run on the SSRS server in the original domain environment. It can be run from elsewhere by changing the $reportServerUri variable to point to the SSRS Web Service URL (available in Reporting Services Configuration Manager).

This script creates an output file named ssrs-list-permissions.csv in the same directory where the script resides. Remember the location and name of this output file as it will be needed in the next part of the process. Sample console output from running the ssrs-list-permissions.ps1 script looks like this:

The permissions output file has the following format:

If a user is assigned to multiple roles, each role will be specified on a separate line in the permissions output file generated by the ssrs-list-permissions.ps1 script.


The second step is to use the User Mapping File along with the permissions output file generated in the previous step. Together, these two files are used as input to the script below that is run on the SSRS server in the new domain environment. This script uses the SSRS web service to update permission policies. For each object/role permission identified in the the permissions output file generated in the original domain, it performs a lookup in the user mapping file to determine user identity in the new domain, and grants that identity the object/role permission.

Sample console output from running the ssrs-change-permissions.ps1 script looks like this:


We’ve demonstrated how you can leverage PowerShell scripting to simplify the process of managing user identities in a specific migration scenario for an enterprise-scale TFS deployment.

Premier Developer
Premier Developer

Premier Support for Developers

Follow Premier   


    Leave a comment