为现有租户配置 Microsoft Entra Connect

有关如何使用 Microsoft Entra Connect 的大部分文章都假定你从没有用户或其他对象的新Microsoft Entra租户开始。 但是，如果你最初使用的是 Microsoft Entra 租户，已在其中填充了用户和其他对象，并且现在想要使用 Connect，那么本文适合你。

基础知识

Microsoft Entra ID 中的对象在云中或本地进行管理。 对于单个对象，不能在本地管理某些属性，也不能管理 Microsoft Entra ID 中的一些其他属性。 每个对象都有一个标志，指示对象在何处进行管理。

可以在本地管理一些用户，也可以在云中管理其他用户。 此配置的常见方案是一个组织，其中包含会计工作者和销售人员的组合。 会计人员有一个本地 Active Directory (AD) 帐户，而销售人员没有，但这两类人员都在 Microsoft Entra ID 中有一个帐户。 你将在本地管理一些用户，在 Microsoft Entra ID 中管理一些用户。

当你开始管理同时在 Microsoft Entra ID 和本地环境中存在的用户时，如果希望后续使用 Microsoft Entra Connect，还需要考虑一些其他注意事项。

与 Microsoft Entra ID 中的现有用户同步

开始与 Microsoft Entra Connect 同步时，Microsoft Entra 服务 API 会检查每个新的传入对象，并尝试查找要匹配的现有对象。 此过程使用三个属性： userPrincipalName、 proxyAddresses 和 sourceAnchor/immutableID。 userPrincipalName 或 proxyAddresses 上的匹配称为“软匹配”。sourceAnchor 上的匹配称为“硬匹配”。对于 proxyAddresses 属性，仅使用 SMTP：的值（即主电子邮件地址）用于评估。

只会针对来自本地 AD 的新对象评估匹配。 如果更改现有对象，使其与这些属性中的任何一个匹配，则会看到错误。

如果Microsoft Entra ID 找到一个对象，其中属性值与来自 Microsoft Entra Connect 的新传入对象相同，则它将接管 Microsoft Entra ID 中的对象，而以前云托管的对象将转换为本地托管对象。 Microsoft Entra ID 中的所有属性如果在本地 AD 中具有值，这些属性会被相应的本地值覆盖。

规划部署时，请考虑上述数据丢失警告。 如果你在 Microsoft Entra ID 中进行了许多更改，而这些更改尚未反映到本地 AD DS 中，那么为防止数据丢失，请先规划如何将 Microsoft Entra ID 中更新后的值写入 AD DS，再使用 Microsoft Entra Connect 同步你的对象。

如果通过软匹配将对象匹配，则会将 sourceAnchor 添加到 Microsoft Entra ID 中的对象上，以便之后可以使用硬匹配。

硬匹配与软匹配

默认情况下，对象的 SourceAnchor 值（例如“abcdefghijklmnopqrstuv=”）是从本地 Active Directory 对象的 mS-Ds-ConsistencyGUID 属性（或 ObjectGUID）的 Base64 字符串表示形式。 此值设置为 Microsoft Entra ID 中的相应 ImmutableId。

Microsoft Entra Connect 或 Cloud Sync 添加新对象时，Microsoft Entra ID 服务会尝试使用与 Microsoft Entra ID 中存在对象的 ImmutableId 属性对应的 sourceAnchor 值匹配传入对象。 如果存在匹配项，Microsoft Entra Connect 会接管该对象的源权限（SoA），并使用传入的本地 Active Directory 对象的属性对其进行更新，这一过程称为硬匹配。 当Microsoft Entra ID找不到任何与 SourceAnchor 值匹配的 ImmutableId 的对象时，它会尝试使用传入对象的 userPrincipalName 或主 SMTP 地址在所谓的软匹配中找到匹配项。

硬匹配和软匹配都尝试匹配Microsoft Entra ID中已经存在和管理的对象，并添加表示同一本地实体的新传入对象。 如果Microsoft Entra ID找不到传入对象的硬匹配或软匹配，则会在Microsoft Entra ID目录中预配一个新对象。

如果 Microsoft Entra ID 能够基于主 SMTP 地址将新的传入对象与 Microsoft Entra ID 中管理的现有对象软匹配，但该新对象具有不同的 sourceAnchor 值，则 Microsoft Entra ID 会尝试预配一个新对象。 预配尝试通常会导致冲突，使 Microsoft Entra ID 无法创建新对象。 这种冲突在以下情况下发生：

