Tutorial - Provision groups to Active Directory Domain Services by using Microsoft Entra Cloud Sync

This tutorial walks you through how to configure Cloud Sync to sync groups to on-premises Active Directory Domain Services (AD DS).

Provision Microsoft Entra ID to Active Directory Domain Services - Prerequisites

The following prerequisites are required to implement provisioning groups to Active Directory Domain Services (AD DS).

License requirements

Using this feature requires Microsoft Entra ID P1 licenses. To find the right license for your requirements, see Compare generally available features of Microsoft Entra ID.

General requirements

• Microsoft Entra account with at least a Hybrid Identity Administrator role.
• On-premises AD DS schema with the msDS-ExternalDirectoryObjectId attribute, which is available in Windows Server 2016 and later.
• Provisioning agent with build version 1.1.3730.0 or later.

$credential = Get-Credential  

Set-AAD DSCloudSyncPermissions -PermissionType UserGroupCreateDelete -TargetDomain "FQDN of domain" -EACredential $credential

• The provisioning agent must be installed on a server that runs Windows Server 2022, Windows Server 2019, or Windows Server 2016.
• The provisioning agent must be able to communicate with one or more domain controllers on ports TCP/389 (LDAP) and TCP/3268 (Global Catalog).
  • Required for Global Catalog lookup to filter out invalid membership references
• Microsoft Entra Connect Sync with build version 2.22.8.0
  • Required to support on-premises user membership synchronized using Microsoft Entra Connect Sync
  • Required to synchronize AD DS:user:objectGUID to AAD DS:user:onPremisesObjectIdentifier

Scale limits for Provisioning groups to Active Directory

Group Provision to Active Directory feature's performance is impacted by the size of the tenant and the number of groups and memberships that are in scope for provisioning to Active Directory. This section provides guidance on how to determine if GPAD supports your scale requirement and how to pick the right group scoping mode to achieve quicker initial and delta sync cycles.

What is not supported?

• Groups that are larger than 50K members aren't supported.
• The use of "All security groups" scoping without applying attribute scope filtering is not supported.

Scale limits

What to do if you exceed limits

Exceeding the recommended limits will slow initial and delta sync, possibly causing sync errors. If this happens, follow these steps:

Too many groups or group members in ‘Selected security groups’ scoping mode:

Reduce the number of in-scope groups (target higher value groups), or split provisioning into multiple, distinct jobs with disjoint scopes.

Too many groups or group members in ‘All security groups’ scoping mode:

Use Selected security groups scoping mode as recommended.

Some group exceeds 50K members:

Split membership across multiple groups or adopt staged groups (for example, by region or business unit) to keep each group under the cap.

Expanded group selection via API

If you need to select more than 999 groups, you must use the Grant an appRoleAssignment for a service principal API call.

An example of the API calls is as follows:

POST https://graph.microsoft.com/v1.0/servicePrincipals/{servicePrincipalID}/appRoleAssignedTo
Content-Type: application/json

{
  "principalId": "",
  "resourceId": "",
  "appRoleId": ""
}

where:

• principalId: Group object ID.
• resourceId: Job's service principal ID.
• appRoleId: Identifier of app role exposed by the resource service principal.

The following table is a list of App Role IDs for Clouds:

More information

Here are more points to consider when you provision groups to AD DS.

• Groups provisioned to AD DS using Cloud Sync can only contain on-premises synchronized users or other cloud-created security groups.
• These users must have the onPremisesObjectIdentifier attribute set on their account.
• The onPremisesObjectIdentifier must match a corresponding objectGUID in the target AD DS environment.
• An on-premises user objectGUID attribute can be synchronized to a cloud user onPremisesObjectIdentifier attribute by using either sync client.
• Only global Microsoft Entra ID tenants can provision from Microsoft Entra ID to AD DS. Tenants such as B2C aren't supported.
• The group provisioning job is scheduled to run every 20 minutes.

Group and User SOA Scenarios

