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 “first.last@company.com”, 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 (@company1.com and @company2.com).
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.

Creating The Filter

Revolutionize Your Business With Generative AI

From product design and software development to virtual agents, content creation, and reporting, GenAI is transforming business. Our AI experts help you unlock GenAI’s full potential and drive growth.

Let’s Get Started

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 (lab4.iwitl.net and lab5.iwitl.net) configured in AADSync. We’ll setup the filter on the lab4.iwitl.net (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 company1.com and company2.com 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]), "@company1.com") = 0 && InStr(LCase([userPrincipalName]), "@company2.com") = 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.

Summary

• 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.