• 在已同步到 Entra ID 的原始本地 AD 用户中，mS-Ds-ConsistencyGuid 属性被设置了不同的 sourceAnchor 值。

• 使用同一 UPN 和主 SMTP 地址创建了一个新的本地 AD 用户，但具有不同的 sourceAnchor 和 SID。

在这种情况下，Microsoft Entra Connect 或云同步中会引发 AttributeValueMustBeUnique 导出错误。根据传入的用户属性，此错误可能指示以下属性冲突之一：

• AttributeConflictName = OnPremiseSecurityIdentifier：新的对象具有不同的源锚定，但与 Entra ID 目录中存在的用户具有相同的 OnPremiseSecurityIdentifier（SID）和主 SMTP 地址。

• AttributeConflictName = ProxyAddresses：新的传入对象具有不同的 sourceAnchor 和 SID，但与 Entra ID 目录中存在的用户具有相同的主 SMTP 地址。

这些情况通常意味着你尝试重新配置同一用户。 若要解决冲突，应更新本地用户 mS-Ds-ConsistencyGuid 的属性，以匹配与现有云用户的 ImmutableID 相同的值。 此更改使 Microsoft Entra ID 能够进行正确的硬匹配。

在 Microsoft Entra ID 中阻止硬匹配

我们添加了一个配置选项，用于在 Microsoft Entra ID 中禁用硬匹配功能。 建议客户禁用硬匹配，除非他们需要它来接管仅限云的帐户。

若要禁用硬匹配，请使用 Update-MgDirectoryOnPremiseSynchronization Microsoft Graph PowerShell cmdlet：

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

$OnPremSync = Get-MgDirectoryOnPremiseSynchronization
$OnPremSync.Features.BlockCloudObjectTakeoverThroughHardMatchEnabled = $true
Update-MgDirectoryOnPremiseSynchronization `
    -OnPremisesDirectorySynchronizationId $OnPremSync.Id `
    -Features $OnPremSync.Features

在 Microsoft Entra ID 中阻止软匹配

同样，我们添加了一个配置选项，用于在 Microsoft Entra ID 中禁用软匹配选项。 我们建议客户禁用软匹配，除非他们需要它接管仅限云的帐户。

若要禁用软匹配，请使用 Update-MgDirectoryOnPremiseSynchronization Microsoft Graph PowerShell cmdlet：

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

$OnPremSync = Get-MgDirectoryOnPremiseSynchronization
$OnPremSync.Features.BlockSoftMatchEnabled = $true
Update-MgDirectoryOnPremiseSynchronization `
    -OnPremisesDirectorySynchronizationId $OnPremSync.Id `
    -Features $OnPremSync.Features

硬匹配安全保护

自 2026 年 7 月 1 日起，Microsoft Entra ID 将为硬匹配操作增加额外保护。 当目标帐户有重新关联的风险时，这些保护有助于防止本地 Active Directory对象接管错误的云帐户。

当目标云帐户满足以下一个或多个条件时，可能会阻止硬匹配：

• 云账户已设置 onPremisesObjectIdentifier。
• 该云账户被分配了 Microsoft Entra 特权角色。
• 该云账户符合分配 Microsoft Entra 特权角色的条件。

这些安全保护不会禁用硬匹配。 安全目标的初始硬匹配仍然有效，并且已正确匹配的用户持续同步不会受到影响。 已启用写回的云管理帐户不受此项强制措施的约束。 检查在云中强制执行，因此无论客户端版本如何，它都适用于 Microsoft Entra Connect Sync 和 Microsoft Entra Cloud Sync。 软匹配 行为保持不变，并将继续由 BlockSoftMatchEnabled 该功能单独管理。

有关确切的错误消息和针对特定错误的修复方法，请参阅 排查 InvalidHardMatch 错误。

在有意将本地用户与现有云用户进行硬匹配之前，请验证以下内容：

• 云用户是接管该本地对象的正确账户。
• 该云用户未被分配特权 Microsoft Entra 角色，也不符合分配该角色的资格，除非你计划先暂时移除该角色或取消其资格。
• 云用户尚未设置 onPremisesObjectIdentifier，除非你打算在重试之前先将其清除。
• 来自本地对象的源定位点值与云用户的 onPremisesImmutableId匹配。

