ADMT Cross-Forest migration, the PowerShell way!

Introduction

A while back, I migrated around 29K Exchange 2007 mailboxes and users with one PowerShell migration script cross-forest to Exchange 2010 into an in-house developed multitenant provisioning platform. Along these mailboxes there were also all kinds of AD Tenant related objects. All objects had to be provisioned in multiple domains in the target forest. Because I dont like any manual tasks or Vbscripts executed from PowerShell everything was automated with native PowerShell scripting only. And better yet, everything was centralised and executed from just one script embedded with multiple functions. This script is placed on a management server in the target domain which served as the initiator for all migration tasks.

Generally ADMT is installed on the target domain controller, the reason for that is to be able to copy the SID from the source user into the SIDhistory attribute onto the target user. Because of security reasons the DsAddSidHistory API function which is called by ADMT needs to be executed on a domain controller in the target domain, in turn the domain controller in the source domain selected for the SID copy operation needs to be the primary domain controller. Because Im operating in a heavily used production environment, I tried to find a way where you wont have to install or modify anything on the domain controllers, every change is one too many and could potentially lead to outage or even worse compromise the security. Besides that its cool to find a way to automate things and circumvent installers and extra layers of software, that way you can hook into the same APIs the software is using and write your own tailored made code/application on top of it, Since ADMT could operate on a member server I installed the ADMT package on the management server but then of course I would miss the SID copy functionality from ADMT. After investigating how the SID copy process worked I stumbled upon a custom made .NET assembly called SIDCloner which can be imported in PowerShell and also uses the DsAddSidHistory API. Without installing any software this assembly file can be placed on the target domain controller and remotely executed in a script block with the invoke-command cmdlet from the management (migration) station. Then I had to automate ADMTs object and password copy process in PowerShell and thats not that straight forward, most ADMT automation scripts and projects found are done with VB. The trick is using the ADMT.Migration COM object in PS, the object is installed as part of the ADMT installation and also used in VB scripts. If you want to copy passwords with ADMT then you also need a Password Export server setup on the source domain controller, ADMT uses this server when you enabled the password copy option in the ADMT script.

Eventually I scripted everything in PS and ended up in custom made migration script with around 1.3K lines and 22 functions leaning on my multitenant provisioning script. This mutlitenant script actually replaces a full blown provisioning engine for AD/Exchange/Sharepoint/Lync/Hosted Destkop provisioning and is somewhere around 5K lines of code and is dotsourced in the migration script. By dotsourcing the provisioning script all functions and global variables are made available in the migration script, this way you seperate the functionality and code (version control) is maintained per script.

Setup

Setting up ADMTs installation and configuration is done quite easily and partially covered in this blog post, I kindly refer you to Technet or the numerous blog posts covering the topic. For the SIDcopy part you have to download SIDCloner, extract the assembly sidcloner.dll and place it on the filesysem of the target domaincontroller youre going to use. There are three more steps to take before you are able to use SIDcloner. Creating the domain local group ($$$SourceDomain) in the source domain, enabling SIDhistory on the trust between the two domains and enabling the auditing of success and failures in the account management section of the DC domain GPO.

netdom trust targetdomain /domain:"sourcedomain" /enableSIDhistory:"yes" /usero:"administrator" /passwordo:"SomePassword"

1	netdom trust targetdomain /domain:"sourcedomain" /enableSIDhistory:"yes" /usero:"administrator" /passwordo:"SomePassword"

If youre going to use the Password Export Server (PES) just follow this article, you will have to generate the encryption file via ADMT and use that file in the installation process of the PES MSI installer.

admt key /option:"create" /sourcedomain:"SourceDomain" /keyfile:"EncryptionFilePath" /keypassword:"SomePassword"

1	admt key /option:"create" /sourcedomain:"SourceDomain" /keyfile:"EncryptionFilePath" /keypassword:"SomePassword"

Also dont forget to run the PES service under a privileged user account from the target domain. PES bits can be downloaded from here. The installation and download links all refer to Microsofts connect site, there you can find the latests versions, they work with 2012 R2 and they are customized to work with Microsoft Azures Active Directory.

