Configure Microsoft Entra ID to Active Directory provisioning (preview)

This article guides you through configuring Microsoft Entra Cloud Sync to provision users and groups from Microsoft Entra ID to on-premises Active Directory Domain Services (AD DS). You create a configuration, choose which objects it provisions, set scoping filters and attribute value filtering, choose target containers, and customize attribute mappings.

Because the scoping choice determines whether attribute value filtering is available, scoping and attribute mapping are covered together here. When your configuration is complete, test and enable it, which is the same for all deployment options. The final section covers tasks you perform after provisioning runs, such as verifying results and moving a provisioned user.

If you're looking for provisioning from AD to Microsoft Entra ID, see Configure provisioning from Active Directory to Microsoft Entra ID.

Prerequisites

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

Choose a deployment option

All deployment options use the same configuration type, Microsoft Entra ID to AD sync. What differs is which object types you bring into scope:

For guidance on choosing an option and scale considerations, see Deployment options.

Create a configuration

To create a Microsoft Entra ID to AD provisioning 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. Select New configuration.

4. Select Microsoft Entra ID to AD sync.

5. On the configuration screen, select your domain. Select Create.

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

The configuration is split into the following five sections:

Sections 1 and 2 are covered in this article. For sections 3–5, see Test and enable provisioning to Active Directory.

Configure scoping filters

Scoping filters determine which objects are provisioned. The Scoping filters page provides a read-only view of the current configuration. Select Edit to open the wizard.

1. On the Get started screen, select Add scoping filters, or select Scoping filters on the left under Manage.

   

Scope by assignment

In Edit mode, use Scope by assignment to choose whether to sync all objects or selected objects. Attribute value filtering is available with either choice, but it's only appropriate with one of them:

• All users and groups — the next step is Scope by attribute. Add attribute value filters for every enabled object type (users, groups, or both), so that provisioning evaluates only the objects you need.

  

• Selected users and groups — the next step is Select users and groups, where you pick specific objects. Attribute value filtering is available in this mode but isn't recommended, because your selection already determines the scope. For more information, see Recommended configuration.

  

Attribute value filtering

Attribute-based scope filtering narrows which objects are provisioned by evaluating their attribute values. You configure it in the Scope by attribute step, on the Users tab, the Groups tab, or both.

Use it with All users and groups, where the filter is the only thing narrowing the scope: without one, every user and group in the tenant is evaluated on every cycle.

Don't use it with Selected users and groups, where your selection already narrows the scope, so a filter adds processing time without changing which objects are provisioned.

The provisioning configuration displays a warning in both cases, but doesn't block you. For more information, see Recommended configuration.

Default security clauses

A default security clause is applied to groups on top of clauses that you create, by using AND logic:

securityEnabled IS TRUE AND dirSyncEnabled IS FALSE AND mailEnabled IS FALSE

The default security clause is evaluated before the clauses that you configure.

Filtering logic

A single clause defines one condition for one attribute value. Clauses within a single scoping filter are evaluated with AND — all must be TRUE.

Multiple scoping filters are evaluated with OR — if any filter is TRUE, the object is provisioned.

Create an attribute-based filter

To create a filter that evaluates an attribute value:

1. Select Add Attribute scoping filter.
2. In Name, enter a name for the filter.
3. Under Attribute, select the attribute to evaluate.
4. Under Operator, select an operator (for example, EQUALS, NOT EQUALS, INCLUDES, REGEX MATCH).
5. Under Value, enter a value.
6. Select Save.

Supported operators

The following operators are supported:

Use regular expressions to filter

For more advanced filtering, use REGEX MATCH to search an attribute string for a substring. For example, consider groups that have the following descriptions:

• Contoso-Sales-US
• Contoso-Marketing-US
• Contoso-Operations-US
• Contoso-LT-US

To provision only the Sales, Marketing, and Operations groups to Active Directory, use the following regular expression:

REGEX MATCH description (?:^|\W)Sales|Marketing|Operations(?:$|\W)

The expression searches the group descriptions for the supplied words and provisions only matching groups.

For more information about writing expressions, see Reference for writing expressions for attribute mappings in Microsoft Entra ID.

Group membership to on-premises users

When group synchronization is enabled, you can optionally provision membership from cloud groups to on-premises users in the Configure group membership step. This setting is off by default.

Scope using directory extensions

