Configure object filters for directory synchronization
Object filtering is a directory synchronization feature that controls the synchronization of objects from on-premises Active Directory to Microsoft Entra ID. Filtering is an advanced subject, even for expert-level Microsoft 365 administrators. Despite that caveat, this unit introduces the subject to provide visibility into how organizations can tailor synchronization to meet their advanced business requirements.
The default configuration for directory synchronization takes all objects in all domains in the configured forests. In general, Microsoft recommends the default configuration for directory synchronization. Users using Microsoft 365 workloads, such as Exchange Online and Skype for Business, benefit from a complete Global Address List. This design enables them to send email and call everyone. With the default configuration, they have the same experience they would have with an on-premises implementation of Exchange Server or Skype for Business Server.
However, organizations must sometimes change the default directory synchronization configuration. When these situations occur, organizations can use filtering to customize the objects that it synchronizes. For example:
- You run a pilot for Azure or Microsoft 365 and you only want a subset of users in Microsoft Entra ID. In the pilot, you don't need a complete Global Address List to demonstrate the functionality.
- You have many service accounts and other nonpersonal accounts that you don't want in Microsoft Entra ID.
- For compliance reasons, you don't delete any user accounts on-premises. You only disable them. But in Microsoft Entra ID, you only want active accounts to be present.
You can apply the following filtering configuration types to the directory synchronization tool:
- Group-based. Filtering based on a single group. You must configure group-based filtering on initial installation by using the installation wizard. While this configuration type provides granular control, is easy to manage, and reduces synchronization traffic, it does have drawbacks. Its filtering options are limited, and a potential for errors if you don't properly set up groups. Also, group-based filtering can potentially slow down synchronization cycles, particularly if you synchronize a large number of objects.
- Domain-based. By using this option, you can select which domains synchronize to Microsoft Entra ID. You can also add and remove domains from the sync engine configuration when you make changes to your on-premises infrastructure after you install your directory synchronization tool.
- Organizational unit (OU)–based. By using this option, you can select which OUs synchronize to Microsoft Entra ID. This option is for all object types in selected OUs.
- Object attribute-based. By using this option, you can filter objects based on attribute values on the objects. You can also have different filters for different object types.
You can use multiple filtering options at the same time. For example, you can use OU-based filtering to only include objects in one OU. At the same time, you can use attribute-based filtering to filter the objects further. When you use multiple filtering methods, the filters use a logical "AND" between the filters.
Important
Group, domain, and OU filtering are available with both Microsoft Entra Connect Sync and Microsoft Entra Cloud Sync. However, object attribute filtering is only available in Microsoft Entra Connect Sync. It's not currently available in Microsoft Entra Cloud Sync.
Object filter configurations
In Microsoft Entra Connect Sync, you can enable filtering at any time. If you start with a default configuration of directory synchronization and then configure filtering, the sync process doesn't synchronize the objects that it filtered out to Microsoft Entra ID. This change results in the deletion of any previously synchronized objects in Microsoft Entra ID that were later filtered.
When installing or upgrading to a newer version of Microsoft Entra Connect Sync, the filtering configuration is retained. Before running the first synchronization cycle, it's always a best practice to verify the configuration wasn't inadvertently changed after upgrading to a newer version.
If an organization has more than one forest, then it must apply the filtering configuration to every forest (assuming that it wants the same configuration for all of them).
Deleting objects through object filtering
Because filtering can remove many objects at the same time, you want to ensure that your new filters are correct before you start exporting any changes to Microsoft Entra ID. After you complete the configuration steps, Microsoft recommends that you follow these verification steps before exporting your changes to Microsoft Entra ID.
To protect you from deleting many objects by accident, the feature "prevent accidental deletes" is enabled by default. If you delete many objects due to filtering (500 by default), you must follow the verification steps previously mentioned to allow the deleted objects to go through to Microsoft Entra ID.
User objects are sometimes inadvertently deleted in Microsoft Entra ID because of a filtering error. If this situation occurs, you can recreate the user objects in Microsoft Entra ID by removing your filtering configurations and then synchronizing your directories. This action restores the users from the recycle bin in Microsoft Entra ID.
However, you can't undelete other object types. For example, let's assume you accidentally deleted a security group that provided an ordered access control list for a resource. In this scenario, you can't recover the group and its access control lists.
Disable the scheduled task
Before you start making changes to filtering, you must first disable the scheduled task that triggers a synchronization cycle every 30 minutes. You must disable this task so you don't accidentally export changes before you verify the changes are correct.
To disable the built-in scheduler that triggers a synchronization cycle every 30 minutes, you must run the following PowerShell command:
Set-ADSyncScheduler -SyncCycleEnabled $False
You should then change the filtering configuration as required by your organization. Once you make the necessary changes, then run the following PowerShell command to enable the scheduler again:
Set-ADSyncScheduler -SyncCycleEnabled $True
Apply and verify changes
After you make your configuration changes and stop the scheduler task, you must apply the changes to the objects that are already present in the system. You might need to process the objects that aren't currently in the sync engine. For example:
- If you changed the configuration by using domain or organizational-unit filtering, you must do a Full import followed by a Delta synchronization.
- If you changed the configuration by using attribute filtering, you must do a Full synchronization.
All changes are staged for export after synchronization, before being exported to Microsoft Entra ID. This design enables you to verify that all the staged changes are correct. This verification process is completed by running a series of PowerShell commands that download the changes to a CSV file. You should examine the file in Microsoft Excel. All changes that are about to be exported are contained in this file.
After reviewing the CSV file, you should make any necessary changes to the data or configuration. At that point, you should repeat this process until the changes that are about to be exported are what you expect.
Once you're satisfied with the configuration changes, you should export them to Microsoft Entra ID. When the export finishes, you should enable the scheduler again.
Additional reading. For detailed steps on how to configure domain, OU, and attribute filtering, as well as how to apply and verify the configuration changes, see Microsoft Entra Connect Sync: Configure filtering.