Assumptions

This tutorial assumes:

• You have an AD DS on-premises environment

• You have cloud sync setup to synchronize users to Microsoft Entra ID.

• You have two users that are synchronized: Britta Simon and Lola Jacobson. These users exist on-premises and in Microsoft Entra ID.

• An organizational unit (OU) is created in AD DS for each of the following departments:

  Display name	Distinguished name
  Groups	OU=Marketing,DC=contoso,DC=com
  Sales	OU=Sales,DC=contoso,DC=com
  Marketing	OU=Groups,DC=contoso,DC=com

Add users to cloud-native or Source of Authority (SOA) converted security groups

To add synced users, follow these steps:

1. Sign in to the Microsoft Entra admin center as at least a Hybrid Identity Administrator.
2. Browse to Entra ID > Groups > All groups.
3. At the top, in the search box, enter Sales.
4. Select the new Sales group.
5. On the left, select Members.
6. At the top, select Add members.
7. At the top, in the search box, enter Britta Simon.
8. Put a check next to Britta Simon and select Select.
9. It should successfully add the user to the group.
10. On the far left, select All groups. Repeat this process by using the Sales group, and add Lola Jacobson to that group.

Prepare SOA converted groups for provisioning to their original organizational unit (OU) path

Complete these steps to prepare groups that you plan to convert to be cloud-managed for provisioning from Microsoft Entra ID back to their original OU path in Active Directory Domain Services (AD DS) on-premises:

1. Change the AD DS group scope to Universal.
2. Create a special application.
3. Create the directory extension property for groups.

Change the group scope for the AD DS groups to Universal

1. Open Active Directory Administrative Center.
2. Right-click a group, click Properties.
3. In the Group section, select Universal as the group scope.
4. Click Save.

Create the extension

Cloud Sync only supports extensions created on a special application called CloudSyncCustomExtensionsApp. If the app doesn't exist in your tenant, you must create it. This step is performed once per tenant.

For more information about how to create the extension, see Cloud sync directory extensions and custom attribute mapping.

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

GET /v1.0/groups/{id}?$select=displayName,extension_<appIdNoHyphens>_GroupDN

Configure provisioning

To configure provisioning, follow these steps:

1. Sign in to the Microsoft Entra admin center as at least a Hybrid Identity Administrator.

2. Browse to Entra ID > Entra Connect > Cloud sync.

   

3. Select New configuration.

4. Select Microsoft Entra ID to AD sync.

   

5. On the configuration screen, select your domain and whether to enable password hash sync. Select Create.

   

6. The Get started screen opens. From here, you can continue configuring cloud sync.

7. On the left, select Scoping filters.

8. For Groups scope, select Selected security groups.

   

9. There are two possible approaches to set the OU:

   • You can use custom expressions ensure the group is re-created with the same OU. Use the following expression for ParentDistinguishedName value:

     IIF(
         IsPresent([extension_<AppIdWithoutHyphens>_GroupDistinguishedName]),
         Replace(
             Mid(
                 Mid(
                     Replace([extension_<AppIdWithoutHyphens> _GroupDistinguishedName], "\,", , , "\2C", , ),
                     Instr(Replace([extension_<AppIdWithoutHyphens> _GroupDistinguishedName], "\,", , , "\2C", , ), ",", , ),
                     9999
                 ),
                 2,
                 9999
             ),
             "\2C", , , ",", ,
         ),
     "<Existing ParentDistinguishedName>",
     )
     

     This expression:

     • Uses a default OU if the extension is empty.
     • Otherwise strips the CN portion and preserves the parentDN path, again handling escaped commas.

     This changes causes a full sync and doesn't affect existing groups. Test setting the GroupDN attribute for an existing group using Microsoft Graph and ensure that it moves back to original OU.

   • If you don't want to preserve the original OU path and CN information from on-premises, under Target container select Edit attribute mapping.

     1. Change Mapping type to Expression.

     2. In the expression box, enter:

        Switch([displayName],"OU=Groups,DC=contoso,DC=com","Marketing","OU=Marketing,DC=contoso,DC=com","Sales","OU=Sales,DC=contoso,DC=com")

     3. Change the Default value to be OU=Groups,DC=contoso,DC=com.

        

     4. Select Apply. The target container changes depending on the group displayName attribute.

