Office 365 – How to Configure UPN Filtering in AADSync

Azure Active Directory Sync Services (AADSync) was made “generally available” in September 2014. While the old DirSync tool is still available (and actually still linked to in the portal), AADSync should be what you’re looking to deploy at this point. As we make this transition, there is a learning curve in trying to understand how to accomplish certain tasks in AADSync that you may have previously done in DirSync.
One of the configuration settings I often implement with DirSync is the creation of a filter to only synchronize attributes with a properly formatted UPN.
Below is how this filter can be implemented using the AADSync PowerShell module.

What Are We Filtering?

Organizations commonly need to change their user’s UPNs to match their email addresses. In doing so, I find it convenient to filter out any user objects where the UPN has not been changed. So if we’re changing UPNs to “”, we don’t sync anyone with a UPN that is still “username@company.local”. In the example below, I’ll configure the filter for two UPN suffixes ( and
Although it’s outside of the scope of what we’re doing here, I also like to use one of the Exchange custom attributes to allow for ad-hoc filtering of miscellaneous accounts. The click-by-click process for that filter is defined in the “Inbound Filtering” section of the this article: AADSync: Configuring Filtering

Why Use PowerShell?

While you can use the click-by-click process, PowerShell provides the advantage that the process is scriptable and repeatable. As a consultant, it makes my documentation much easier than pages of screenshots. Unfortunately there seems to be almost no documentation on the AADSync PowerShell module at this time; so figuring out the syntax can be a bit of a struggle right now.

Quick Tip: While you’re still learning the syntax, the AADSync “Sync Rules Editor” allows you to “Export” a filter and provides the relevant PowerShell for that filter.

Creating The Filter

If the AADSync PowerShell module is not loaded for some reason, you’ll want to load it:

Import-Module ADSync

Next, we’ll want to determine the “Identifier” for our Active Directory connector:

Get-ADSyncConnector | FT Name, Identifier

The above environment has two Active Directory forests ( and configured in AADSync. We’ll setup the filter on the (bfd53bb7-8bde-4b13-8136-decb91e29d13) connector.
Now we create the filter for the connector:

New-ADSyncRule  `
-Name 'In from AD - User Filter by UPN' `
-Description 'Only sync users with and UPN suffixes' `
-Direction 'Inbound' `
-Precedence 50 `
-SourceObjectType 'user' `
-TargetObjectType 'person' `
-Connector 'bfd53bb7-8bde-4b13-8136-decb91e29d13' `
-LinkType 'Join' `
-SoftDeleteExpiryInterval 0 `
-ImmutableTag '' `
-OutVariable syncRule
Add-ADSyncAttributeFlowMapping  `
-SynchronizationRule $syncRule[0] `
-Source @('userPrincipalName') `
-Destination 'cloudFiltered' `
-FlowType 'Expression' `
-ValueMergeType 'Update' `
-Expression 'IIF((InStr(LCase([userPrincipalName]), "") = 0 && InStr(LCase([userPrincipalName]), "") = 0), True, NULL)' `
-OutVariable syncRule
Add-ADSyncRule -SynchronizationRule $syncRule[0]

With the above filter you’ll want to pay attention to the “precedence” and make sure it doesn’t conflict with any other filters you’ve created. Also important to note is that the “InStr” function appears to be case-sensitive thus the use of “LCase”. Additional documentation on the functions can be found at: Azure AD Sync Functions Reference.


  • DirSync is being replaced by AADSync and should be used in new deployments.
  • Understand what type of filtering is supported.
  • Documentation on the AADSync PowerShell module is a bit non-existent at the moment.
  • Using PowerShell to create your filters is repeatable and easier to document.
  • Be sure to check out the AADSync “best practices for changing the default configuration“.

Did you find this article helpful?
Leave a comment below or follow me on Twitter (@JoePalarchio) for additional posts and information on Office 365.
Looking to do some more reading on Office 365?
Catch up on my past articles here: Joe Palarchio.

Thoughts on “Office 365 – How to Configure UPN Filtering in AADSync”

  1. Hi
    is there away to filter on import?
    for example if i have two forests and for some reason one forest uses the same upn of the other(by mistake) and this creates duplicates.
    i dont want to ‘cloudfilter’ it cause that might affect the other ‘correct’ user.
    i want it(if its even possible) to skip importing if it finds the wrong upn coming from the agent in forestA.
    Thanks in advance
    love the blog

  2. Turbomcp-
    I imagine having duplicate UPNs is a larger issue (especially if you plan to use AD FS).
    Setting “cloudFiltered” controls what is synced to Azure AD and you are correct that the objects are still pulled into the metaverse.
    You would need to modify the existing Inbound provisioning rules to exclude the appropriate UPN suffixes or create new Inbound rules with precedence to exclude them. Checkout the Sync Rules Editor

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Joe Palarchio

More from this Author

Subscribe to the Weekly Blog Digest:

Sign Up
Follow Us