硬匹配场景和恢复路径

下表汇总了常见的硬匹配场景，说明 Microsoft Entra ID 是否允许或阻止每种场景，以及如何恢复。

修复被特权角色阻止的硬匹配

如果云用户具有特权角色分配或资格：

1. 确认本地对象应链接到现有云用户。
2. 如果用户已软删除，请从Microsoft Entra ID回收站还原它。
3. 暂时从云用户中删除特权角色分配或资格。
4. 重新运行同步以完成硬匹配。
5. 重新分配特权角色或还原资格。

清除 onPremisesObjectIdentifier

如果由于已设置 onPremisesObjectIdentifier 而导致硬匹配被阻止，请将该值清除为 null，然后重新运行同步。 使用 Microsoft Graph 或 ADSyncTools。

若要通过 Microsoft Graph 清除 onPremisesObjectIdentifier 以便继续同步，请发送以下请求：

PATCH https://microsoftgraph.chinacloudapi.cn/beta/users/{userId}
Content-Type: application/json

{
  "onPremisesObjectIdentifier": null
}

此 PATCH 请求需要具有 User-OnPremisesSyncBehavior.ReadWrite.All Microsoft Graph 权限以及全局管理员或混合身份管理员角色。

或者，若要使用 ADSyncTools 2.5.0 或更高版本清除 onPremisesObjectIdentifier，请运行以下命令：

# Provide the user's identity.
$userId = "<userId>"

# Review the current on-premises attributes.
Get-ADSyncToolsOnPremisesAttribute -Id $userId

# Optional: back up the current values before making changes.
Get-ADSyncToolsOnPremisesAttribute -Id $userId | Export-Clixml backupOnpremisesAttributes.Clixml

# Clear onPremisesObjectIdentifier.
Clear-ADSyncToolsOnPremisesAttribute -Id $userId -onPremisesObjectIdentifier

清除该值后，重新运行同步。

暂时允许 onPremisesObjectIdentifier 更新

如果在强制实施之前无法修正受影响的对象，请启用租户级功能标志 allowOnPremUpdateOfOnPremisesObjectIdentifierEnabled。 默认情况下，此标志处于禁用状态。 除非您需要在完成修复期间进行临时绕过，否则请将该标志保持为禁用状态。

$baseUri = "https://microsoftgraph.chinacloudapi.cn/beta"
$onPremSync = Get-MgDirectoryOnPremiseSynchronization
$uri = "$baseUri/directory/onPremisesSynchronization/$($onPremSync.Id)"
$params = @{
    features = @{
        allowOnPremUpdateOfOnPremisesObjectIdentifierEnabled = $true
    }
}
Invoke-MgGraphRequest -Method PATCH -Uri $uri -Body $params
(Get-MgDirectoryOnPremiseSynchronization).Features | fl

用户以外的其他对象

对于启用邮件的组和联系人，可以基于 proxyAddresses 进行软匹配。 硬匹配不适用，因为你只能通过 PowerShell 更新用户的 sourceAnchor/immutableID。 对于未启用邮件功能的组，不支持软匹配或硬匹配。

管理员角色注意事项

为了防止不受信任的本地用户，Microsoft Entra ID 与具有管理员角色的云用户不匹配。 这是默认行为。 若要解决此问题，请执行以下步骤：

1. 从云专用用户对象中删除目录角色。
2. 硬删除在云中创建的新隔离对象。
3. 触发新的同步周期。
4. （可选）在匹配完成后，将目录角色添加回云中的用户对象。

从 Microsoft Entra ID 中的数据创建新的本地 Active Directory

某些客户最初在 Microsoft Entra ID 中使用仅限云的解决方案，而没有构建本地 AD。 稍后，他们希望使用本地资源，并想要基于 Microsoft Entra 数据生成本地 AD。 Microsoft Entra Connect 无法帮助实现此方案。 它不会在本地创建用户，并且无法将本地密码设置为与 Microsoft Entra ID 中的密码相同。

如果计划添加本地 AD 的唯一原因是支持业务线（LOB）应用，请考虑改用Microsoft Entra 域服务。

相关内容

详细了解如何将本地标识与 Microsoft Entra ID 集成。