Code

Most COM objects are oldschool and therefore 32-bit, so if you want to use the ADMT.migration COM object in the ADMT migration script, you have to execute it under a 32-bit PowerShell session.

$Migration = New-Object -ComObject "ADMT.Migration"

1	$Migration = New-Object -ComObject "ADMT.Migration"

Since Im using 64-bit snappins and modules in a 64-bit PS runtime environment, the only quick and clean way is executing the ADMT migration task in a 32-bit job process with the start-job cmdlet combined with the -RunAs32 parameter set to $true. My job executes the admtmig.ps1 script on the same management/migration box with all the constants and options required by ADMT. The admtmig.ps1 script requires two arguments, one tenant variable and one admtobjects variable. The Tenant argument is used to create two new AD canonical name (CN) variables in the script based on the existing source and new target OU. The admtobjects argument is an array of objects from the source domain to be migrated and are also in a canonical name (CN) format. The following code executes the script and waits for the job to finish.

$job = Start-Job {admtmig.ps1 $args[0] $args[1]}  -ArgumentList @($tenant,$admtobjects) -RunAs32:$true Name $tenant 
$job| Wait-Job | Receive-Job; Remove-Job $tenant -ErrorAction SilentlyContinue -Confirm:$false

$job = Start-Job {admtmig.ps1 $args[0] $args[1]} -ArgumentList @($tenant,$admtobjects) -RunAs32:$true Name $tenant

$job| Wait-Job | Receive-Job; Remove-Job $tenant -ErrorAction SilentlyContinue -Confirm:$false

You have to adjust the admtmig.ps1 script (below) to your needs, scroll through the script and modify the variables like source/ target domain DCs , password server and the native ADMT constants.

I left it pretty standard but you have to take a look at the properties I excluded, basically they are all Exchange properties which I didnt need since I already read out and stored all source users and their related Exchange attributes in nested Hashtables. Eventually I converted all the values to the new Exchange multitenant provisioning scheme in the target domain. Another benefit in this approach is capturing the old configuration before ADMT or Exchange MRS (mailbox move) could modify it.

### BEGIN ADMT Scripting Constants ###

# Arguments

$Tenant = $args[0]
[array]$AdmtObjects = $args[1]

# Domain

$TargetDomain = "target.local" 
$SourceDomain = "source.local" 
$DCSource = "dc1.source.local"
$DCTarget = "dc1.target.local"
$PWserver = $DCTarget

# OU

$Tenant = $args[0]
$TenantSourceOU = "hosting/$Tenant"
$TenantTargetOU = "hostingv2/$Tenant" 



# PasswordOption constants

$admtComplexPassword                   = "&H0001"
$admtCopyPassword                      = "&H0002"
$admtDoNotUpdatePasswordsForExisting   = "&H0010"

# ConflictOptions constants

$admtIgnoreConflicting           = "&H0000"
$admtMergeConflicting            = "&H0001"
$admtRemoveExistingUserRights    = "&H0010"
$admtRemoveExistingMembers       = "&H0020"
$admtMoveMergedAccounts          = "&H0040"

# DisableOption constants

$admtLeaveSource        = "&H0000"
$admtDisableSource      = "&H0001"
$admtTargetSameAsSource = "&H0000"
$admtDisableTarget      = "&H0010"
$admtEnableTarget       = "&H0020"

# SourceExpiration constant

$admtNoExpiration = "-1"

# Translation Option

$admtTranslateReplace = "0"
$admtTranslateAdd     = "1"
$admtTranslateRemove  = "2"

# Report Type

$admtReportMigratedAccounts  = "0"
$admtReportMigratedComputers = "1"
$admtReportExpiredComputers  = "2"
$admtReportAccountReferences = "3"
$admtReportNameConflicts     = "4"

# Option constants

$admtNone     = "0"
$admtData     = "1"
$admtFile     = "2"
$admtDomain   = "3"
$admtRecurse           = "&H0100"
$admtFlattenHierarchy  = "&H0000"
$admtMaintainHierarchy = "&H0200"

