Azure AD

Azure AD Connect – Synchronizing MAIL field with UserPrincipalName in Azure

Azure AD Connect is an application responsible for synchronizing Active Directory with Azure AD allowing for a natural population of users, groups, and devices in Office 365. While for most companies standard setup is very easy and most of the time touch-free, there are companies which require greater customization. During installation of AD Connector, you choose what should be used for Azure AD Username from your AD. UserPrincipalName field is an obvious choice for this and also proposed by default for that purpose. This field is utilized further by your users to log in to your Exchange, SharePoint, Teams and so on.

As seen on the screen above you can pick that field during installation of AD Connector. If at that point you decide you want to change that field you can do so. But what if you decide to change this setting after you've already had Azure AD Connect up and ready? It's not that obvious but there is a way!

This is where Synchronization Rules Editor comes in handy. Using this tool you can change that. You can change a lot of mappings if you wish to do so. Here's how?

Synchronization Rules Configuration

Basically when you open Synchronization Rules Editor there are multiple rules to choose from

We're mostly interested in the connector that is defined for our domain, is related to user object type and finally has userPrincipalName somewhere in it.

That leaves as only 2 with Synchronization Rules. When you now edit those two rules, you will be given an option to write directly or clone that rule and use it separately. It's up to you to decide on the best path, but it's highly advised to use the clone and merely disable the rule as suggested. It's a matter of answering Yes to the next question.

If you clone this rule, you have to edit Name, Description and mandatory Precedence fields in the next Window. The lower precedence the higher in the hierarchy. That means in our case we should use something below 100 to make sure it's first in line.

After updating Description block we now can skip to Transformations. This is where the magic happens. We're basically interested in Expression over Target Attribute UserPrincipalName

We need to modify source expression to match our needs. Whether this will be mail to UserPrincipalName field or vice versa, the change is pretty simple. You merely swap one field with another like shown in the code box below

IIF(IsPresent([userPrincipalName]),[userPrincipalName], IIF(IsPresent([sAMAccountName]),([sAMAccountName]&"@"&%Domain.FQDN%),Error("AccountName is not present")))

To

IIF(IsPresent([mail]),[mail], IIF(IsPresent([sAMAccountName]),([sAMAccountName]&"@"&%Domain.FQDN%),Error("AccountName is not present")))

While at first look it seems complicated it's quite simple equation. If the mail field is present use mail field. If it's not present check if SamAccountName is present. If it is present use SamAccountName with domain field. If SamAccountName is not present either throw an error. After replacing one equation with the other, we have to save this rule and go into the next one. As you can see on the screen below, there are three rules now, but only 2 of those are still enabled. Cloned one and the other one that we need to modify.

Finally, after editing those two rules we should be left only with two cloned, but enabled rules, and two disabled rules.

What's now left is a simple PowerShell command to make full, initial synchronization.

Start-ADSyncSyncCycle –PolicyType Initial

Give it a few minutes and verify your changes.

Small explanation on behaviour

If Email Address field is empty connector will use SamAccountName. Similarly, if you use UserPrincipalName and it will be unable to use UserPrincipalName due to not existing domain name it will use that field. In the example below user has an empty E-Mail field but below example applies to any Azure UserName that you chose for synchronization.

Will get you this

But if you fill it in properly with an email address and execute Delta synchronization on your AD Connect

Start-ADSyncSyncCycle –PolicyType Delta

It will update itself to set values adequately.

This post was last modified on %s = human-readable time difference 01:02

Przemyslaw Klys

System Architect with over 14 years of experience in the IT field. Skilled, among others, in Active Directory, Microsoft Exchange and Office 365. Profoundly interested in PowerShell. Software geek.

Share
Published by
Przemyslaw Klys
Tags: active directoryazureazure adoffice 365
6 years ago

Recent Posts

Upgrade Azure Active Directory Connect fails with unexpected error

Today, I made the decision to upgrade my test environment and update the version of…

1 month ago

Mastering Active Directory Hygiene: Automating Stale Computer Cleanup with CleanupMonster

Have you ever looked at your Active Directory and wondered, "Why do I still have…

2 months ago

Active Directory Replication Summary to your Email or Microsoft Teams

Active Directory replication is a critical process that ensures the consistent and up-to-date state of…

7 months ago

Syncing Global Address List (GAL) to personal contacts and between Office 365 tenants with PowerShell

Hey there! Today, I wanted to introduce you to one of the small but excellent…

11 months ago

Active Directory Health Check using Microsoft Entra Connect Health Service

Active Directory (AD) is crucial in managing identities and resources within an organization. Ensuring its…

1 year ago

Seamless HTML Report Creation: Harness the Power of Markdown with PSWriteHTML PowerShell Module

In today's digital age, the ability to create compelling and informative HTML reports and documents…

1 year ago