There are days where you need to move objects in a domain or forest to somewhere else, and those days require the Active Directory Migration Tool (ADMT). Hopefully, any moves that you make are pre-planned and approved by change management. In reality, sometimes sysadmins have to make emergency Active Directory (AD) migrations for catastrophic hardware failures or as a part of an Incident Response plan. It’s best to know how to use ADMT before you need to make changes, so read on for all of the details.
What is the Active Directory Migration Tool (ADMT)?
The Active Directory Migration Tool (ADMT) is a Microsoft software application that helps you manage and perform the necessary operations to move AD objects. You can move objects within the same domain forest (intraforest) or to a different forest (interforest).
Get the Free PowerShell and Active Directory Essentials Video Course
Prerequisites for Installing the Active Directory Migration Tool
Here are the most important system requirements that you need to know about for ADMT.
- You need to install ADMT on Windows Server 2008 or later.
- ADMT doesn’t work on Read-Only Domain Controllers.
- The source and target domains also need to be running supported Windows Server versions.
- ADMT requires a SQL server to store data. The SQL instance can live anywhere.
How to Install ADMT
The biggest hurdle installing ADMT will probably be installing or provisioning a SQL server. Other than that, it’s a simple process.
1. Download the installer from Microsoft.
2. Run the installer.
3. Click Next, Agree to the EULA, and then either join the Customer Experience Improvement Plan or not, and click Next.
4. Enter the SQL server you are going to use for ADMT in the next dialog:
5. Click Finish when it’s done!
Ways to Use Active Directory Migration Tool for Intraforest Migration
Now we are going to walk through a common usage scenario for ADMT, an intraforest migration. This is when you need to move objects from one location to another in the same AD forest.
Behaviors to Consider During Intraforest Active Directory Domain Object Migration
First, you need to understand the domain trust relationships that exist in your forest. You could have situations where users will lose access to resources because of a missing trust relationship.
Second, build a spreadsheet or something to document the objects that you are moving, the source path and destination, and their status in the process.
Third, you will want to create a test plan to verify functionality post move – this is something ADMT does not provide.
And last, ADMT doesn’t have a rollback function. Do be sure before you press the button.
Importance of an Include File
For large moves you should use an include file to input the move data into ADMT. Small moves – under ten objects or so – you can manage in the UI or command line. You will want to use an include file for more objects than that.
An include file is a list of each object you want to move and where you want the object to move to. Here are the four possible items in each line of an include file.
- SourceName The SAM account name of the object you are moving.
- TargetRDN The new relative distinguished name of the object after the move.
- TargetSAM Specifies the new target SAM for the object.
- TargetUPN Specifies the new UPN for the target – only applies to user objects.
A simple example of an include file would look like this:
Only the source name is required in the first column – the rest of the fields are optional. In this case, we specified the RDN and the UPN for the new object.
Understand Active Directory Forest
As previously mentioned, you need to map out your AD Forest before you perform your migration. Forests can have parent–child relationships that have default trusts, or you could configure trusts manually between domains.
A domain trust means that authentications to one domain are trusted – the second domain accepts the first domain’s authentication – by other domains with a valid trust relationship.
If you don’t verify your trust relationships before you migrate objects you might inadvertently lock out users or objects. Don’t do that!
Pre Migration Checklist
- Create a spreadsheet of your migration. Track the source objects and their target locations. Use this spreadsheet to create your Include File.
- Double-check your spreadsheet and include file.
- Run a migration test with a test account and verify permissions. If you are using a least-privilege model, you might need to run more than one test depending on your source permission sets.
- Follow your change management process and inform users of the impending changes.
- Make sure you are using the latest and greatest ADMT from Microsoft as you prepare and test your migration.
Migrating Limited Objects
Follow this procedure when you are migrating a small number of objects with ADMT.
1. Open ADMT.
2. From the Toolbar, select Action -> User Account Migration Wizard. You will see this dialog. Click Next to start the wizard.
3. Select the Source and Target Domain Controller and Domain. Click Next.
4. Click ‘Select Users from Domain’ in the next dialog.
5. In the next dialog, click add and select the users from the domain that you want to migrate, click OK.
6. Check the main window and verify that the displayed users match the users you want to migrate. Click Next.
7. Select the target Organizational Unit (OU). Click Next.
8. Select the checkboxes for “translate roaming profiles” and “update user rights.” Ignore any warnings and click Next.
9. The next dialog is the Conflict Resolution dialog. Select “do not migrate source object if a conflict is detected in the domain” just in case there are any conflicts to resolve. Click Next.
10. Click Finish, wait for the process to complete, and look for any error messages and a migration summary.
Migrating Large Number of Objects
This process is the same as the previous process, but you select the option to “read objects from an include file.” Of course, you want your include file to be configured correctly. Otherwise, the rest of the process is the same as above.
There is a different wizard to migrate entire groups in AD. Migrating groups is a similar process to individual users.
- From ADMT, select Action -> Group Account Migration Wizard.
- In the next dialog, fill in the source and target domains. Click Next.
- Next, select the box for the appropriate option – select groups or include file. Click Next.
- Enter the target OU. Click Next.
- Leave everything blank in this dialog and click Next.
- In the Conflict Resolution dialog, select “Do not migrate source object if a conflict is detected in the target domain.” Click Next.
- Double check your input in the following dialog and click Finish.
- Verify the results.
Migrating a Large Number of Groups
This process is the same as the process for groups above, except you use the include file option. Verify ADMT reads your include file correctly before you click Finish.
Migrating Workstations or Member Servers
1. From ADMT, select Action -> Computer Migration Wizard.
2. In the next dialog, fill in the source and target domains. Click Next.
3. Next, select the box for the appropriate option – select groups or include file. Click Next.
4. Enter the target OU. Click Next.
5. Leave everything blank in this dialog and click Next.
6. In the Conflict Resolution dialog, select “Do not migrate source object if a conflict is detected in the target domain.” Click Next.
7. Double check your input in the following dialog and click Finish.
8. Verify the results.
Migrating Objects from Child Domain to Parent Domain Using Command Line
Of course, you can use PowerShell to do these same jobs without the ADMT GUI.
To migrate users without an include file use the following syntax:
ADMT USER /N “”<username>” /IF:YES /SD:<”sourcedomain”> /TD:<”targetdomain”> /TO:<”:”>
/N user or group name you need to migrate
/IF Yes if you are doing an intraforest migration
/SD the source domain
/TD the target domain
/TO the target OU
To migrate users or groups with an include file:
ADMT USER /F “<includefile_name>” /IF:YES /SD:<”source_domain”> /TD:<”target_domain”> /TO:<”target_OU”>
/F is the include file you created for the migration.
Maintaining Active Directory correctly with tools like ADMT can reduce your risk profile and protect you from cyberattacks. Without proper care, your AD could become a target rich environment of over-permissive or stale accounts.
For more tips and tricks on minimizing risk in AD check out the webinar:
We've been keeping the world's most valuable data out of enemy hands since 2005 with our market-leading data security platform.How it works
Michael has worked as a sysadmin and software developer for Silicon Valley startups, the US Navy, and everything in between.