Manage directory synchronization settings via the Graph API

After years of unsuccessful attempts to deprecate the good old MSOnline PowerShell module and subsequent postponements for its end of life, Microsoft seems to finally be making steps in the right direction and providing actual replacements for missing functionalities. In this case, we’re talking about the set of cmdlets used to manage directory synchronization settings, most of which are now covered by a Graph API endpoint. Let’s take a look.

First, a quick refresher on the set of cmdlets involved. Apart from the Get-MsolCompanyInformation cmdlet, which can be used to check the status of directory synchronization and password sync, the last sync timestamps and the service account used, the MSOnline module features a set of cmdlets to get or update some of the settings controlling the dirsync process. Those include:

• Get-MsolDirSyncConfiguration – gives you the status of the Accidental deletion feature.
• Get-MsolDirSyncFeatures – gives you the status of the rest of the features, such as device writeback or soft-match based on UPN.
• Set-MsolDirSyncConfiguration – updates the Accidental deletion feature settings.
• Set-MsolDirSyncEnabled – toggles the status of the directory synchronization feature itself.
• Set-MsolDirSyncFeature – controls the rest of the features.

The list of corresponding replacements is now available under the /beta endpoint of the Graph API, under /directory/onPremisesSynchronization/. Only delegate permissions are currently supported, and you will need the OnPremDirectorySynchronization.Read.All scope to read the current settings values. To make changes, the OnPremDirectorySynchronization.ReadWrite.All scope is needed. Let’s take a look at few examples.

First, to get the current configuration, use a GET query against the /onPremisesSynchronization endpoint:

GET https://graph.microsoft.com/beta/directory/onPremisesSynchronization

As you can see from the screenshot above, the settings are grouped into two sections. Configuration lists the accidental deletion feature settings as well as the sync interval settings, all bundled into a onPremisesDirectorySynchronizationConfiguration resource type. Features lists the settings for each feature, as part of the onPremisesDirectorySynchronizationFeature resource type. Do note that the individual feature names differ between the output of the MSOnline cmdlets and the Graph API. Lastly, we have the id value, representing the tenant’s objectID, which we will need in order to update the settings.

To update the directory synchronization settings, one must issue a PATCH request against the /directory/onPremisesSynchronization/{id} endpoint and provide a JSON body with the corresponding resource settings values. The OnPremDirectorySynchronization.ReadWrite.All scope is required in order to make change, so make sure you have it granted and are running in the delegate permissions model. The list of “configuration” settings you can update includes:

• accidentalDeletionPrevention – a representation of the onPremisesAccidentalDeletionPrevention resource, with two settings:
  • alertThreshold – integer value representing the maximum number of objects deleted before an alert is triggered. Alternatively, you can provide a percentage value (see below).
  • synchronizationPreventionType – string value (enum?), representing the status of the accidental deletion feature. Possible values include: disabled, enforcedForCount and enforcedForPercentage.
• synchronizationInterval – the sync interval, represented as a duration value. The default value is “PT30M”. If directory synchronization is disabled, the value will be null.
• customerRequestedSynchronizationInterval – the custom sync interval, as requested by your organization. Also represented as a duration value. If directory synchronization is disabled, the value will be null.

As an example, here’s how to update the alertThreshold value:

PATCH https://graph.microsoft.com/beta/directory/onPremisesSynchronization/923712ba-352a-4eda-bece-09d0684d0cfb

Next, we have the set of “feature” settings. Those include:

• BlockCloudObjectTakeoverThroughHardMatch – controls whether “hard-match” is enabled.
• blockSoftMatchEnabled – controls whether “soft-match” is enabled.
• bypassDirSyncOverridesEnabled – controls the “dirsync overrides” feature as detailed here.
• cloudPasswordPolicyForPasswordSyncedUsersEnabled – controls whether the cloud password policy applies to user with password sync enabled.
• concurrentCredentialUpdateEnabled – controls concurrency for user credentials updates.
• concurrentOrgIdProvisioningEnabled – controls concurrency for user provisioning.
• deviceWritebackEnabled – controls the device writeback feature.
• directoryExtensionsEnabled – controls the  directory extensions feature.
• fopeConflictResolutionEnabled – this setting is only relevant for FOPE clients, and no longer used?
• groupWriteBackEnabled – controls the group writeback feature.
• passwordSyncEnabled – controls the password sync feature.
• passwordWritebackEnabled – controls the password writeback feature.
• quarantineUponProxyAddressesConflictEnabled – controls the behavior of the duplicate attribute resiliency feature.
• quarantineUponUpnConflictEnabled – as above.
• softMatchOnUpnEnabled – controls whether soft-match should happen also on UPN values.
• synchronizeUpnForManagedUsersEnabled – controls whether UPN updates are syncrhonized from on-premises (read here).
• unifiedGroupWritebackEnabled – controls the M365 Group writeback feature.
• userForcePasswordChangeOnLogonEnabled – controls the force password change on next logon feature.
• userWritebackEnabled – controls the User writeback feature (deprecated?).

As an example, here’s how to toggle the group writeback and M365 group writeback features:

PATCH https://graph.microsoft.com/beta/directory/onPremisesSynchronization/923712ba-352a-4eda-bece-09d0684d0cfb

You can of course mix and match settings between the configuration and features sections as needed. Do note however that not all settings can be changed. And most importantly, none of the settings above allows you to actually enable/disable directory synchronization currently, as you might have already noticed. This is controlled via the onPremisesSyncEnabled value, which is currently NOT exposed via the Graph API. I’ll make sure to update the article once that happens.

UPDATE 03.2023: The endpoints are not released under the /v1.0 branch!