Edit

Share via

Migrate Microsoft Entra Connect Sync group writeback V2 to Microsoft Entra Cloud Sync

  • Article

Important

The public preview of Group Writeback v2 in Microsoft Entra Connect Sync will no longer be available after June 30, 2024. This feature will be discontinued on this date, and you will no longer be supported in Connect Sync to provision cloud security groups to Active Directory. The feature will continue to operate beyond the discontinuation date; however, it will no longer receive support after this date and may cease functioning at any time without notice.

We offer similar functionality in Microsoft Entra Cloud Sync called Group Provision to Active Directory that you can use instead of Group Writeback v2 for provisioning cloud security groups to Active Directory. We're working on enhancing this functionality in Cloud Sync along with other new features that we're developing in Cloud Sync.

Customers who use this preview feature in Connect Sync should switch their configuration from Connect Sync to Cloud Sync. You can choose to move all your hybrid sync to Cloud Sync (if it supports your needs). You can also run Cloud Sync side by side and move only cloud security group provisioning to Active Directory onto Cloud Sync.

For customers who provision Microsoft 365 groups to Active Directory, you can keep using Group Writeback v1 for this capability.

You can evaluate moving exclusively to Cloud Sync by using the user synchronization wizard.

The following document describes how to migrate group writeback using Microsoft Entra Connect Sync (formerly Azure AD Connect) to Microsoft Entra Cloud Sync. This scenario is only for customers who are currently using Microsoft Entra Connect group writeback v2. The process outlined in this document pertains only to cloud-created security groups that are written back with a universal scope.

Important

This scenario is only for customers who are currently using Microsoft Entra Connect group writeback v2

Also, this scenario is only supported for:

Mail-enabled groups and DLs written back to AD continue to work with Microsoft Entra Connect group writeback but will revert to the behavior of group writeback V1, so in this scenario, after disabling group writeback V2 all M365 groups will be written back to AD independently of the Writeback Enabled setting in Entra admin center. For more information, see the Provisioning to Active Directory with Microsoft Entra Cloud Sync FAQ.

Prerequisites

The following prerequisites are required to implement this scenario.

  • Microsoft Entra account with at least a Hybrid Identity Administrator role.
  • An on-premises AD account with at least domain administrator permissions - required to access the adminDescription attribute and copy it to the msDS-ExternalDirectoryObjectId attribute
  • On-premises Active Directory Domain Services environment with Windows Server 2016 operating system or later.
    • Required for AD Schema attribute - msDS-ExternalDirectoryObjectId
  • Provisioning agent with build version 1.1.1367.0 or later.
  • The provisioning agent must be able to communicate with the domain controller(s) on ports TCP/389 (LDAP) and TCP/3268 (Global Catalog).
    • Required for global catalog lookup to filter out invalid membership references

Naming convention for groups written back

By default, Microsoft Entra Connect Sync uses the following format when naming groups that are written back.

  • Default format: CN=Group_<guid>,OU=<container>,DC=<domain component>,DC=<domain component>

  • Example: CN=Group_3a5c3221-c465-48c0-95b8-e9305786a271,OU=WritebackContainer,DC=contoso,DC=com 

To make it easier to find groups being written back from Microsoft Entra ID to Active Directory, Microsoft Entra Connect Sync added an option to write back the group name by using the cloud display name. This is done by selecting the Writeback Group Distinguished Name with cloud Display Name during initial setup of group writeback v2. If this feature is enabled, Microsoft Entra Connect uses the following new format, instead of the default format:

  • New format: CN=<display name>_<last 12 digits of object ID>,OU=<container>,DC=<domain component>,DC=<domain component>

  • Example: CN=Sales_e9305786a271,OU=WritebackContainer,DC=contoso,DC=com 

Important

By default, Microsoft Entra cloud sync uses the new format, even if Writeback Group Distinguished Name with cloud Display Name feature is not enabled in Microsoft Entra Connect Sync. If you are using the default Microsoft Entra Connect Sync naming and then migrate the group so that it is managed by Microsoft Entra cloud sync, the group is renamed to the new format. Use the following section to allow Microsoft Entra cloud sync to use the default format from Microsoft Entra Connect.

Using the default format

