Skip Ribbon Commands
Skip to main content

How do I filter objects on Azure Active Directory (AAD) Connect?

Last Update: 11/7/2016 2:16 PM

How do I filter objects on Azure Active Directory (AAD) Connect?

Answer:

This article explains the steps required to set a filter, using AAD Connect, that will clear the MailBoxGuid so that objects can be synchronized between environments.

  • Important:
    • If you are using AAD Sync, instead of AAD Connect, as your synchronization tool, the steps will be very similar to the ones detailed below.
    • If you are using DirSync, the steps will not be similar enough. In this case, we recommend that you upgrade to either AAD Sync or AAD Connect.

 

The following are example use cases where filtering objects from the synchronization could be advantageous:

  • Some users are already using Office 365 as a production platform. You would want to filter out all objects except those user objects that are already using Office 365. This way only those objects would be included in the synchronization.
  • You are planning a batch migration to Office 365. You would then want to filter out all objects except those user objects that are part of the batch, or any previous batch. This way only those objects would be included in the synchronization.
  • You do not have the required Exchange Online licenses to assign to all the users. This would be useful so that you can then assign licenses to all synchronized accounts.
  • Enabling the Exchange Online license will cause an error.
  • Important: 
    • In all of the scenarios above, you would still want to synchronize all the objects using AAD Connect in order to have a complete Global Address List (GAL) on Office 365. This will allow users to send email to the on-premises users, after mail routing has been enabled on Office 365.
    • For directions on how to enable mail routing on Office 365, refer to KB005137

 

Summary explanation:

The filter, based on a specific attribute, will clear the MailboxGuid for the synchronized objects, and thus avoid any service disruption for those users already using Office 365.

 

Follow the steps below to guide you through the process of creating a new rule on AAD Connect, and filtering objects based on one extensionAttribute (called customAttribute on Exchange, and extensionAttribute on Active Directory Schema).

  • Notes:
    • Before you start, it is very important that you are familiar with AAD Connect and PowerShell syntax.
    • The screen shots are from Microsoft Azure Active Directory Connect, version 1.1.189.0. If you are using other versions, the screen shots may be different.

 

Pre-Migration Tasks

  1. Choose one extensionAttribute that can be populated with a customized tag. In our example, we will use extensionAttribute 5 and the tag "BT - User Migrated".
  2. Populate the extensionAttribute of the users that you are planning to assign an Exchange Online license to, with the chosen Tag.

This step can be executed in any of the following ways:

a. Using Exchange Management Console (EMC):
KB005809_Change_ExtensionAttribute.jpg

b. Using Exchange Management Shell (EMS) by executing the following script:

Set-Mailbox <user_UPN> -customAttribute5 "BT - User Migrated"

c. Bulk edit using EMS:

    • Create a users.CSV file with the UPN of the users that you what to enable the Exchange Online. It should look like this:
    • ​UPN
      ​UserA@mydomain.com
      ​​​​UserB@mydomain.com
      ​​​UserC@mydomain.com
      ​...
      ​​​UserZ@mydomain.com

d. Execute the following PowerShell script:

      $UserList = Import-CSV '<Path Name>\Users.csv'
      foreach( $user in $UserList )
      {
           Set-Mailbox $user.UPN -customAttribute5 "BT - User Migrated"
      }

3. Search and select the rule.

  • In Windows, search for the Synchronization Rules Editor, and open it. Note: The default location is C:\Program Files\Microsoft Azure AD Sync\UIShell\SyncRulesEditor.exe.
  • Search and select the rule with the name In from AD - User Exchange and click Export. Also, take note of the lowest precedence number (in this example it is 80). You will need it below.
    KB005809_Export_Usr_Exch_Rule.jpg

A Notepad (or other text editor defined as a default) will open, with a randon name and a .tmp extension.
Important: Save the file and keep it in a safe location. The file will allow you to recreate the default rule without any customization if something goes wrong.

KB005809_Temp_Notepad_File.jpg

4. After you save the file, create a duplicate, change the extension to .ps1, and edit the file.
KB005809_Notepad_Dir.jpg

On the .ps1 file:

  • Change the Name to identify that it is a customized rule.
  • Change Precedence to a number lower than the number found in Step 4 (in our example, it was 80).
  • Delete the lines identifier and ImmutableTag.

    After the above modifications have been made, the file will look like this:
  • KB005809_Changes_to_Rules.jpeg
     

5. Open a PowerShell with elevated privileges, navigate to the folder where you store the .ps1 file, and execute the script. After it finishes, scroll up and validate that no error appears. 
KB005809_Execute_ps1.jpg

6. Confirm that a new line was created in the Synchronization Rules Editor. Note: There is no refresh, so you will need to close and reopen it to confirm that a new line was created:
KB005809_New_AAD_Connect_Rule.jpeg

7. Now, edit the rules.

    • Start with the customized synchronization rule.
    • Highlight the rule and click Edit.
      KB005809_Edit_Customized_Rule.jpg
    • Select Scoping filter and click the Add clause button. This will create a new line. Choose the extensionAttribute used before. Under Operator, select EQUAL and populate the Value with "BT - User Migrated".  Then select Transformations.
      KB005809_Change_Scoping_Filter.jpg
    • Scroll down until you find the msExchMailboxGuid attribute, and change it to the following:

      Flow Type: Direct
      Target Attribute: msExchMailboxGuid
      Source: NULL

      Merge Type: Update
      KB005809_Change_Transformation.jpg

    • Click Save. The window will close automatically.
    • Now, edit the original Synchronization rule. On the Scoping filter, click Add clause, and add the extensionAttribute, NOTEQUAL, and BT - User Migrated.
      • It will look like this:
        KB005809_Change_Scoping_Filter_1.jpg

8. Perform a FULL Sync.  Note: A DeltaSync will not make the required changes. 

An easy way to perform this step is to open a PowerShell on the computer where AAD Connect is running, and execute the following script:

​Import-Module ADSync
Start-ADSyncSyncCycle -PolicyType Initial

9. Enable the Exchange Online license for the required users.

10. Using EMC, AD, or using PowerShell, remove the tag BT - User Migrated from the users. If you use PowerShell, replace BT -User Migrated with $null. 

11. Perform a DeltaSync.

An easy way to perform this step is to open a PowerShell on the computer where AAD Connect is running, and execute the following script:

​Import-Module ADSync
Start-ADSyncSyncCycle -PolicyType Delta

 

Post-migration tasks

 

After you enable all the required Exchange licenses in Office 365, you can revert all the changes made on AAD Connect:

  1. Highlight and delete the customized synchronization rule:
    KB005809_Delete_Synchronization_Rule.jpg
    KB005809_Confirm_Delete_Synchronization_Rule.jpg
  2. Remove the clause from the Scoping filter of the original rule:
    KB005809_Deleting_Clause.jpg

    It should look like this:
    KB005809_Normal_Scoping_Filter.jpg