# Event related constants

# Progress type
$admtProgressObjectMigration   = "0"
$admtProgressAgentDispatch     = "1"
$admtProgressAgentOperation    = "2"
$admtProgressMailboxMigration  = "3"

# Event type
$admtEventNone                         = "0"
$admtEventObjectInputPreprocessed      = "1"
$admtEventTaskStart                    = "2"
$admtEventTaskFinish                   = "3"
$admtEventObjectProcessed              = "4"
$admtEventGroupMembershipProcessed     = "5"
$admtEventAgentStatusUpdate          ="6"
$admtEventAgentNotStarted = "7"
$admtEventAgentFailedToStart = "8"
$admtEventAgentWaitingForReboot = "9"
$admtEventAgentRunning = "10"
$admtEventAgentCancelled = "11"
$admtEventAgentPassed = "12"
$admtEventAgentFailed = "13"
$admtEventAgentWaitingForRetry = "14"
$admtEventAgentSuccessful = "15"
$admtEventAgentCompletedWithWarnings = "16"
$admtEventAgentCompletedWithErrors = "17"
$admtEventTaskLogSaved = "18"


$admtAgentPreCheckPhase = "&H100"
$admtAgentAgentOperationPhase = "&H200"
$admtAgentPostCheckPhase = "&H300"

$admtAgentStatusMask = "&HFF"
$admtAgentPhaseMask = "&H300"

# Status type
$admtStatusSuccess   = "0"
$admtStatusWarnings  = "1"
$admtStatusErrors    = "2"

### END ADMT Scripting Constants ###

# Sets OU location , migration object and global variables 
# already populated in main script.
$Migration = New-Object -ComObject "ADMT.Migration"
$Migration.SourceOU = $TenantSourceOU
$Migration.TargetOU = $TenantTargetOU
#Creates an instance of an ADMT migration object using the COM-object provided with ADMT
$Migration.IntraForest = $false
$Migration.SourceDomain = $SourceDomain
$Migration.SourceDomainController = $DCSource
$Migration.TargetDomain = $TargetDomain
$Migration.TargetDomainController = $DCTarget 
$Migration.PasswordOption = $admtCopyPassword
$Migration.PasswordServer = $PWserver
$Migration.ConflictOptions = $admtIgnoreConflicting
$Migration.UserPropertiesToExclude = "publicDelegates,publicDelegatesBL,otherWellKnownObjects,msExchUseOAB,msExchQueryBaseDN,adminDisplayName,altRecipient,authOrig,autoReplyMessage,deletedItemFlags,delivContLength,deliverAndRedirect,displayNamePrintable,dLMemDefault,dLMemRejectPerms,dLMemSubmitPerms,extensionAttribute15,folderPathname,garbageCollPeriod,homeMDB,homeMTA,internetEncoding,legacyExchangeDN,mAPIRecipient,mDBUseDefaults,msExchADCGlobalNames,msExchControllingZone,msExchExpansionServerName,msExchFBURL,msExchHideFromAddressLists,msExchHomeServerName,msExchMailboxGuid,msExchMailboxSecurityDescriptor,msExchPoliciesExcluded,msExchPoliciesInclude,msExchRecipLimit,msExchResourceGUID,protocolSettings,proxyAddresses,publicDelegates,securityProtocol,showInAddressBook,submissionContLength,targetAddress,textEncodedORAddress,unauthOrig,msExchIMAPOWAURLPrefixOverride,sAMAccountType,Sidhistory"
$Migration.InetOrgPersonPropertiesToExclude = ""
$Migration.GroupPropertiesToExclude = ""
$Migration.ComputerPropertiesToExclude = ""
$Migration.SystemPropertiesToExclude = "publicDelegates,publicDelegatesBL,otherWellKnownObjects,msExchUseOAB,msExchQueryBaseDN,adminDisplayName,altRecipient,authOrig,autoReplyMessage,deletedItemFlags,delivContLength,deliverAndRedirect,displayNamePrintable,dLMemDefault,dLMemRejectPerms,dLMemSubmitPerms,extensionAttribute15,folderPathname,garbageCollPeriod,homeMDB,homeMTA,internetEncoding,legacyExchangeDN,mAPIRecipient,mDBUseDefaults,msExchADCGlobalNames,msExchControllingZone,msExchExpansionServerName,msExchFBURL,msExchHideFromAddressLists,msExchHomeServerName,msExchMailboxGuid,msExchMailboxSecurityDescriptor,msExchPoliciesExcluded,msExchPoliciesInclude,msExchRecipLimit,msExchResourceGUID,protocolSettings,proxyAddresses,publicDelegates,securityProtocol,showInAddressBook,submissionContLength,targetAddress,textEncodedORAddress,unauthOrig,msExchIMAPOWAURLPrefixOverride,sAMAccountType,Sidhistory"
$Migration.PerformPreCheckOnly = $false
$Migration.AdmtEventLevel = $admtStatusWarnings
$Migration.CommandLine = $false

