How to use the BypassDirSyncOverrides feature of a Microsoft Entra tenant.
This article describes the BypassDirsyncOverrides feature and how to restore synchronization of Mobile and otherMobile attributes from Microsoft Entra ID to on-premises Active Directory.
Generally, synchronized users cannot be changed from Azure or Microsoft 365 admin portals, neither through PowerShell using Microsoft Entra ID or MSOnline modules. The exception to this is the Microsoft Entra user’s attributes called MobilePhone and AlternateMobilePhones. These attributes are synchronized from on-premises Active Directory attributes mobile and otherMobile, respectively, but end users can update their own phone number in MobilePhone attribute in Microsoft Entra ID through their profile page. Admins can also update synchronized user’s MobilePhone and AlternateMobilePhones values in Microsoft Entra ID using MSOnline PowerShell module.
Giving users and admins the ability to update phone numbers directly in Microsoft Entra ID enables enterprises to reduce the administrative overhead of managing user’s phone numbers in local Active Directory as these can change more frequently.
The caveat however, is that once a synchronized user's MobilePhone or AlternateMobilePhones number is updated via admin portal or PowerShell, the synchronization API will no longer honor updates to these attributes when they originate from on-premises Active Directory. This is commonly known as a “DirSyncOverrides” feature. Administrators will notice this behavior when updates to Mobile or otherMobile attributes in Active Directory, do not update the correspondent user’s MobilePhone or AlternateMobilePhones in Microsoft Entra ID accordingly, even though, the object is successfully synchronized through Microsoft Entra Connect's engine.
Identifying users with different Mobile and otherMobile values
You can export a list of users with different Mobile and otherMobile values between Active Directory and Microsoft Entra ID using ‘Compare-ADSyncToolsDirSyncOverrides’ from ADSyncTools PowerShell module. This will allow you to determine the users and respective values that are different between on-premises Active Directory and Microsoft Entra ID. This is important to know because enabling the BypassDirSyncOverrides feature will overwrite all the different values in Microsoft Entra ID with the value coming from on-premises Active Directory.
As a prerequisite you need to be running Microsoft Entra Connect version 2 or later and install the latest ADSyncTools module from PowerShell Gallery with the following command:
To compare all the synchronized user’s Mobile and OtherMobile values, run the following command:
Compare-ADSyncToolsDirSyncOverrides -Credential $(Get-Credential)
The target API used by this feature does not handle authentication user interactions. MFA or conditional policies will block authentication. When prompted to enter credentials, please use a Global Administrator account that doesn't have MFA enabled or any Conditional Access policy applied. As a last resort, please create a temporary Global Administrator user account without MFA or Conditional Access that can be deleted after completing the desired operations using the BypassDirSyncOverridees feature.
This function will export a CSV file with a list of users where Mobile or OtherMobile values in on-premises Active Directory are different than the respective MobilePhone or AlternateMobilePhones in Microsoft Entra ID.
At this stage you can use this data to reset the values of the on-premises Active Directory Mobile and otherMobile properties to the values that are present in Microsoft Entra ID. This way you can capture the most updated phone numbers from Microsoft Entra ID and persist this data in on-premises Active Directory, before enabling BypassDirSyncOverrides feature. To do this, import the data from the resulting CSV file and then use the 'Set-ADSyncToolsDirSyncOverrides' from ADSyncTools module to persist the value in on-premises Active Directory.
For example, to import data from the CSV file and extract the values in Microsoft Entra ID for a given UserPrincipalName, use the following command:
$upn = '<UserPrincipalName>' $user = Import-Csv 'ADSyncTools-DirSyncOverrides_yyyyMMMdd-HHmmss.csv' | where UserPrincipalName -eq $upn | select UserPrincipalName,*InAAD Set-ADSyncToolsDirSyncOverridesUser -Identity $upn -MobileInAD $user.MobileInAAD
Enabling BypassDirSyncOverrides feature
By default, BypassDirSyncOverrides feature is turned off. Enabling BypassDirSyncOverrides allows your tenant to bypass any changes made in MobilePhone or AlternateMobilePhones by users or admins directly in Microsoft Entra ID and always honor the values present in on-premises Active Directory Mobile or OtherMobile.
If you do not wish to have end users updating their own mobile phone number or there is no requirement to have admins updating mobile or alternative mobile phone numbers using PowerShell, you should leave the feature BypassDirsyncOverrides enabled on the tenant.
With this feature turned on, even if an end user or admin updates either MobilePhone or AlternateMobilePhones in Microsoft Entra ID, the values synchronized from on-premises Active Directory will persist upon the next sync cycle. This means that any updates to these values only persist when the update is performed in on-premises Active Directory and then synchronized to Microsoft Entra ID.
Enable the BypassDirSyncOverrides feature:
To enable BypassDirSyncOverrides feature use the MSOnline PowerShell module.
Set-MsolDirSyncFeature -Feature BypassdirSyncOverrides -Enable $true
Once the feature is enabled, start a full synchronization cycle in Microsoft Entra Connect using the following command:
Start-ADSyncSyncCycle -PolicyType Initial
[!NOTE] Only objects with a different MobilePhone or AlternateMobilePhones value from on-premises Active Directory will be updated.
Verify the status of the BypassDirSyncOverrides feature:
Get-MsolDirSyncFeatures -Feature BypassdirSyncOverrides
Disabling BypassDirSyncOverrides feature
If you desire to restore the ability to update mobile phone numbers from the portal or PowerShell, you can disable BypassDirSyncOverrides feature using the following Microsoft Online PowerShell module command:
Set-MsolDirSyncFeature -Feature BypassdirSyncOverrides -Enable $false
When this feature is turned off, anytime a user or admin updates the MobilePhone or AlternateMobilePhones directly in Microsoft Entra ID, a DirSyncOverrides is created which prevents any future updates to these attributes coming from on-premises Active Directory. From this point on, a user or admin can only manage these attributes from Microsoft Entra ID as any new updates from on-premises Mobile or OtherMobile will be dismissed.
Managing mobile phone numbers in Microsoft Entra ID and on-premises Active Directory
To manage the user’s phone numbers, an admin can use the following set of functions from ADSyncTools module to read, write and clear the values in either Microsoft Entra ID or on-premises Active Directory.
Get Mobile and OtherMobile properties from on-premises Active Directory:
Get-ADSyncToolsDirSyncOverridesUser 'User1@Contoso.com' -FromAD
Get MobilePhone and AlternateMobilePhones properties from Microsoft Entra ID:
Get-ADSyncToolsDirSyncOverridesUser 'User1@Contoso.com' -FromAzureAD
Set MobilePhone and AlternateMobilePhones properties in Microsoft Entra ID:
Set-ADSyncToolsDirSyncOverridesUser 'User1@Contoso.com' -MobilePhoneInAAD '999888777' -AlternateMobilePhonesInAAD '0987654','1234567'
Set Mobile and otherMobile properties in on-premises Active Directory:
Set-ADSyncToolsDirSyncOverridesUser 'User1@Contoso.com' -MobileInAD '999888777' -OtherMobileInAD '0987654','1234567'
Clear MobilePhone and AlternateMobilePhones properties in Microsoft Entra ID:
Clear-ADSyncToolsDirSyncOverridesUser 'User1@Contoso.com' -MobilePhoneInAAD -AlternateMobilePhonesInAAD
Clear Mobile and otherMobile properties in on-premises Active Directory:
Clear-ADSyncToolsDirSyncOverridesUser 'User1@Contoso.com' -MobileInAD -OtherMobileInAD
Learn more about Microsoft Entra Connect:
ADSyncTools PowerShell module