UPN and sAMAccountName Updates and Entra ID Directory Synchronization Features

The other day, I received a note from an Office 365 for IT Pros reader to say that they’d perused the book to seek advice about how best to handle the situation when someone needs to change their name, usually because of marriage or divorce. The reader says that their usual practice is to change the user’s email address in Active Directory, but that they avoid changing the user principal name and sAMAccountName because changing “either or both of those attributes breaks their connection with Microsoft 365 services when the sync occurs.”

Microsoft documents issues that can occur when a user principal name changes, and there are quite a few forum discussions about changing attributes in Active Directory (here’s an example). We don’t cover directory synchronization in the Office 365 for IT Pros eBook. We used to, but then relegated the coverage to the companion volume, and then we dropped the companion volume because most of its material had aged significantly.

Use a Depreciated Module to Set Directory Synchronization Features

Seeing that I had no good answer for our reader, I pushed the question to Brian Desmond, who looks after the Entra ID chapter in the book. His response was “Changing the UPN or sAMAccountName [for a user account] should not break the sync process because Entra Connect uses their objectGUID in AD as the anchor. That said, you need to turn on the SynchronizeUpnForManagedUsers feature for that change to work right.”

Brian went on to reference the Set-MsolDirSyncFeature cmdlet as the way to enable the SynchronizeUpnForManagedUsers feature. The cmdlet is from the MSOL (Microsoft Online Services) module, which is depreciated and due for final retirement on March 30, 2025. The question then is how to set the feature without using a soon-to-be-removed cmdlet?

The Graph Answer for Managing Directory Synchronization Features

The answer is to use the UpdateonPremisesDirectorySynchronization Graph API to update the properties of the onPremisesDirectorySynchronizationFeature resource type, where we discover that synchronizeUpnForManagedUsersEnabled is a Boolean property.

Where there’s a Graph API, there’s a Microsoft Graph PowerShell SDK cmdlet. In this case, the Update-MgDirectoryOnPremiseSynchronization cmdlet (I’ve already flagged the error in referring to “OnPremises” as “OnPremise;” and yes, these things matter).

Here’s how to update two directory synchronization feature settings with the Graph SDK cmdlet. First, find the identifier for the directory synchronization object in the tenant:

$SyncId = Get-MgDirectoryOnPremiseSynchronization | Select-Object -ExpandProperty Id

Now build a hash table for the features to enable (or disable). The keys for the hash table must match (including casing) the properties described here.

$Features = @{}
$Features.Add(“softMatchOnUpnEnabled”,$true)
$Features.Add(“synchronizeUpnForManagedUsersEnabled”,$true)

Finally, build another hash table to hold the parameters for the update cmdlet and run the cmdlet:

$Parameters = @{}
$Parameters.Add(“features”,$Features)
Update-MgDirectoryOnPremiseSynchronization -OnPremisesDirectorySynchronizationId $SyncId -BodyParameter $Parameters

To check the current state of the directory synchronization settings, run the Get-MgDirectoryOnPremiseSynchronization cmdlet:

Get-MgDirectoryOnPremiseSynchronization | Select-Object -ExpandProperty Features | fl

BlockCloudObjectTakeoverThroughHardMatchEnabled : False
BlockSoftMatchEnabled : False
BypassDirSyncOverridesEnabled : False
CloudPasswordPolicyForPasswordSyncedUsersEnabled : False
ConcurrentCredentialUpdateEnabled : False
ConcurrentOrgIdProvisioningEnabled : False
DeviceWritebackEnabled : False
DirectoryExtensionsEnabled : False
FopeConflictResolutionEnabled : False
GroupWriteBackEnabled : False
PasswordSyncEnabled : False
PasswordWritebackEnabled : False
QuarantineUponProxyAddressesConflictEnabled : False
QuarantineUponUpnConflictEnabled : False
SoftMatchOnUpnEnabled : True
SynchronizeUpnForManagedUsersEnabled : True
UnifiedGroupWritebackEnabled : False
UserForcePasswordChangeOnLogonEnabled : False
UserWritebackEnabled : False
AdditionalProperties : {}

Entra PowerShell Module’s Directory Synchronization Feature Cmdlets

And because Microsoft introduced the Entra PowerShell module in preview in June 2024 specifically to help customers migrate away from the depreciated AzureAD and MSOL modules, there’s also the Set-EntraDirSyncFeature cmdlet. Microsoft handcrafted the cmdlets in the Entra module to make them more PowerShell-like than Graph-like, so this cmdlet is the easiest one to use.

To make the change, I installed the latest version of the Entra preview module (Figure 1) from the PowerShell gallery, and then ran:

Import-Module Microsoft.Graph.Entra
Connect-Entra -Scopes OnPremDirectorySynchronization.ReadWrite.All
Set-EntraDirSyncFeature -Feature SynchronizeUpnForManagedUsers -Enabled:$true

The Get-EntraDirSyncFeature cmdlet reveals the current state for directory synchronization features:

Get-EntraDirSyncFeature

Enabled DirSyncFeature
——- ————–
False BlockCloudObjectTakeoverThroughHardMatch
False BlockSoftMatch
False BypassDirSyncOverrides
False CloudPasswordPolicyForPasswordSyncedUsers
False ConcurrentCredentialUpdate
False ConcurrentOrgIdProvisioning
False DeviceWriteback
False DirectoryExtensions
False FopeConflictResolution
False GroupWriteBack
False PasswordSync
False PasswordWriteback
False QuarantineUponProxyAddressesConflict
False QuarantineUponUpnConflict
True SoftMatchOnUpn
True SynchronizeUpnForManagedUsers
False UnifiedGroupWriteback
False UserForcePasswordChangeOnLogon
False UserWriteback

Each directory synchronization feature must be managed separately. You can’t enable or disable several features in one operation.

Any Lingering Synchronization Issues?

Although I discovered how to replace the old MSOL cmdlet with a new Entra cmdlet to set directory synchronization features, I still didn’t find out if people encounter synchronization issues after updating on-premises user account properties like the user principal name and sAMAccountName. If you’ve had problems that you couldn’t resolve, note them as a comment. Maybe someone else will have a solution.

Insight like this doesn’t come easily. You’ve got to know the technology and understand how to look behind the scenes. Benefit from the knowledge and experience of the Office 365 for IT Pros team by subscribing to the best eBook covering Office 365 and the wider Microsoft 365 ecosystem.