Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
This tutorial walks you through how to configure Cloud Sync to sync groups to on-premises Active Directory Domain Services (AD DS).
Important
We recommend using Selected security groups as the default scoping filter when you configure group provisioning to AD DS. This default scoping filter helps prevent any performance issues when you provision groups.
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 environment with Windows Server 2016 operating system or later.
- Required for AD DS schema attribute - msDS-ExternalDirectoryObjectId
- Provisioning agent with build version 1.1.3730.0 or later.
Note
The permissions to the service account are assigned during clean install only. If you're upgrading from the previous version, then permissions need to be assigned manually by using PowerShell:
$credential = Get-Credential
Set-AAD DSCloudSyncPermissions -PermissionType UserGroupCreateDelete -TargetDomain "FQDN of domain" -EACredential $credential
If the permissions are set manually, you need to assign Read, Write, Create, and Delete all properties for all descendant Groups and User objects.
These permissions aren't applied to AdminSDHolder objects by default. For more information, see Microsoft Entra provisioning agent gMSA PowerShell cmdlets.
- 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:objectGUIDtoAAD DS:user:onPremisesObjectIdentifier
Supported groups and scale limits
The following is supported:
- Only cloud-native or SOA converted (from AD DS to Microsoft Entra ID) security groups are supported.
- These groups can have assigned or dynamic membership groups.
- These groups can only contain on-premises synchronized users or additional cloud created security groups.
- The on-premises user accounts that are synchronized and are members of this cloud created security group, can be from the same domain or cross-domain, but they all must be from the same forest.
- These groups are written back with the group scope of Universal. Your on-premises environment must support the Universal group scope.
- Groups that are larger than 50,000 members aren't supported.
- Tenants that have more than 150,000 objects aren't supported. Meaning, if a tenant has any combination of users and groups that exceeds 150K objects, the tenant isn't supported.
- Each direct child nested group counts as one member in the referencing group
- Reconciliation of groups between Microsoft Entra ID and AD DS isn't supported if the group is manually updated in AD DS.
Additional information
Here's 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.
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:
Note
Only synced user member references are provisioned to AD DS.
- Sign in to the Microsoft Entra admin center as at least a Hybrid Identity Administrator.
- Browse to Entra ID > Groups > All groups.
- At the top, in the search box, enter Sales.
- Select the new Sales group.
- On the left, select Members.
- At the top, select Add members.
- At the top, in the search box, enter Britta Simon.
- Put a check next to Britta Simon and select Select.
- It should successfully add the user to the group.
- On the far left, select All groups. Repeat this process by using the Sales group, and add Lola Jacobson to that group.
Configure provisioning
To configure provisioning, follow these steps:
Sign in to the Microsoft Entra admin center as at least a hybrid identity administrator.
Browse to Entra ID > Entra Connect > Cloud sync.
Select New configuration.
Select Microsoft Entra ID to AD sync.
On the configuration screen, select your domain and whether to enable password hash sync. Select Create.
The Get started screen opens. From here, you can continue configuring cloud sync.
On the left, select Scoping filters.
For Groups scope, select Selected security groups.
There are two possible approaches to set the OU:
- You can preserve the original OU path from on-premises. With this approach, you need to set the attribute mapping based on an extensionAttribute value. For more information, see Preserve the original OU path.
Or
- Under Target container select Edit attribute mapping.
Change Mapping type to Expression.
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")Change the Default value to be
OU=Groups,DC=contoso,DC=com.
Select Apply - This changes the target container depending on the group displayName attribute.
Select Save.
On the left, select Overview.
At the top, select Review and enable.
On the right, select Enable configuration.
Test configuration
Note
When you run on-demand provisioning, members aren't automatically provisioned. You need to select the members you want to test, and the limit is five members.
Sign in to the Microsoft Entra admin center as at least a hybrid identity administrator.
Browse to Entra ID > Entra Connect > Cloud sync.
Under Configuration, select your configuration.
On the left, select Provision on demand.
Enter Sales in the Selected group box.
From the Selected users section, select some users to test.
Select Provision.
You should see the group provisioned.
Verify in AD DS
Follow these steps to make sure the group is provisioned to AD DS:
Sign in to your on-premises environment.
Launch Active Directory Users and Computers.
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.
| Use case | Parent group type | Member group type | Job | How sync works |
|---|---|---|---|---|
| A Microsoft Entra parent security group has only Microsoft Entra members. | Microsoft Entra security group | Microsoft Entra security group | AAD2ADGroupProvisioning (group provisioning to AD DS) | The job provisions the parent group with all its member references (member groups). |
| A Microsoft Entra parent security group has some members that are synced groups. | Microsoft Entra security group | AD DS security groups (synced groups) | AAD2ADGroupProvisioning (group provisioning to AD DS) | The job provisions the parent group, but all the member references (member Groups) that are AD DS groups aren't provisioned. |
| A Microsoft Entra parent security group has some members that are synced groups whose SOA is converted to cloud. | Microsoft Entra security group | AD DS security groups whose SOA is converted to cloud. | AAD2ADGroupProvisioning (group provisioning to AD DS) | The job provisions the parent group with all its member references (member groups). |
| You convert the SOA of a synced group (parent) that has cloud-owned groups as members. | AD DS security groups with SOA converted to cloud | Microsoft Entra security group | AAD2ADGroupProvisioning (group provisioning to AD DS) | The job provisions the parent group with all its member references (member groups). |
| You convert the SOA of a synced group (parent) that has other synced groups as members. | AD DS security groups with SOA converted to cloud | AD DS security groups (synced groups) | AAD2ADGroupProvisioning (group provisioning to AD DS) | The job provisions the parent group, but all the member references (member Groups) that are AD DS security groups aren't provisioned. |
| You convert the SOA of a synced group (parent) whose members are other synced groups that have SOA converted to cloud. | AD DS security groups with SOA converted to cloud | AD DS security groups with SOA converted to cloud | AAD2ADGroupProvisioning (group provisioning to AD DS) | The job provisions the parent group with all its member references (member groups). |
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.
