Field Notes

UPN Suffix Filtering in Azure AD Connect

  • Billy Ford

Filtering what objects are synced to Azure AD is a common request and there are many instances where filtering by OU just doesn't cut it. One option is to filter users by their UPN suffix so that only users with the public FQDN as their UPN suffix are synced to Azure AD (e.g., would be synced while would not).


Filtering can be configured using either the GUI or PowerShell.

Using The Synchronization Rules Editor

  1. Open the Synchronization Rules Editor on the server where Azure AD Connect is installed.

    Open the Synchronization Rules Editor

    If you receive an error when trying to launch the rules editor, make sure that your user is a member of the ADSyncAdmins group (you must log out and back in for group changes to take effect).

  2. Click the Add new rule button on the View and manage your synchronization rules window.

    Click Add new rule

  3. Fill out the appropriate fields on the Description tab and click Next >.

    • Name: In from AD - User Filter by UPN
    • Connected System: Your on-premise AD connector (e.g.,
    • Connected System Object Type: user
    • Metaverse Object Type: person
    • Link Type: Join
    • Precedence: A number between 1-99. Make sure the value isn't being used by another rule.

    Fill out the values for the Description tab

  4. On the Scoping filter tab, click Add group, then Add clause, add a userPrincipalName attribute filter, and click Next >.

    • Attribute: userPrincipalName
    • Operator: ENDSWITH
    • Value: Your internal UPN suffix prefixed with @ (e.g., Users with this UPN suffix will NOT be synced with Microsoft 365.

    Add the userPrincipalName attribute filter

  5. Leave the Join rules tab blank and click Next >.

  6. On the Transformations tab, click Add transformation, add a cloudFiltered attribute transformation, and click Add.

    • FlowType: Constant
    • Target Attribute: cloudFiltered
    • Source: True
    • Merge Type: Update

    Add the cloudFiltered attribute transformation

You should now see your new rule listed on the View and manage your synchronization rules window. The next time that AD Connect Sync runs, users that have a UPN suffix matching the value you specified in Step 4 will be excluded from synchronization.

AD Connect Rule List

Using PowerShell

The following script will create an Azure AD Connect Sync rule to exclude any user with a UPN suffix that matches your on-premise Active Directory DNS root from synchronization. The script will attempt to determine the internal DNS root by looking at the name of the on-premise AD Sync Connector.

Import-Module ADSync

$Connector = (Get-ADSyncConnector | Where-Object {$_.Type -eq "AD"})
$UPNSuffix = "@$($Connector.Name)"

# Uncomment the next line to manually specify your UPN suffix.
#UPNSuffix = ""

# Make sure no other rule has the same precendence.
$Precedence = 10

New-ADSyncRule  `
-Name 'In from AD - User Filter by UPN' `
-Description 'Filter users based on UPN.' `
-Direction 'Inbound' `
-Precedence $Precedence `
-SourceObjectType 'user' `
-TargetObjectType 'person' `
-Connector $Connector.Identifier.Guid `
-LinkType 'Join' `
-SoftDeleteExpiryInterval 0 `
-ImmutableTag '' `
-OutVariable syncRule

Add-ADSyncAttributeFlowMapping  `
-SynchronizationRule $syncRule[0] `
-Source @('True') `
-Destination 'cloudFiltered' `
-FlowType 'Constant' `
-ValueMergeType 'Update' `
-OutVariable syncRule

New-Object  `
-TypeName 'Microsoft.IdentityManagement.PowerShell.ObjectModel.ScopeCondition' `
-ArgumentList 'userPrincipalName',$UPNSuffix,'ENDSWITH' `
-OutVariable condition0

Add-ADSyncScopeConditionGroup  `
-SynchronizationRule $syncRule[0] `
-ScopeConditions @($condition0[0]) `
-OutVariable syncRule

Add-ADSyncRule  `
-SynchronizationRule $syncRule[0]