How to use the BypassDirSyncOverrides feature of an Azure AD tenant.

This article describes the BypassDirsyncOverrides  feature and how to restore synchronization of Mobile and otherMobile attributes from Azure AD to on-premises Active Directory.

Generally, synchronized users cannot be changed from Azure or Microsoft 365 admin portals, neither through PowerShell using AzureAD or MSOnline modules. The exception to this is the Azure AD 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 Azure AD through their profile page. Admins can also update synchronized user’s MobilePhone and AlternateMobilePhones values in Azure AD using MSOnline PowerShell module.

Giving users and admins the ability to update phone numbers directly in Azure AD 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 Azure AD accordingly, even though, the object is successfully synchronized through Azure AD 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 Azure Active Directory 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 Azure Active Directory. This is important to know because enabling the BypassDirSyncOverrides feature will overwrite all the different values in Azure Active Directory with the value coming from on-premises Active Directory.

Using Compare-ADSyncToolsDirSyncOverrides

As a prerequisite you need to be running Azure AD Connect version 2 or later and install the latest ADSyncTools module from PowerShell Gallery with the following command:

Install-Module ADSyncTools 

To compare all the synchronized user’s Mobile and OtherMobile values, run the following command:

Compare-ADSyncToolsDirSyncOverrides -Credential $(Get-Credential) 

Note

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 Azure AD.

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 Azure Active Directory. This way you can capture the most updated phone numbers from Azure AD 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 Azure AD 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 Azure AD 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 Azure Active Directory, 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 Azure Active Directory.

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 Azure AD 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 Azure AD, 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 Azure AD as any new updates from on-premises Mobile or OtherMobile will be dismissed.

Managing mobile phone numbers in Azure AD 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 Azure AD 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 Azure AD:

Get-ADSyncToolsDirSyncOverridesUser 'User1@Contoso.com' -FromAzureAD

Set MobilePhone and AlternateMobilePhones properties in Azure AD:

Set-ADSyncToolsDirSyncOverridesUser 'User1@Contoso.com' -MobileInAD '999888777'  -OtherMobileInAD '0987654','1234567'

Set Mobile and otherMobile properties in on-premises Active Directory:

Set-ADSyncToolsDirSyncOverridesUser 'User1@Contoso.com' -MobilePhoneInAAD '999888777' -AlternateMobilePhonesInAAD '0987654','1234567'

Clear MobilePhone and AlternateMobilePhones properties in Azure AD:

Clear-ADSyncToolsDirSyncOverridesUser 'User1@Contoso.com' -MobileInAD -OtherMobileInAD

Clear Mobile and otherMobile properties in on-premises Active Directory:

Clear-ADSyncToolsDirSyncOverridesUser 'User1@Contoso.com' -MobilePhoneInAAD -AlternateMobilePhonesInAAD

Next Steps

Learn more about Azure AD Connect: ADSyncTools PowerShell Module