For more advanced scoping and filtering, you can use directory extensions. For an overview, see Directory extensions for provisioning Microsoft Entra ID to Active Directory. For a step-by-step tutorial, see Using directory extensions when provisioning to Active Directory.

Configure the target container

Use the Target container to control the organizational unit (OU) where user and group objects are created in Active Directory. You can use a constant, direct, or expression mapping on the parentDistinguishedName attribute.

• Users — the default user target container automatically preserves the original OU of a user whose Source of Authority (SOA) is converted to the cloud (the default parentDistinguishedName expression uses onPremisesDistinguishedName). A cloud-native user is created in CN=Users,DC=<selected AD domain>, which you can override.

  

• Groups — the default group target container is CN=Users,DC=<selected AD domain>. To place groups in different OUs by attribute, use an expression with the Switch() function. The following example routes groups by display name:

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

  

  Display name is a weak routing key because it can change and isn't guaranteed to follow a consistent pattern. To route groups by a stable value, or to keep a group in the organizational unit it already occupies, use a directory extension instead. For more information, see Preserve the OU path.

Preserve the OU path

How the original OU is preserved depends on the object type:

• Users — preservation is built in. The default parentDistinguishedName mapping re-creates a SOA-converted user in their original OU, so no extra configuration is required.
• Groups — the original 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.

To set up the extension, see Preserve a group's organizational unit and name. Complete that setup before you convert the group to cloud-managed, then use the expressions that follow.

Preserve a group's original organizational unit

To map a SOA-converted group to its original OU, adapt the sample expression by replacing extension_<AppIdWithoutHyphens>_GroupDN with the extension attribute name in your tenant, and <Default ParentDistinguishedName> with the target OU to use when the extension value is empty:

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

Set Default value (if null) to the target OU to use when the GroupDN extension is empty.

Apply the expression to the target-container mapping:

1. Under Group target container, select Edit attribute mapping.
2. Change Mapping type to Expression.
3. Paste the expression into the expression box.
4. Select Apply, and then select Save.

Preserve a group's original common name

Use the same GroupDN extension to preserve the common name (CN). The expression extracts the CN from the stored distinguished name and uses the group display name and object ID as a fallback:

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

Apply the expression to the cn attribute mapping, then select Save schema.

When you finish configuring scoping filters and target containers, select Save. A message tells you what to configure next; select the link to continue.

Configure attribute mapping

Microsoft Entra Cloud Sync maps attributes between your Microsoft Entra ID users/groups and the AD objects. Because the AD schema isn't discoverable, each Microsoft Entra ID to AD configuration uses a fixed set of default mappings, which you can customize for your business needs.

Keep the same group name

By default, sAMAccountName isn't synchronized from Microsoft Entra ID to Active Directory, so a newly created group in AD receives a randomly generated sAMAccountName. To keep a consistent group name in AD, create a custom mapping to sAMAccountName. For example, use the following expression:

Join("_", [displayName], "Contoso_Group")

The expression combines the displayName value with Contoso_Group. For example, a group with the display name Marketing receives the sAMAccountName value Marketing_Contoso_Group.

Change other attribute mappings as needed

The following tables list the default user and group attribute mappings. You can change any of these mappings based on your requirements — modify an existing mapping, delete one, or add a new one. Some mappings are managed by the service and can't be edited.

To add a mapping:

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

2. Under Configuration, select your Microsoft Entra ID to AD configuration.

3. On the left, select Attribute mapping.

4. At the top, select the object type you're mapping: user, group, or contact.

5. Select Add attribute mapping, and then select the mapping type:

   • Direct — the target attribute takes the value of the source attribute.
   • Constant — the target attribute takes a fixed string that you specify.
   • Expression — the target attribute takes the result of an expression.
   • None — the target attribute is left unmodified.

6. Fill in the remaining options for the mapping type you chose, select when to apply the mapping, and then select Apply.

7. Select Save schema. Saving the schema triggers a synchronization.

For more information about writing expressions, see Reference for writing expressions for attribute mappings in Microsoft Entra ID.

User attribute mappings

Some user mappings (for example, adminDescription and msDS-ExternalDirectoryObjectId) are managed by the service, aren't visible in the UI, and must not be edited.

Group attribute mappings

Service-managed group mappings (adminDescription, msDS-ExternalDirectoryObjectId, ObjectGUID) aren't visible in the UI and must not be edited.