# Creates an user migration object
$UserMigration = $Migration.CreateUserMigration()
$UserMigration.DisableOption = $admtTargetSameAsSource
$UserMigration.SourceExpiration = $admtNoExpiration
$UserMigration.MigrateSIDs = $false
$UserMigration.TranslateRoamingProfile = $false
$UserMigration.UpdateUserRights = $false
$UserMigration.MigrateGroups = $false
$UserMigration.UpdatePreviouslyMigratedObjects = $false
$UserMigration.FixGroupMembership = $false
$UserMigration.MigrateServiceAccounts = $false


#Initiates user migration. Logs are written to windir-ADMT-Logs by default.
$UserMigration.Migrate($admtData,$admtobjects,$null)

#Creates a password migration object
$PasswordMigration = $Migration.CreatePasswordMigration()

#Initiates password migration. Logs are written to windir-ADMT-Logs by default.
$PasswordMigration.Migrate($admtData,$admtobjects,$null)

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

### BEGIN ADMT Scripting Constants ###

# Arguments

$Tenant = $args[0]

[array]$AdmtObjects = $args[1]

# Domain

$TargetDomain = "target.local"

$SourceDomain = "source.local"

$DCSource = "dc1.source.local"

$DCTarget = "dc1.target.local"

$PWserver = $DCTarget

# OU

$Tenant = $args[0]

$TenantSourceOU = "hosting/$Tenant"

$TenantTargetOU = "hostingv2/$Tenant"

# PasswordOption constants

$admtComplexPassword = "&H0001"

$admtCopyPassword = "&H0002"

$admtDoNotUpdatePasswordsForExisting = "&H0010"

# ConflictOptions constants

$admtIgnoreConflicting = "&H0000"

$admtMergeConflicting = "&H0001"

$admtRemoveExistingUserRights = "&H0010"

$admtRemoveExistingMembers = "&H0020"

$admtMoveMergedAccounts = "&H0040"

# DisableOption constants

$admtLeaveSource = "&H0000"

$admtDisableSource = "&H0001"

$admtTargetSameAsSource = "&H0000"

$admtDisableTarget = "&H0010"

$admtEnableTarget = "&H0020"

# SourceExpiration constant

$admtNoExpiration = "-1"

# Translation Option

$admtTranslateReplace = "0"

$admtTranslateAdd = "1"

$admtTranslateRemove = "2"

# Report Type

$admtReportMigratedAccounts = "0"

$admtReportMigratedComputers = "1"

$admtReportExpiredComputers = "2"

$admtReportAccountReferences = "3"

$admtReportNameConflicts = "4"

# Option constants

$admtNone = "0"

$admtData = "1"

$admtFile = "2"

$admtDomain = "3"

$admtRecurse = "&H0100"

$admtFlattenHierarchy = "&H0000"

$admtMaintainHierarchy = "&H0200"

# Event related constants

# Progress type

$admtProgressObjectMigration = "0"

$admtProgressAgentDispatch = "1"

$admtProgressAgentOperation = "2"

$admtProgressMailboxMigration = "3"