If you want cloud sync to use the same default format as Microsoft Entra Connect Sync, you need to modify the attribute flow expression for the CN attribute. The two possible mappings are:

Expression Syntax Description
Cloud sync default expression using DisplayName Append(Append(Left(Trim([displayName]), 51), "_"), Mid([objectId], 25, 12)) The default expression used by Microsoft Entra cloud sync (that is, the new format)
Cloud sync new expression without using DisplayName Append("Group_", [objectId]) The new expression to use the default format from Microsoft Entra Connect Sync.

For more information, see Add an attribute mapping - Microsoft Entra ID to Active Directory

Step 1 - Copy adminDescription to msDS-ExternalDirectoryObjectID

To validate group membership references, Microsoft Entra Cloud Sync must query the Active Directory Global Catalog for msDS-ExternalDirectoryObjectID attribute. This is an indexed attribute which replicates across all Global Catalogs within the Active Directory Forest.

  1. In your on-premises environment, open ADSI Edit.

  2. Copy the value that it in the group's adminDescription attribute

    Screenshot of the adminDescription attribute.

  3. Paste in to the msDS-ExternalDirectoryObjectID attribute

    Screenshot of the msDS-ExternalDirectoryObjectID attribute.

The following PowerShell script can be used to help automate this step. This script takes all of the groups in the OU=Groups,DC=Contoso,DC=com container and copy the adminDescription attribute value to the msDS-ExternalDirectoryObjectID attribute value. Before using this script, update the variable $gwbOU with the DistinguishedName of your group writeback's target organizational unit (OU).

PowerShell 

# Provide the DistinguishedName of your Group Writeback target OU
$gwbOU = 'OU=Groups,DC=Contoso,DC=com'

# Get all groups written back to Active Directory
$properties = @('displayName', 'Samaccountname', 'adminDescription', 'msDS-ExternalDirectoryObjectID')
$groups = Get-ADGroup -Filter * -SearchBase $gwbOU -Properties $properties | 
    Where-Object {$_.adminDescription -ne $null} |
        Select-Object $properties

# Set msDS-ExternalDirectoryObjectID for all groups written back to Active Directory 
foreach ($group in $groups) {
    Set-ADGroup -Identity $group.Samaccountname -Add @{('msDS-ExternalDirectoryObjectID') = $group.adminDescription}
}

The following PowerShell script can be used to check the results of the script above or confirm that all groups have adminDescription value equal to msDS-ExternalDirectoryObjectID value.

PowerShell 

# Provide the DistinguishedName of your Group Writeback target OU
$gwbOU = 'OU=Groups,DC=Contoso,DC=com'


# Get all groups written back to Active Directory
$properties = @('displayName', 'Samaccountname', 'adminDescription', 'msDS-ExternalDirectoryObjectID')
$groups = Get-ADGroup -Filter * -SearchBase $gwbOU -Properties $properties | 
    Where-Object {$_.adminDescription -ne $null} |
        Select-Object $properties

$groups | select displayName, adminDescription, 'msDS-ExternalDirectoryObjectID', @{Name='Equal';Expression={$_.adminDescription -eq $_.'msDS-ExternalDirectoryObjectID'}}

Step 2 - Place the Microsoft Entra Connect Sync server in staging mode and disable the sync scheduler

  1. Start the Microsoft Entra Connect Sync wizard

  2. Click Configure

  3. Select Configure staging mode and click Next

  4. Enter Microsoft Entra credentials

  5. Place a check in the Enable staging mode box and click Next

    Screenshot of enabling staging mode.

  6. Click Configure

  7. Click Exit

    Screenshot of staging mode success.

  8. On your Microsoft Entra Connect server, open a PowerShell prompt as an administrator.

  9. Disable the sync scheduler:

    PowerShell 
    Set-ADSyncScheduler -SyncCycleEnabled $false

Step 3 - Create a custom group inbound rule

In the Microsoft Entra Connect Synchronization Rules editor, you need to create an inbound sync rule that filters out groups that have NULL for the mail attribute. The inbound sync rule is a join rule with a target attribute of cloudNoFlow. This rule tells Microsoft Entra Connect not to synchronize attributes for these groups. To create this sync rule, you can opt to use the user interface or create it via PowerShell with the provided script.

