Table of Contents
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 Deprecated 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 deprecated 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 deprecated 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.
I find the user can encounter OneDrive issues temporarily whilst the changes are propagated around and the odd user will encounter permissions issues within SharePoint Online and the only way I found to fixed that is to when viewing person for a group and change the id to 0 so it brings a list of users find the user and delete them and re-add it back
Worth noting, I believe, that once enabled the EnableSoftMatchOnUpn feature cannot be disabled. Tread carefully if you have customers where the AD and Entra UPNs are mismatched (not recommended i know, but some customers have quirks) as a soft match based on Primary SMTP will also update the UPN in Entra to match the UPN in AD which causes an issue if you require them mismatched.
A new way of configuring directory synchronization settings doesn’t affect how the actual tools that use these settings work…