Directory extensions and custom attribute mapping

Microsoft Entra Cloud Sync lets you add directory extensions and map them to custom attributes. For more information, see Directory extensions for provisioning Microsoft Entra ID to Active Directory.

When your attribute mappings are complete, select Save schema. A message tells you what to configure next; select the link to continue.

Verify and manage provisioned objects

The following tasks apply after provisioning runs. Before you work through them, test and enable your configuration.

Verify provisioning

After you convert SOA and the object is in scope, run provisioning and confirm the result. These steps apply to all three deployment options: users only, groups only, or users and groups.

Groups:

• Confirm that the SOA-converted group is available in the provisioning configuration's group scope.

  

• When the job runs, the SOA-converted group is provisioned successfully. In Provisioning logs, search for the group and verify it was provisioned.

  

• Open the provisioning log details and confirm that the group was matched with an existing target group.

  

• On the Modified Properties tab, confirm that the target group's adminDescription and cn attributes are updated.

  

Verify in AD DS

In Active Directory Users and Computers, confirm that the original group is updated in its expected OU rather than a duplicate group being created.

Open the group properties and verify that the expected group name, scope, and attributes are present.

Cloud skips changes made in AD after SOA conversion

After you convert an object's SOA to the cloud, the cloud is the source of authority. If you edit an attribute of that object directly in AD DS (for example, rename a group), Cloud Sync skips the object during provisioning. In Provisioning logs, the object shows as Skipped, and the details explain that the object isn't synced because its SOA is converted to the cloud.

Move a provisioned user to a different organizational unit

After a user is provisioned, changing the Target container doesn't move them, and moving the object manually in AD DS is reverted on the next sync cycle. This behavior is expected, because the default parentDistinguishedName expression checks whether the user already has an on-premises location:

IIF(IsNullOrEmpty([onPremisesDistinguishedName]), "OU=Cloud_Users,DC=contoso,DC=com", Replace([onPremisesDistinguishedName], , "^.*?,(?=(?:CN|OU|DC)=)", , "", , ))

When onPremisesDistinguishedName is empty, the user is created in the constant target container you specified. When it's populated, the expression derives the OU from that attribute instead and ignores the constant. That precedence preserves the original OU of a user whose SOA is converted to the cloud. It's also why an already-provisioned user keeps returning to the OU recorded on their cloud object.

A cloud-native user has no onPremisesDistinguishedName until the first provisioning cycle, which writes the value back to the cloud object. For the full list of attributes written back, see On-premises attributes written back to Microsoft Entra ID.

To move a user, use the option that matches the scope of the change:

• All users that match a mapping rule — change the target container mapping so it points to the new OU, then select Save. Provisioning restarts and moves every user that matches the mapping rules on the next cycle.
• A single user — update that user's onPremisesDistinguishedName attribute in Microsoft Entra ID.
• A user that's moving to a different domain — remove the user from the current configuration's scope, then add the user to the scope of the configuration that targets the other domain.

The onPremisesDistinguishedName attribute is read-only unless you're assigned at least the Hybrid Identity Administrator role. The Microsoft Entra admin center doesn't expose on-premises attributes for editing, so use Microsoft Graph to update a single user:

PATCH https://microsoftgraph.chinacloudapi.cn/v1.0/users/{user-id}
Content-Type: application/json

{
    "onPremisesDistinguishedName": "CN=Cloud User,OU=Cloud_Users,DC=contoso,DC=com"
}

A 204 No Content response confirms the update. The user moves to the new OU on the next sync cycle.

To confirm the move, open the user's entry in Provisioning logs and select Modified Properties. The parentDistinguishedName row shows the old and new values.

Roll back a SOA-converted user or group

If you roll back a SOA-converted user or group so that AD DS owns it again, provisioning stops syncing changes for that object and removes it from the configuration scope. The on-premises object isn't deleted, and on-premises control resumes in the next sync cycle.

To confirm a rollback, check the Audit logs to verify that sync no longer happens for the object because it's managed on-premises, then confirm in AD DS that the object is still present.

Next step

Related content

• Deployment options for provisioning to Active Directory
• How provisioning to Active Directory works
• Transfer user Source of Authority (SOA) to the cloud
• Convert group Source of Authority (SOA) to the cloud
• What is Microsoft Entra Cloud Sync?