Create a custom group inbound rule in the user interface

  1. Launch the Synchronization Rules Editor from the start menu.

  2. Select Inbound from the drop-down list for Direction and select Add new rule.

  3. On the Description page, enter the following and select Next:

    • Name: Give the rule a meaningful name

    • Description: Add a meaningful description

    • Connected System: Choose the Microsoft Entra connector that you're writing the custom sync rule for

    • Connected System Object Type: Group

    • Metaverse Object Type: Group

    • Link Type: Join

    • Precedence: Provide a value that is unique in the system. Lower than 100 is recommended, so that it takes precedence over the default rules.

    • Tag: Leave empty

      Screenshot of inbound sync rule.

  4. On the Scoping filter page, Add the following and then select Next.

    Attribute Operator Value
    cloudMastered EQUAL true
    mail ISNULL

    Screenshot of scoping filter.

  5. On the Join rules page, select Next.

  6. On the Transformations page, add a Constant transformation: flow True to cloudNoFlow attribute.

    Screenshot of transformation.

  7. Select Add.

Create a custom group inbound rule in PowerShell

  1. On your Microsoft Entra Connect server, open a PowerShell prompt as an administrator.

  2. Import the module.

    PowerShell 
    Import-Module ADSync

  3. Provide a unique value for the sync rule precedence [0-99].

    PowerShell 
    [int] $inboundSyncRulePrecedence = 88

  4. Execute the following script:

    PowerShell 
     New-ADSyncRule  `
 -Name 'In from AAD - Group SOAinAAD coexistence with Cloud Sync' `
 -Identifier 'e4eae1c9-b9bc-4328-ade9-df871cdd3027' `
 -Description 'https://learn.microsoft.com/entra/identity/hybrid/cloud-sync/migrate-group-writeback' `
 -Direction 'Inbound' `
 -Precedence $inboundSyncRulePrecedence `
 -PrecedenceAfter '00000000-0000-0000-0000-000000000000' `
 -PrecedenceBefore '00000000-0000-0000-0000-000000000000' `
 -SourceObjectType 'group' `
 -TargetObjectType 'group' `
 -Connector 'b891884f-051e-4a83-95af-2544101c9083' `
 -LinkType 'Join' `
 -SoftDeleteExpiryInterval 0 `
 -ImmutableTag '' `
 -OutVariable syncRule

 Add-ADSyncAttributeFlowMapping  `
 -SynchronizationRule $syncRule[0] `
 -Source @('true') `
 -Destination 'cloudNoFlow' `
 -FlowType 'Constant' `
 -ValueMergeType 'Update' `
 -OutVariable syncRule

 New-Object  `
 -TypeName 'Microsoft.IdentityManagement.PowerShell.ObjectModel.ScopeCondition' `
 -ArgumentList 'cloudMastered','true','EQUAL' `
 -OutVariable condition0

 New-Object  `
 -TypeName 'Microsoft.IdentityManagement.PowerShell.ObjectModel.ScopeCondition' `
 -ArgumentList 'mail','','ISNULL' `
 -OutVariable condition1

 Add-ADSyncScopeConditionGroup  `
 -SynchronizationRule $syncRule[0] `
 -ScopeConditions @($condition0[0],$condition1[0]) `
 -OutVariable syncRule

 Add-ADSyncRule  `
 -SynchronizationRule $syncRule[0]

 Get-ADSyncRule  `
 -Identifier 'e4eae1c9-b9bc-4328-ade9-df871cdd3027'

Step 4 - Create a custom group outbound rule

You also need an outbound sync rule with a link type of JoinNoFlow and the scoping filter that has the cloudNoFlow attribute set to True. This rule tells Microsoft Entra Connect not to synchronize attributes for these groups. To create this sync rule, you can opt to use the user interface or create it via PowerShell with the provided script.

Create a custom group outbound rule in the user interface

  1. Select Outbound from the drop-down list for Direction and select Add rule.

  2. On the Description page, enter the following and select Next:

    • Name: Give the rule a meaningful name
    • Description: Add a meaningful description
    • Connected System: Choose the AD connector that you're writing the custom sync rule for
    • Connected System Object Type: Group
    • Metaverse Object Type: Group
    • Link Type: JoinNoFlow
    • Precedence: Provide a value that is unique in the system. Lower than 100 is recommended, so that it takes precedence over the default rules.
    • Tag: Leave empty

    Screenshot of outbound sync rule.

  3. On the Scoping filter page, choose cloudNoFlow equal True. Then select Next.

    Screenshot of outbound scoping filter.

  4. On the Join rules page, select Next.

  5. On the Transformations page, select Add.

Create a custom group inbound rule in PowerShell

  1. On your Microsoft Entra Connect server, open a PowerShell prompt as an administrator.

  2. Import the module.

    PowerShell 
    Import-Module ADSync

  3. Provide a unique value for the sync rule precedence [0-99].

    PowerShell 
    [int] $outboundSyncRulePrecedence = 89

  4. Get the Active Directory Connector for Group Writeback.

    PowerShell 
    $connectorAD = Get-ADSyncConnector -Name "Contoso.com"

  5. Execute the following script:

    PowerShell 
     New-ADSyncRule  `
 -Name 'Out to AD - Group SOAinAAD coexistence with Cloud Sync' `
 -Identifier '419fda18-75bb-4e23-b947-8b06e7246551' `
 -Description 'https://learn.microsoft.com/entra/identity/hybrid/cloud-sync/migrate-group-writeback' `
 -Direction 'Outbound' `
 -Precedence $outboundSyncRulePrecedence `
 -PrecedenceAfter '00000000-0000-0000-0000-000000000000' `
 -PrecedenceBefore '00000000-0000-0000-0000-000000000000' `
 -SourceObjectType 'group' `
 -TargetObjectType 'group' `
 -Connector $connectorAD.Identifier `
 -LinkType 'JoinNoFlow' `
 -SoftDeleteExpiryInterval 0 `
 -ImmutableTag '' `
 -OutVariable syncRule

 New-Object  `
 -TypeName 'Microsoft.IdentityManagement.PowerShell.ObjectModel.ScopeCondition' `
 -ArgumentList 'cloudNoFlow','true','EQUAL' `
 -OutVariable condition0

 Add-ADSyncScopeConditionGroup  `
 -SynchronizationRule $syncRule[0] `
 -ScopeConditions @($condition0[0]) `
 -OutVariable syncRule

 Add-ADSyncRule  `
 -SynchronizationRule $syncRule[0]

 Get-ADSyncRule  `
 -Identifier '419fda18-75bb-4e23-b947-8b06e7246551'

Step 5 - Use PowerShell to finish configuration

  1. On your Microsoft Entra Connect server, open a PowerShell prompt as an administrator.

  2. Import the ADSync module:

    PowerShell 
    Import-Module ADSync

  3. Run a full sync cycle:

    PowerShell 
    Start-ADSyncSyncCycle -PolicyType Initial

  4. Disable the group writeback feature for the tenant:

    Warning

    This operation is irreversible. After disabling group writeback V2, all Microsoft 365 groups will be written back to AD, independently of the Writeback Enabled setting in Entra admin center.

    PowerShell 
    Set-ADSyncAADCompanyFeature -GroupWritebackV2 $false

  5. Run a full sync cycle (yes again):

    PowerShell 
    Start-ADSyncSyncCycle -PolicyType Initial

  6. Re-enable the sync scheduler:

    PowerShell 
    Set-ADSyncScheduler -SyncCycleEnabled $true

    Screenshot of PowerShell execution.

Step 6 - Remove the Microsoft Entra Connect Sync server from staging mode

  1. Start the Microsoft Entra Connect Sync wizard
  2. Click Configure
  3. Select Configure staging mode and click Next
  4. Enter Microsoft Entra credentials
  5. Remove the check from the Enable staging mode box and click Next
  6. Click Configure
  7. Click Exit

Step 7 - Configure Microsoft Entra Cloud Sync

Now that the groups are removed from the synchronization scope of Microsoft Entra Connect Sync, you can set up and configure Microsoft Entra Cloud Sync to take over synchronization of the security groups. See Provision groups to Active Directory using Microsoft Entra Cloud Sync.

Next Steps