# Event type

$admtEventNone = "0"

$admtEventObjectInputPreprocessed = "1"

$admtEventTaskStart = "2"

$admtEventTaskFinish = "3"

$admtEventObjectProcessed = "4"

$admtEventGroupMembershipProcessed = "5"

$admtEventAgentStatusUpdate ="6"

$admtEventAgentNotStarted = "7"

$admtEventAgentFailedToStart = "8"

$admtEventAgentWaitingForReboot = "9"

$admtEventAgentRunning = "10"

$admtEventAgentCancelled = "11"

$admtEventAgentPassed = "12"

$admtEventAgentFailed = "13"

$admtEventAgentWaitingForRetry = "14"

$admtEventAgentSuccessful = "15"

$admtEventAgentCompletedWithWarnings = "16"

$admtEventAgentCompletedWithErrors = "17"

$admtEventTaskLogSaved = "18"

$admtAgentPreCheckPhase = "&H100"

$admtAgentAgentOperationPhase = "&H200"

$admtAgentPostCheckPhase = "&H300"

$admtAgentStatusMask = "&HFF"

$admtAgentPhaseMask = "&H300"

# Status type

$admtStatusSuccess = "0"

$admtStatusWarnings = "1"

$admtStatusErrors = "2"

### END ADMT Scripting Constants ###

# Sets OU location , migration object and global variables

# already populated in main script.

$Migration = New-Object -ComObject "ADMT.Migration"

$Migration.SourceOU = $TenantSourceOU

$Migration.TargetOU = $TenantTargetOU

#Creates an instance of an ADMT migration object using the COM-object provided with ADMT

$Migration.IntraForest = $false

$Migration.SourceDomain = $SourceDomain

$Migration.SourceDomainController = $DCSource

$Migration.TargetDomain = $TargetDomain

$Migration.TargetDomainController = $DCTarget

$Migration.PasswordOption = $admtCopyPassword

$Migration.PasswordServer = $PWserver

$Migration.ConflictOptions = $admtIgnoreConflicting

$Migration.UserPropertiesToExclude = "publicDelegates,publicDelegatesBL,otherWellKnownObjects,msExchUseOAB,msExchQueryBaseDN,adminDisplayName,altRecipient,authOrig,autoReplyMessage,deletedItemFlags,delivContLength,deliverAndRedirect,displayNamePrintable,dLMemDefault,dLMemRejectPerms,dLMemSubmitPerms,extensionAttribute15,folderPathname,garbageCollPeriod,homeMDB,homeMTA,internetEncoding,legacyExchangeDN,mAPIRecipient,mDBUseDefaults,msExchADCGlobalNames,msExchControllingZone,msExchExpansionServerName,msExchFBURL,msExchHideFromAddressLists,msExchHomeServerName,msExchMailboxGuid,msExchMailboxSecurityDescriptor,msExchPoliciesExcluded,msExchPoliciesInclude,msExchRecipLimit,msExchResourceGUID,protocolSettings,proxyAddresses,publicDelegates,securityProtocol,showInAddressBook,submissionContLength,targetAddress,textEncodedORAddress,unauthOrig,msExchIMAPOWAURLPrefixOverride,sAMAccountType,Sidhistory"

$Migration.InetOrgPersonPropertiesToExclude = ""

$Migration.GroupPropertiesToExclude = ""

$Migration.ComputerPropertiesToExclude = ""

$Migration.SystemPropertiesToExclude = "publicDelegates,publicDelegatesBL,otherWellKnownObjects,msExchUseOAB,msExchQueryBaseDN,adminDisplayName,altRecipient,authOrig,autoReplyMessage,deletedItemFlags,delivContLength,deliverAndRedirect,displayNamePrintable,dLMemDefault,dLMemRejectPerms,dLMemSubmitPerms,extensionAttribute15,folderPathname,garbageCollPeriod,homeMDB,homeMTA,internetEncoding,legacyExchangeDN,mAPIRecipient,mDBUseDefaults,msExchADCGlobalNames,msExchControllingZone,msExchExpansionServerName,msExchFBURL,msExchHideFromAddressLists,msExchHomeServerName,msExchMailboxGuid,msExchMailboxSecurityDescriptor,msExchPoliciesExcluded,msExchPoliciesInclude,msExchRecipLimit,msExchResourceGUID,protocolSettings,proxyAddresses,publicDelegates,securityProtocol,showInAddressBook,submissionContLength,targetAddress,textEncodedORAddress,unauthOrig,msExchIMAPOWAURLPrefixOverride,sAMAccountType,Sidhistory"

