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.

Prerequisites

• Microsoft Entra Connect version 1.5.18.0 or later
• Source anchor attribute set to mS-DS-ConsistencyGuid

Migrate groups

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

Next steps

Learn more about integrating your on-premises identities with Microsoft Entra ID.