Microsoft Entra Connect Sync service features
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 -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 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:
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:
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:
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:
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:
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.