Lesson: Mastering Active Directory Migration with ADMT

Introduction: Why Active Directory Migration Matters

Active Directory Domain Services (AD DS) serves as the identity backbone for the vast majority of enterprise environments. It manages user authentication, computer authorization, and policy enforcement across the network. Because of its critical role, migrating Active Directory from one environment to another is one of the most high-stakes tasks an IT professional can undertake. Whether your organization is undergoing a merger, an acquisition, a domain consolidation, or a forest redesign, the ability to move objects—users, groups, and computers—between Active Directory environments is essential.

The Active Directory Migration Tool (ADMT) is the primary utility provided by Microsoft to facilitate these transitions. Unlike simple copy-paste operations, migrating identity objects involves complex tasks like SID history migration, password migration, and security descriptor translation. If done incorrectly, migrations can lead to extended downtime, orphaned resources, broken file permissions, and significant security gaps. This lesson explores the technical architecture of ADMT, the prerequisites for a successful migration, and the step-by-step procedures required to execute a migration safely.

Understanding the ADMT Architecture

At its core, ADMT is designed to perform inter-forest or intra-forest migrations. It functions as a bridge that reads objects from a source domain and recreates them in a target domain. To achieve this, it relies on a SQL Server database to track the migration status, map objects, and ensure that the migration process is repeatable and auditable.

When you install ADMT, you are deploying a management console and a service that interacts with the source and target domain controllers. The tool does not simply "move" an object; it performs a "copy and re-create" operation. During this process, ADMT handles the complexities of maintaining the security identity (SID) history, which is vital for ensuring that users can still access resources in the old domain while they transition to the new one.

Callout: ADMT vs. Manual Recreation Many administrators wonder why they shouldn't just create new accounts and manually assign permissions. While manual recreation is feasible for five users, it is impossible at scale. ADMT automates the translation of security descriptors on files, folders, and printers. If you manually recreate a user, that user loses their link to their historical data permissions. ADMT preserves the integrity of the security environment, which is why it is the standard tool for enterprise migrations.

Core Components of the Migration Environment

1. The Migration Server: This is the machine where the ADMT software is installed. It must be a member of the target domain and should be a dedicated server to avoid performance bottlenecks.
2. The SQL Database: ADMT requires a SQL Server instance to store migration logs, object mappings, and state information.
3. The Source and Target Domains: These must be connected via a functional two-way trust relationship.
4. The ADMT Agent: This is a small service pushed to target computers to facilitate the translation of local security settings when migrating computer objects.

Prerequisites for a Successful Migration

Before you even open the ADMT console, you must ensure your environment is prepared. A failure to meet these prerequisites is the most common cause of migration failure.

1. Trust Relationships

You must establish a two-way, transitive forest trust between the source and target domains. This trust allows the ADMT server to authenticate against both environments. Ensure that DNS resolution is functioning perfectly between the two forests; if the domains cannot resolve each other's domain controllers, the migration will stall immediately.

2. Permissions and Rights

The account running the ADMT migration must have specific privileges:

• Target Domain: Must be a member of the Domain Administrators group.
• Source Domain: Must be a member of the Administrators group (or have equivalent delegated rights) to read objects.
• SQL Server: The account must have db_owner permissions on the ADMT database.

3. SID History Requirements

To enable SID history migration, you must perform two specific configuration tasks. First, you must enable auditing on the source domain. Second, you must run a specific script on the target domain to allow the SID history attribute to be populated. If you do not perform these steps, ADMT will be unable to migrate the SID history, rendering the migration largely ineffective for maintaining resource access.

Note: Migrating SID history is a security-sensitive operation. Because SID history allows a user to act as their old identity, it effectively bypasses traditional access controls. Always disable SID history migration if you do not strictly require it for legacy resource access.

Step-by-Step: Setting Up the Migration Environment

Step 1: Install SQL Server

ADMT does not ship with a full SQL engine, so you must have a supported version of SQL Server installed. For small to medium migrations, SQL Server Express is often sufficient, but for large-scale enterprise migrations, a standard edition is recommended to handle the logging load.

Step 2: Install ADMT

Install the ADMT binary on the designated migration server. During the installation, you will be prompted to link the tool to your SQL database. Once installed, launch the ADMT console.

Step 3: Configure Auditing

You must configure the source domain controllers to audit account management. This is done via Group Policy. If auditing is not enabled, ADMT cannot track the changes required for password migration.

Step 4: Enabling SID History

This requires the use of the admt.exe command-line utility. You must run the following command on the target domain controller:

# This command enables the target domain to accept SID history
admt key /option:create /sourcedomain:SourceDomainName /keyfile:C:\Temp\keyfile.pes

Note: The .pes file is the Password Export Server file. You must copy this file to the source domain controller to perform password migration.

Migrating User and Group Objects

The core of your work will involve the User Account Migration Wizard. This wizard handles the migration of users, their passwords, and their group memberships.

Workflow for User Migration

1. Selection: Select the source domain and the target organizational unit (OU).
2. Account Conflict Resolution: Decide what happens if a user with the same name already exists in the target domain. Options include skipping the migration, renaming the user, or replacing the existing user.
3. Password Migration: If you are migrating passwords, you must have the Password Export Server (PES) installed on the source domain's Primary Domain Controller.
4. Object Properties: Choose which attributes to migrate. You should generally migrate all attributes, but be careful with attributes that are specific to the source infrastructure (like legacy exchange attributes).

Practical Example: Migrating a Group

When migrating groups, you have the option to perform a "member migration." If you select this, ADMT will look at the group members in the source domain and, if those members have already been migrated to the target domain, it will automatically add them to the new group. This is a massive time-saver.

