Microsoft Entra Connect Sync service features

Article
07/26/2024

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:

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "OnPremDirectorySynchronization.Read.All"

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

The result looks like this output:

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 will also be rolled out and enabled on directories created before this date. You will 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
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:

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -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:

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -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:

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "OnPremDirectorySynchronization.ReadWrite.All"

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

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 syn.