Preserve a group's organizational unit and name when you convert Source of Authority (preview)

When you convert a group's Source of Authority (SOA) to Microsoft Entra ID, the group's original organizational unit (OU) isn't detected automatically. Use the GroupDN directory extension to capture the group's distinguished name (DN) before you convert its SOA, then reference that extension in the OU and common name (CN) mapping expressions.

This article covers the one-time setup. Complete it before you convert the group to cloud-managed. For the mapping expressions that consume the extension, see Preserve a group's original organizational unit.

Prerequisites

Complete the steps in Prerequisites for provisioning from Microsoft Entra ID to Active Directory before you continue.

Set up the GroupDN extension

Complete the following tasks in order, before you convert the group to cloud-managed.

Change the group scope to Universal

To change the group scope to Universal:

  1. Open Active Directory Administrative Center.
  2. Select and hold (or right-click) the group, and then select Properties.
  3. In the Group section, select Universal as the group scope.
  4. Select Save.

Create the extension

Cloud Sync only supports extensions created on the CloudSyncCustomExtensionsApp application. Create this application once per tenant if it doesn't already exist.

  1. Open an elevated PowerShell window and run the following commands to install modules and connect:

    Install-Module Microsoft.Graph -Scope CurrentUser -Force
Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "Application.ReadWrite.All","Directory.ReadWrite.All","Directory.AccessAsUser.All"

  2. Check if the application exists. If it doesn't, create it, and ensure a service principal is present:

    $tenantId = (Get-MgOrganization).Id
$app = Get-MgApplication -Filter "identifierUris/any(uri:uri eq 'API://$tenantId/CloudSyncCustomExtensionsApp')"
if (-not $app) {
  $app = New-MgApplication -DisplayName "CloudSyncCustomExtensionsApp" -IdentifierUris "API://$tenantId/CloudSyncCustomExtensionsApp"
}
$app

$sp = Get-MgServicePrincipal -Filter "AppId eq '$($app.AppId)'"
if (-not $sp) {
  $sp = New-MgServicePrincipal -AppId $app.AppId
}
$sp

  3. Add a directory extension property named GroupDN — a string attribute on group objects:

    New-MgApplicationExtensionProperty `
  -ApplicationId $app.Id `
  -Name "GroupDN" `
  -DataType "String" `
  -TargetObjects Group

For more information, see Directory extensions for provisioning Microsoft Entra ID to Active Directory.

Map distinguishedName to the GroupDN extension

Tell Cloud Sync to populate the extension with the group's distinguished name (DN) from Active Directory. This captures the group's full DN (CN + OU path) in Microsoft Entra ID.

  1. Open Entra ID > Entra Connect > Cloud Sync.
  2. Select your AD to Microsoft Entra ID configuration.
  3. Go to Attribute mappings and set Object type to Group.
  4. Add a new attribute mapping:
    • Mapping type: Direct
    • Source attribute: distinguishedName
    • Target attribute: extension_<appIdWithoutHyphens>_GroupDN
  5. Save the schema to trigger a sync.

Verify the mapping and convert SOA

After a sync runs, verify that the extension property is populated with the DN by using Microsoft Graph PowerShell:

$groupDisplayName = 'My Security Group'
$clientId = $app.AppId
$propName = "extension_{0}_GroupDN" -f ($clientId -replace "-","")
$grp = Get-MgGroup -Filter "displayName eq '$groupDisplayName'" -ConsistencyLevel eventual
Get-MgGroup -GroupId $grp.Id -Property "id,displayName,$propName" |
  Select-Object id, displayName, @{n=$propName; e={$_."$propName"}}

Once the DN is stored in the extension, convert the group's Source of Authority to Microsoft Entra ID. The group becomes cloud-managed while its original DN is preserved in the extension for use in the OU and CN mapping expressions that follow.

Next step

Test and enable provisioning

Related content

  • Last updated on