Edit

Share via

Microsoft Entra Connect Sync service features

  • Article

The synchronization feature of Microsoft Entra Connect has two components:

  • The on-premises component named Microsoft Entra Connect Sync, also called sync engine.
  • The service residing in Microsoft Entra ID also known as Microsoft Entra Connect Sync service

This topic explains how the following features of the Microsoft Entra Connect Sync service work and how you can configure them using PowerShell.

To see the configuration in your Microsoft Entra directory using the Graph PowerShell, use the following commands:

PowerShell 
Connect-MgGraph -Scopes "OnPremDirectorySynchronization.Read.All"

Get-MgDirectoryOnPremiseSynchronization | Select-Object -ExpandProperty Features | Format-List

The result looks like this output:

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

Note

From August 24, 2016 the feature Duplicate attribute resiliency is enabled by default for new Microsoft Entra directories. This feature was rolled out and enabled on directories created before this date. You'll receive an email notification when your directory is about to get this feature enabled.

The following settings are configured in Microsoft Entra Connect:

DirSyncFeature Comment
SoftMatchOnUpn Allows objects to join on userPrincipalName in addition to primary SMTP address.
SynchronizeUpnForManagedUsers Allows the sync engine to update the userPrincipalName attribute for managed/licensed (nonfederated) users.
DeviceWriteback Microsoft Entra Connect: Enabling device writeback
DirectoryExtensions Microsoft Entra Connect Sync: Directory extensions
DuplicateProxyAddressResiliency
DuplicateUPNResiliency		 Allows an attribute to be quarantined when it's a duplicate of another object rather than failing the entire object during export.
Password Hash Sync Implementing password hash synchronization with Microsoft Entra Connect Sync
Password Writeback Not supported. This service feature is discontinued. To configure Password Writeback see Enable password writeback in Microsoft Entra Connect
Pass-through Authentication User sign-in with Microsoft Entra pass-through authentication
UnifiedGroupWriteback Group writeback
UserWriteback Not currently supported.

Duplicate attribute resiliency

Instead of failing to provision objects with duplicate UPNs / proxyAddresses, the duplicated attribute is "quarantined" and a temporary value is assigned. When the conflict is resolved, the temporary UPN is changed to the proper value automatically. For more information, see Identity synchronization and duplicate attribute resiliency.

UserPrincipalName soft match

When this feature is enabled, soft-match is enabled for UPN in addition to the primary SMTP address, which is always enabled. Soft-match is used to match existing cloud users in Microsoft Entra ID with on-premises users.

If you need to match on-premises AD accounts with existing accounts created in the cloud and you aren't using Exchange Online, then this feature is useful. In this scenario, you generally don’t have a reason to set the SMTP attribute in the cloud.

This feature is on by default for newly created Microsoft Entra directories. You can see if this feature is enabled for you by running:

PowerShell 
Connect-MgGraph -Scopes "OnPremDirectorySynchronization.Read.All"

$DirectorySync = Get-MgDirectoryOnPremiseSynchronization
$DirectorySync.Features.SoftMatchOnUpnEnabled

If this feature isn't enabled for your Microsoft Entra directory, then you can enable it by running:

PowerShell 
Connect-MgGraph -Scopes "OnPremDirectorySynchronization.ReadWrite.All"

$SoftMatchOnUpn = @{ SoftMatchOnUpnEnabled = "true" }
Update-MgDirectoryOnPremiseSynchronization -Features $SoftMatchOnUpn `
   -OnPremisesDirectorySynchronizationId $DirectorySync.Id

BlockSoftMatch

When this feature is enabled, it blocks the Soft Match feature. Customers are encouraged to enable this feature and keep it at enabled until Soft Matching is required again for their tenancy. This flag should be enabled again after any soft matching has completed and is no longer needed.

Example - Blocking soft matching in your tenant:

PowerShell 
Connect-MgGraph -Scopes "OnPremDirectorySynchronization.ReadWrite.All"

$SoftBlock = @{ BlockSoftMatchEnabled = "true" }
Update-MgDirectoryOnPremiseSynchronization -Features $SoftBlock `
   -OnPremisesDirectorySynchronizationId $DirectorySync.Id

Note

When BlockSoftMatch is enabled, new hybrid-joined devices will encounter an InvalidSoftMatch error during a Soft Match attempt. This occurs when the computer object synchronized from on-premises Active Directory (AD) to Entra is merged with the new device registered in the cloud. To resolve this issue, administrators should temporarily disable BlockSoftMatch to allow the hybrid join to proceed.

Synchronize userPrincipalName updates

Historically, updates to the UserPrincipalName attribute using the sync service from on-premises was blocked, unless both of these conditions were true:

  • The user managed (nonfederated).
  • The user doesn't have a license assigned.

Note

From March 2019, synchronizing UPN changes for federated user accounts is allowed.

Enabling this feature allows the sync engine to update the userPrincipalName when it is changed on-premises and you use password hash sync or pass-through authentication.

This feature is on by default for newly created Microsoft Entra directories. You can see if this feature is enabled for you by running:

PowerShell 
Connect-MgGraph -Scopes "OnPremDirectorySynchronization.Read.All"

$DirectorySync = Get-MgDirectoryOnPremiseSynchronization
$DirectorySync.Features.SynchronizeUpnForManagedUsersEnabled

If this feature isn't enabled for your Microsoft Entra directory, then you can enable it by running:

PowerShell 
Connect-MgGraph -Scopes "OnPremDirectorySynchronization.ReadWrite.All"

$SyncUpnManagedUsers = @{ SynchronizeUpnForManagedUsersEnabled = "true" }
Update-MgDirectoryOnPremiseSynchronization -Features $SyncUpnManagedUsers `
   -OnPremisesDirectorySynchronizationId $DirectorySync.Id

After enabling this feature, existing userPrincipalName values remain as-is. On next change of the userPrincipalName attribute on-premises, the normal delta sync on users updates the UPN. Once this feature is enabled, it's not possible to disable it.

See also