# Example of a command-line migration for a specific user
admt user /sourceDomain:SourceDom /targetDomain:TargetDom /user:JohnDoe /targetOU:"OU=Users,DC=Target,DC=com" /migrateSIDs:yes /sIDHistory:yes

Warning: Always perform a test migration with a small set of pilot users before initiating a bulk migration. Once you migrate a user, undoing the process is difficult and can leave the user account in a "dirty" state where it exists in both domains but functions in neither.

Migrating Computer Objects and Security Translation

Migrating computers is more complex than migrating users because of the computer's local security database (the SAM). When you migrate a computer, it must be joined to the new domain, and its local permissions must be updated to recognize the new domain's security principals.

The Security Translation Wizard

This wizard is the "magic" of ADMT. It scans local files, shares, and registry keys on the target computers and replaces the old SIDs with the new SIDs. This ensures that a user who had "Read" access to a folder on their local machine before the migration still has "Read" access after the migration.

1. Select Computers: Choose the computers from the source domain.
2. Translation Options: You can choose to replace or add the new SIDs. For most migrations, you want to "Add" the new SID to the existing ACL (Access Control List). This allows the user to access files using either their old identity or their new one.
3. Agent Installation: ADMT will push an agent to the target computer. This agent performs the translation locally. You must ensure that the firewall on the target computers allows communication from the ADMT server.

Best Practices for Enterprise Migrations

1. The "Pilot First" Rule

Never start a migration with your VIPs or your most critical servers. Start with a non-production OU containing test user accounts and a few virtual machines. This allows you to validate your trust, your permissions, and your migration script logic without impacting business operations.

2. DNS Hygiene

ADMT is highly sensitive to DNS issues. Ensure that your forwarders and conditional forwarders are configured correctly. If the ADMT server cannot resolve the target domain controller by its FQDN, the migration will time out.

3. Cleanup of SID History

Once the migration is complete and you have verified that all applications and services are working, you should eventually remove the SID history. Keeping SID history indefinitely poses a security risk. Develop a plan to remove the sIDHistory attribute from migrated accounts after a transition period (typically 30–90 days).

4. Use Service Accounts Carefully

Service accounts are the most common point of failure. Because service accounts often run with hardcoded credentials or are embedded in configuration files, migrating them can break application connectivity. Always document service account dependencies before moving them.

Common Pitfalls and Troubleshooting

Troubleshooting "Access Denied"

This is the most common error. If you receive an "Access Denied" error, check the following:

• The ADMT Service Account: Does it have "Domain Admin" rights in both domains?
• Firewalls: Is Port 445 (SMB) and RPC ports open between the ADMT server and the target domain controllers?
• Database connectivity: Is the ADMT service able to write to the SQL database? Check the SQL logs for permission issues.

Handling Orphaned Objects

If a migration fails halfway through, you may end up with objects in the target domain that are not fully configured. Use the ADMT log files located in the C:\Windows\ADMT\Logs directory. These logs provide granular detail on why a specific object failed to migrate.

Callout: The Role of Logs ADMT generates extensive log files for every operation. If an object fails to migrate, don't just retry the operation. Open the log file, search for the object's GUID, and identify the specific error code. Often, the error is as simple as an object name conflict or a missing attribute value.

Comparison Table: Migration Methods

Advanced Scenarios: Password Export Server (PES)

The Password Export Server is a separate installation that must be placed on the source domain controller. This is a security-hardened utility that allows ADMT to move the password hashes from the source to the target.

Setting up PES

1. Install the PwdMig.msi on the source domain controller.
2. Run the admt key command to generate the .pes file.
3. Import the key into the PES on the source domain controller.
4. Restart the Netlogon service on the source domain controller.

If you skip the restart of the Netlogon service, the password migration will fail, and you will see "Access Denied" or "Encryption Error" in your logs. This is a common point of confusion for new administrators.

Security Considerations for Migrations

Migrating Active Directory is, in effect, modifying your entire security perimeter. During the migration, you are creating a path of least resistance between two domains.

• Least Privilege: Once the migration is complete, remove the ADMT service account from the Domain Admin groups.
• Trust Directionality: Ensure the trust is set to "Selective Authentication" if you want to limit what the domains can see of each other.
• Auditing: Turn on "Success/Failure" auditing for all account management events during the migration window. This will allow you to see if any unauthorized accounts are being accessed or modified.

Key Takeaways

1. Automation is Essential: Never attempt to migrate more than a handful of objects manually. ADMT provides the necessary automation to handle SID history and ACL translation, which are critical for maintaining business continuity.
2. Trust and DNS are Paramount: The stability of your migration depends entirely on the health of your cross-forest trust and DNS resolution. If these are not configured correctly, no amount of ADMT configuration will make the migration work.
3. Pilot Testing Saves Lives: Always run a pilot migration. The "fail fast" approach allows you to identify configuration errors in your test environment before they impact production users.
4. The PES is a Security Component: Treating the Password Export Server (PES) with care is critical. It is a powerful tool that, if mismanaged, could expose sensitive credential data. Always follow the official documentation for PES installation.
5. Post-Migration Cleanup: A migration is not finished when the objects are moved. You must perform security cleanup, such as removing SID history and cleaning up the ADMT service accounts, to ensure the environment remains secure.
6. Log Analysis is Your Best Friend: When things go wrong—and they eventually will—the log files in the ADMT\Logs directory are the only source of truth. Learn to read them and use them to isolate failed migrations.
7. Document Dependencies: Before migrating servers or users, map their dependencies. Knowing which applications rely on specific user SIDs or computer accounts will save you hours of troubleshooting after the migration is complete.

By following these guidelines and adhering to the structured approach of ADMT, you can ensure that your organization's identity migration is smooth, secure, and successful. Remember that migration is a process, not a single event, and the work you do in preparation will define the outcome.