Migrate groups from one forest to another for Microsoft Entra Connect
This article describes how to migrate groups from one forest to another so that the migrated group objects match the existing objects in the cloud.
- Microsoft Entra Connect version 1.5.18.0 or later
- Source anchor attribute set to
mS-DS-ConsistencyGuid
Starting in version 1.5.18.0, Microsoft Entra Connect supports the use of the mS-DS-ConsistencyGuid
attribute for groups. If you choose mS-DS-ConsistencyGuid
as the source anchor attribute and the value is populated in Active Directory, Microsoft Entra Connect uses the value of mS-DS-ConsistencyGuid
as the immutableId
. Otherwise, it falls back to using objectGUID
. But note that Microsoft Entra Connect doesn't write the value back to the mS-DS-ConsistencyGuid
attribute in Active Directory.
During a cross-forest move, when a group object is moving from one forest (say F1) to another forest (say F2), you need to copy either the mS-DS-ConsistencyGuid
value (if it's present) or the objectGUID
value from the object in forest F1 to the mS-DS-ConsistencyGuid
attribute of the object in F2.
Use the following scripts as a guide to learn how to migrate a single group from one forest to another. You can also use these scripts as a guide for the migration of multiple groups. The scripts use the forest name F1 for the source forest and F2 for the destination forest.
First, we get the objectGUID
and mS-DS-ConsistencyGuid
of the group object in forest F1. These attributes are exported to a CSV file.
<#
DESCRIPTION
============
This script will take DN of a group as input.
It then copies the objectGUID and mS-DS-ConsistencyGuid values along with other attributes of the given group to a CSV file.
This CSV file can then be used as input to the Export-Group script.
#>
Param(
[ValidateNotNullOrEmpty()]
[string]
$dn,
[ValidateNotNullOrEmpty()]
[string]
$outputCsv
)
$defaultProperties = @('samAccountName', 'distinguishedName', 'objectGUID', 'mS-DS-ConsistencyGuid')
$group = Get-ADGroup -Filter "DistinguishedName -eq '$dn'" -Properties $defaultProperties -ErrorAction Stop
$results = @()
if ($group -eq $null)
{
Write-Error "Group not found"
}
else
{
$objectGUIDValue = [GUID]$group.'objectGUID'
$mSDSConsistencyGuidValue = "N/A"
if ($group.'mS-DS-ConsistencyGuid' -ne $null)
{
$mSDSConsistencyGuidValue = [GUID]$group.'mS-DS-ConsistencyGuid'
}
$adgroup = New-Object -TypeName PSObject
$adgroup | Add-Member -MemberType NoteProperty -Name samAccountName -Value $($group.'samAccountName')
$adgroup | Add-Member -MemberType NoteProperty -Name distinguishedName -Value $($group.'distinguishedName')
$adgroup | Add-Member -MemberType NoteProperty -Name objectGUID -Value $($objectGUIDValue)
$adgroup | Add-Member -MemberType NoteProperty -Name mS-DS-ConsistencyGuid -Value $($mSDSConsistencyGuidValue)
$results += $adgroup
}
Write-Host "Exporting group to output file"
$results | Export-Csv "$outputCsv" -NoTypeInformation
Next, we use the generated output CSV file to stamp the mS-DS-ConsistencyGuid
attribute on the target object in forest F2:
<#
DESCRIPTION
============
This script will take DN of a group as input and the CSV file that was generated by the Import-Group script.
It copies either the objectGUID or the mS-DS-ConsistencyGuid value from the CSV file to the given object.
#>
Param(
[ValidateNotNullOrEmpty()]
[string]
$dn,
[ValidateNotNullOrEmpty()]
[string]
$inputCsv
)
$group = Get-ADGroup -Filter "DistinguishedName -eq '$dn'" -ErrorAction Stop
if ($group -eq $null)
{
Write-Error "Group not found"
}
$csvFile = Import-Csv -Path $inputCsv -ErrorAction Stop
$msDSConsistencyGuid = $csvFile.'mS-DS-ConsistencyGuid'
$objectGuid = [GUID] $csvFile.'objectGUID'
$targetGuid = $msDSConsistencyGuid
if ($msDSConsistencyGuid -eq "N/A")
{
$targetGuid = $objectGuid
}
Set-ADGroup -Identity $dn -Replace @{'mS-DS-ConsistencyGuid'=$targetGuid} -ErrorAction Stop
Learn more about integrating your on-premises identities with Microsoft Entra ID.