Migrate Users from Account Forest to Exchange Resource Forest

This article explains how to migrate Active Directory users of a so-called account forest domain to an Exchange resource forest domain including the conversion of linked into regular mailboxes.

Running an Exchange installation in a separate forest has the advantage that Exchange schema extensions are kept completely separate from the forest the account domain belongs to. It is also an administrative boundary for example in case Exchange is provided by a hosting company.

On the other hand, it adds complexity and additional domain controllers to the environment that have to be taken care of.

Table of Contents:

1. Overview
2. Before the Migration
3. Migration of Users and Conversion of Mailboxes
4. After the Cross Forest Migration
5. Conclusion

Overview

This scenario is based on an actual customer request we have received recently. There are two forests, one so-called account forest where user accounts, groups and OUs are kept and a second forest, where Microsoft Exchange is installed and mailboxes are hosted. The customer was facing the task to consolidate the account forest's domain with the exchange resource forest domain, essentially getting rid of the current account domain.

If running Exchange in its own forest, mailboxes are setup as linked mailboxes. Each mailbox has a deactivated user account in the exchange forest's domain and the mailboxes are configured to grant access to the corresponding user account of the account domain.

During the migration, the Exchange mailboxes need to be converted from linked to regular mailboxes. The deactivated user account in the target domain needs to be merged with the user from the account domain. For example it needs to preserve the displayName attribute of the account in the target domain, which is used in Exchange address books, while updating the account password with the one from the source domain.

CopyRight2 has been installed on a server of the Exchange resource domain. It can optionally be installed on a domain controller to maximize performance. Besides of running it in the target domain (pull configuration) you can use the same settings if you prefer running it from the source domain (push configuration).

In addition to CopyRight2, the CopyRight2 Password Migration Add-On and the PowerShell Integration Add-On were installed on the same server to support the migration of user account passwords and to allow use of the Exchange PowerShell commandlets.

While this is possible entirely without using PowerShell, simply by changing the corresponding Active Directory attributes, we prefer to stick to the approach recommended by Microsoft. This additionally gives us the opportunity to showcase how to call PowerShell commandlets with CopyRight2's PowerShell Integration Add-On.

Before the Migration

Before the migration takes place, users are logging on with their corresponding user account located in the account forest's domain. The linked mailboxes grant permissions allowing them to access their mailboxes  using Microsoft Outlook.

Migration of Users and Conversion of Mailboxes

To perform the actual migration between the account forest and the exchange resource forest, the first step is to define a User and Group Migration job within CopyRight2:

In the Source and Destination page, we provide the NetBIOS names of the source and the target domain controller:

Now we need to select the user accounts that should be migrated to the target domain:

In the Filter page we activate the migration of users. For the sake of simplicity we do not migrate other object types, such as domain local groups, global groups, universal groups, distributions lists or contacts. It is important to configure the object type for Add/Update because we want the job to update the existing and currently disabled mailbox account in the target domain:

Next we enable the migration of passwords in the Settings page:

To migrate the OU hierarchy to the target domain we enable the corresponding option in the Active Directory Options page. In this example the hierarchy is copied to the root of the target domain, but you could alternatively migrate the hierarchy below a specified OU as well. If using this option, CopyRight2 will migrate each migrated object's OU parents automatically:

In the AD Attribute page, we remove the displayName attribute from the list of attributes to migrate. This is done to preserve the display name of the deactivated accounts associated with each mailbox in the target domain, because the display name is used in address books. If you want to preserve any additional attributes, for example first name, last name and so on, you could remove these as well:

In the Advanced page we need to activate the "Map security identifiers with a predefined mapping table" option to define the relationship between the samAccountName of accounts in the source and the target domain. The mapping is not needed if the samAccountName attribute is identical in both domains:

The mapping file is a simple text file, having one row per mapped user account with the following format:

Source-Domain-NetBIOS-Name\Account-Name;Destination-Domain-NetBIOS-Name\Account-Name;3

In order to be able to call Exchange management commandlets we need to call PowerShell's Add-PSsnapin first. This is done in a Job Start type of script that gets executed only once each time the CopyRight2 job is executed:

It is prefixed by '#' to indicate that it is a PowerShell command and to differentiate from regular VBScript (Scripting Host). Here is the line of code in its entirety:

#Add-PSsnapin -Name "Microsoft.Exchange.Management.PowerShell.SnapIn" -ErrorAction "SilentlyContinue"

Next we change the Script Type to Transform Users to define the scriptlet that gets executed once for each migrated user object:

The script is passing the source account's mail attribute, containing the SMTP address, to the set-user PowerShell commandlet's identity parameter. To get the content of the mail attribute, CopyRight2's scripting host function Source() is used having the attribute name as parameter:

#set-user -Identity Source("mail") -LinkedMasterAccount $null

You could achieve the same by using the script below instead, without resorting to PowerShell. This script uses the Destination() function, having the attribute name as a parameter to access the target object's attributes:

Destination("msExchRecipientDisplayType")=0
Destination("msExchRecipientTypeDetails")=1
Destination("msExchMasterAccountSid")=Empty

However, this is not recommended and should be considered a hack, because the attributes involved could change for example. The list of attributes above were determined by running an LDIFDE export for an account before and after execution of the set-user commandlet and then comparing the results.

After the Cross Forest Migration

After running the migration job, you will see that the previously deactivated account in the target domain associated with each mailbox, now is activated and that the corresponding Exchange mailbox is now showing up as a regular instead of a linked mailbox. Furthermore the password has been migrated so that users can actually logon with that account and access their mailboxes.

Conclusion

After reading this article you should know now how to perform an account forest domain to Exchange forest domain migration. You will also have learned how PowerShell scripts can be integrated into CopyRight2's scripting host implementation. If you should want to read more about the PowerShell Integration Add-on you could read the "How To: Integrate PowerShell to Extend Your Migration Process" blog posting.

If you should have any feedback, positive or negative or some follow-up questions, please let us know in the comments below. Thank you.