10. You can use custom expressions to ensure the group is re-created with the same CN. Use the following expression for CN value:

    IIF(
        IsPresent([extension_<AppIdWithoutHyphens>_GroupDistinguishedName]),
        Replace(
            Replace(
                Replace(
                    Word(Replace([extension_<AppIdWithoutHyphens> _GroupDistinguishedName], "\,", , , "\2C", , ), 1, ","),
                    "CN=", , , "", ,
                ),
                "cn=", , , "", ,
            ),
            "\2C", , , ",", ,
        ),
    Append(Append(Left(Trim([displayName]), 51), "_"), Mid([objectId], 25, 12)),
    )
    

    This expression:

    • If the extension is empty, generates a fallback CN from DisplayName + ObjectId.
    • Otherwise extracts the CN, handling escaped commas by temporarily replacing them with hex values.

11. Select Save.

12. On the left, select Overview.

13. At the top, select Review and enable.

14. On the right, select Enable configuration.

Test configuration

1. Sign in to the Microsoft Entra admin center as at least a Hybrid Identity Administrator.

2. Browse to Entra ID > Entra Connect > Cloud sync.

   

3. Under Configuration, select your configuration.

4. On the left, select Provision on demand.

5. Enter Sales in the Selected group box.

6. From the Selected users section, select some users to test.

   

7. Select Provision.

8. You should see the group provisioned.

Verify in AD DS

Follow these steps to make sure the group is provisioned to AD DS:

1. Sign in to your on-premises environment.

2. Launch Active Directory Users and Computers.

3. Verify the new group is provisioned.

   

Group provision to AD DS behavior for SOA converted objects

When you convert the Source of Authority (SOA) to cloud for an on-premises group, that group becomes eligible for group provisioning to AD DS.

For example, in the following diagram, the SOA or SOATestGroup1 is converted to the cloud. As a result, it becomes available for the job scope in group provisioning to AD DS.

• When a job runs, SOATestGroup1 is provisioned successfully.

• In the Provisioning logs, you can search for SOATestGroup1 and verify that the group was provisioned.

  

• The details show that SOATestGroup1 was matched with an existing target group.

  

• You can also confirm that the adminDescription and cn of the target group are updated.

  

• When you look at AD DS, you can find that the original group is updated.

  

  

Cloud skips provisioning converted SOA objects to Microsoft Entra ID

If you try to edit an attribute of a group in AD DS after you convert SOA to the cloud, Cloud Sync skips the object during provisioning.

Let's say we have a group SOAGroup3, and we update its group name to SOA Group3.1.

In the Provisioning Logs, you can see that SOAGroup3 was skipped.

The details explain that the object isn't synced because its SOA is converted to the cloud.

Nested groups and membership references handling

The following table explains how the provisioning handles membership references after you convert SOA in different use cases.

Group provision to AD DS behavior after you roll back SOA converted groups

If you have SOA converted groups in scope and you roll back the SOA converted group to make it owned by AD DS, group provisioning to AD DS stops syncing the changes, but it doesn't delete the on-premises group. It also removes the group from configuration scope. On-premises control of the group resumes in the next sync cycle.

• You can verify in the Audit Logs that sync doesn't happen for this object because it's managed on-premises.

  

  You can also check in AD DS that the group is still intact and not deleted.

  

Next steps

• Group writeback with Microsoft Entra Cloud Sync
• Govern on-premises AD DS based apps (Kerberos) using Microsoft Entra ID Governance
• Migrate Microsoft Entra Connect Sync group writeback V2 to Microsoft Entra Cloud Sync