$Migration.PerformPreCheckOnly = $false

$Migration.AdmtEventLevel = $admtStatusWarnings

$Migration.CommandLine = $false

# Creates an user migration object

$UserMigration = $Migration.CreateUserMigration()

$UserMigration.DisableOption = $admtTargetSameAsSource

$UserMigration.SourceExpiration = $admtNoExpiration

$UserMigration.MigrateSIDs = $false

$UserMigration.TranslateRoamingProfile = $false

$UserMigration.UpdateUserRights = $false

$UserMigration.MigrateGroups = $false

$UserMigration.UpdatePreviouslyMigratedObjects = $false

$UserMigration.FixGroupMembership = $false

$UserMigration.MigrateServiceAccounts = $false

#Initiates user migration. Logs are written to windir-ADMT-Logs by default.

$UserMigration.Migrate($admtData,$admtobjects,$null)

#Creates a password migration object

$PasswordMigration = $Migration.CreatePasswordMigration()

#Initiates password migration. Logs are written to windir-ADMT-Logs by default.

$PasswordMigration.Migrate($admtData,$admtobjects,$null)

If you want to preserve existing ACLs based on the source users SID you have to copy the SID. Thats where SIDCloner comes in play with the following code.

$sessionoption = New-PSSessionOption -IdleTimeout 3600000
$session = New-PSSession -Credential $Cred -ComputerName $DCtarget -SessionOption $sessionoption -Name "SIDCopy"
	Invoke-Command  -Session $session -Scriptblock {
	    param($sourcesam,$sourcedomainfqdn,$targetsam,$targetdomainfqdn)

			[System.Reflection.Assembly]::LoadFile("SIDCloner.dll")
			[wintools.sidcloner]::CloneSid(
	        	$sourcesam,
	        	$sourcedomainfqdn,
	        	$targetsam,
	        	$targetdomainfqdn
	        	)			
		}  -ArgumentList $sourcesam,$sourcedomainfqdn,$targetsam,$targetdomainfqdn | Out-Null

$sessionoption = New-PSSessionOption -IdleTimeout 3600000

$session = New-PSSession -Credential $Cred -ComputerName $DCtarget -SessionOption $sessionoption -Name "SIDCopy"

Invoke-Command -Session $session -Scriptblock {

param($sourcesam,$sourcedomainfqdn,$targetsam,$targetdomainfqdn)

[System.Reflection.Assembly]::LoadFile("SIDCloner.dll")

[wintools.sidcloner]::CloneSid(

$sourcesam,

$sourcedomainfqdn,

$targetsam,

$targetdomainfqdn

)

} -ArgumentList $sourcesam,$sourcedomainfqdn,$targetsam,$targetdomainfqdn | Out-Null

The copying process is done per user, instead of opening up a new session per user, invoke-command uses an existing session which has an idletimeout of 60 minutes. Invoke-command executes the scriptblock with four arguments and loads the assembly from the local path on the target domain controller. Then the .NET method CloneSid is executed along with the four supplied arguments, which are pretty self-explanatory. Using this method its possible to copy a SID from one user to another user with a totally different SAM accountname, it could be any migrated or non-migrated user in the target domain. Now you probably understand the security implications of executing such command and why the API call is restricted to the domain controller.

ADMT Cross-Forest migration, the PowerShell way!

Introduction

Setup

Code

Recent Posts

Categories

Copyright

ADMT Cross-Forest migration, the PowerShell way!

Introduction

Setup

Code

Recent Posts

Categories

Tags

Copyright