预配到 Active Directory 时使用目录扩展

目录扩展将属性添加到Microsoft Entra ID拥有的Microsoft Entra架构。从Microsoft Entra ID预配到Active Directory时，可以将该属性放入两个用途：确定预配的对象，或将值传递到Active Directory属性中。这两种用法对用户和组都适用。

本文将分别讲解其中每种情况的一个示例。选择每个步骤中的 “组或用户 ”选项卡，以遵循所需的示例。你的选择将贯穿本文的其余部分。

Tab	Example	Use
组	`WritebackEnabled`	仅预配扩展属性值为 true 的组。
用户	`EmployeeCode`	将扩展值写入Active Directory用户属性。

有关目录扩展的背景信息，请参阅目录扩展，以便将Microsoft Entra ID预配到Active Directory。有关常规映射界面和表达式语法，请参阅配置向 Active Directory 进行预配。

注释

Microsoft Entra ID 为组提供一个内置的 isWritebackEnabled 属性，可通过 Microsoft Graph 进行设置。可以使用属性值筛选直接筛选该属性，因此不需要自定义扩展属性来控制写回哪些组。如果需要限定内置属性未涵盖的值，请使用本文中的步骤。

组也支持属性映射。对于其授权来源已转换为 Microsoft Entra ID 的组，GroupDN 扩展会保留原始组织单位和公用名。若要创建该扩展，请参阅 “保留组的组织单位和名称”。有关读取它的表达式，请参阅 “保留组的原始组织单位”。

在您开始之前

这两个示例都需要相同的起点：

与 Microsoft Entra ID 同步用户的工作环境。
连接到目标Active Directory域的正常预配代理。
用于Active Directory配置的Microsoft Entra ID，或创建配置的权限。

然后，每个示例都需要自己的对象。

组
用户

此示例使用以下环境：

四个同步用户：Britta Simon、Lola Jacobson、Anna Ringdahl 和 John Smith。
Active Directory中的三个组织单位：销售、营销和组。
Britta Simon 和 Anna Ringdahl 用户帐户驻留在 Sales 组织单位中。
Lola Jacobson 和 John Smith 用户帐户驻留在 Marketing 组织单位中。
组 OU 是预配来自 Microsoft Entra ID 的组的位置。

可以使用本文中创建的环境进行测试或更熟悉云同步。

小窍门

在ms-vscode.powershell使用 Visual Studio Code 和扩展，以获得执行 Microsoft Graph PowerShell SDK cmdlet 的更好体验。

安装和连接 Microsoft Graph PowerShell SDK

如果尚未安装，请按照 Microsoft Graph PowerShell SDK 文档安装 Microsoft Graph PowerShell SDK 的主要模块： Microsoft.Graph。
使用管理权限打开 PowerShell。
若要设置执行策略，请运行以下命令（出现提示时全部按“[A] 是”）：
```
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

连接到租户（请务必在登录时代表接受）：

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "Directory.ReadWrite.All", "Application.ReadWrite.All", "User.ReadWrite.All", "Group.ReadWrite.All"

重要

以交互方式进行身份验证。不要在脚本中放置帐户密码。

创建 CloudSyncCustomExtensionsApp 应用程序和服务主体

这两个示例将扩展存储在同一个应用程序上，因此只需执行此操作一次。

重要

Microsoft Entra Cloud Sync 的目录扩展仅支持标识符 URI 为 api://<tenantId>/CloudSyncCustomExtensionsApp 的应用程序，以及由 Microsoft Entra Connect 创建的标识符为的租户架构扩展应用程序。

获取租户 ID：
```
$tenantId = (Get-MgOrganization).Id
$tenantId
```
注释

这会输出当前租户 ID。可以通过导航到 Microsoft Entra 管理中心>Entra ID>概述来确认此租户 ID。

使用上一步中的 $tenantId 变量，检查 CloudSyncCustomExtensionsApp 是否存在。

$cloudSyncCustomExtApp = Get-MgApplication -Filter "identifierUris/any(uri:uri eq 'api://$tenantId/CloudSyncCustomExtensionsApp')"
$cloudSyncCustomExtApp

如果存在 CloudSyncCustomExtensionsApp，请跳到下一步。否则，请创建新的 CloudSyncCustomExtensionsApp 应用：

$cloudSyncCustomExtApp = New-MgApplication -DisplayName "CloudSyncCustomExtensionsApp" -IdentifierUris "api://$tenantId/CloudSyncCustomExtensionsApp"
$cloudSyncCustomExtApp

检查 CloudSyncCustomExtensionsApp 应用程序是否关联了服务主体。如果你刚才创建了新应用，请跳到下一步。
```
Get-MgServicePrincipal -Filter "AppId eq '$($cloudSyncCustomExtApp.AppId)'"
```
如果刚刚创建新应用或未返回服务主体，请为 CloudSyncCustomExtensionsApp 创建服务主体：
```
New-MgServicePrincipal -AppId $cloudSyncCustomExtApp.AppId
```

注释

在Microsoft Entra ID中创建目录扩展不需要重启预配代理。仅当代理需要发现新添加的Active Directory架构属性时，才重启代理。

在Microsoft Entra ID中创建两个组。一个是销售组，另一个是市场营销组。

请以至少混合身份管理员的身份登录Microsoft Entra 管理中心。
浏览到 Entra ID>群组>所有群组。
在顶部，选择新建组。
确保“组类型”设置为“安全”。
对于 组名称，请输入 Sales。
对于 成员身份类型，请将其保留在分配状态。
选择“创建”。
使用 Marketing 作为 组名称重复此过程。

现在，将用户添加到创建的组。

浏览到 Entra ID>群组>所有群组。
在顶部的搜索框中输入“Sales”。
选择新的 “销售 ”组。
在左侧，选择“ 成员”。
在顶部，选择“ 添加成员”。
选中 Britta Simon 和 Anna Ringdahl，然后单击选择。
在最左侧，选择 “所有组 ”，并使用 “营销 ”组重复此过程，添加 洛拉·雅各布森 和 约翰·史密斯。

注释

将用户添加到 Marketing 组时，请记下概述页上的组 ID。稍后使用此 ID 将新创建的属性添加到组。

确定要预配到Active Directory的云托管用户，并确认可以检索它：

$testUser = Get-MgUser -Filter "userPrincipalName eq '<test-user-UPN>'"
$testUser

您可以选择通过组将用户纳入范围，而不是直接选择该用户：

创建分配的Microsoft Entra安全组，例如 AD-Provisioning-Test。
将云托管的测试用户添加到组。
在云同步中配置用户范围时选择该组。

重要

每个用户都会保留该扩展属性值。组成员身份仅将用户纳入预配范围；组成员身份本身并不传递该值。

创建目录扩展

组
用户

小窍门

此示例创建了一个名为 WritebackEnabled 的自定义扩展属性，用于 Microsoft Entra Cloud Sync 作用域筛选器，以便仅将 WritebackEnabled 设置为 true 的组写回本地 Active Directory。它的工作方式类似于本文前面所述的内置 isWritebackEnabled 属性。

在 CloudSyncCustomExtensionsApp 下，创建扩展属性并将其分配给 Group 对象：

New-MgApplicationExtensionProperty -ApplicationId $cloudSyncCustomExtApp.Id -Name 'WritebackEnabled' -DataType 'Boolean' -TargetObjects 'Group'

此 cmdlet 将创建一个如下所示 extension_<AppIdWithoutHyphens>_WritebackEnabled的扩展属性。

在 CloudSyncCustomExtensionsApp 下，创建扩展属性并将其分配给 User 对象：

New-MgApplicationExtensionProperty -ApplicationId $cloudSyncCustomExtApp.Id -Name 'EmployeeCode' -DataType 'String' -TargetObjects 'User'

此 cmdlet 将创建一个如下所示 extension_<AppIdWithoutHyphens>_EmployeeCode的扩展属性。检索生成的名称，因为在添加属性映射时需要它：

$userExtension = Get-MgApplicationExtensionProperty -ApplicationId $cloudSyncCustomExtApp.Id |
    Where-Object Name -Like '*_EmployeeCode' | Select-Object -First 1

$userExtensionName = $userExtension.Name
$userExtensionName

设置扩展值

组
用户

为 Marketing 组的新建属性设置一个值。

获取扩展属性：

$gwbEnabledExtAttrib = Get-MgApplicationExtensionProperty -ApplicationId $cloudSyncCustomExtApp.Id |
    Where-Object {$_.Name -Like '*WritebackEnabled'} | Select-Object -First 1
$gwbEnabledExtName = $gwbEnabledExtAttrib.Name

获取Marketing组：

$marketingGrp = Get-MgGroup -ConsistencyLevel eventual -Filter "DisplayName eq 'Marketing'"

为营销组设置值 True：

Update-MgGroup -GroupId $marketingGrp.Id -AdditionalProperties @{$gwbEnabledExtName = $true}

若要确认，请阅读属性值：

$marketingGrp = Get-MgGroup -ConsistencyLevel eventual -Filter "DisplayName eq 'Marketing'" -Property Id,$gwbEnabledExtName
$marketingGrp.AdditionalProperties.$gwbEnabledExtName

在测试用户上设置值：

Update-MgUser -UserId $testUser.Id -AdditionalProperties @{ $userExtensionName = "EMP-1001" }

若要确认，请阅读属性值：

$testUser = Get-MgUser -UserId $testUser.Id -Property "id,displayName,$userExtensionName"
$testUser.AdditionalProperties[$userExtensionName]

在云同步配置中使用扩展

组
用户

请以至少混合身份管理员的身份登录Microsoft Entra 管理中心。
浏览到 Entra ID>Entra Connect>云同步。
选择“新配置”。
选择“Microsoft Entra ID 与 AD 同步”。
在配置屏幕上，选择你的域。选择“创建”。
此时将打开“开始使用”屏幕。在此处，可以继续配置云同步。
在左侧选择“ 范围筛选器”，然后选择“ 组范围>所有组”。
选择 “编辑属性映射 ”并将 目标容器 更改为 OU=Groups,DC=Contoso,DC=com。选择“保存”。
选择 “添加属性范围筛选器”。
键入范围筛选器的名称： Filter groups with Writeback Enabled。
在 “目标属性”下，选择新创建的属性，如下所示 extension_<AppIdWithoutHyphens>_WritebackEnabled。

重要

例如，下拉列表中显示的某些目标属性可能无法用作范围筛选器，因为并非所有extensionAttribute[1-15]属性都可以在Microsoft Entra ID中管理。因此，我们建议为此创建自定义扩展属性。
在 “运算符”下，选择 “IS TRUE”。
选择“ 保存”，然后选择“ 保存”。
使配置保持禁用状态，并返回到该配置。

请以至少混合身份管理员的身份登录Microsoft Entra 管理中心。
浏览到 Entra ID>Entra Connect>云同步。
选择“新建配置”并选择“Microsoft Entra ID AD 同步，或打开现有配置。
选择 Active Directory 域和运行状况良好的预配代理。
在左侧，选择 范围筛选器并配置 用户范围。直接选择测试用户，或选择包含该用户的组。
为用户选择“编辑属性映射”，并将目标容器设置为完整的Active Directory可分辨名称，例如OU=test,DC=Contoso,DC=com。
添加属性映射：

设置 Value

映射类型直接

源属性 extension_<AppIdWithoutHyphens>_EmployeeCode

目标属性 extensionAttribute1或另一个可写Active Directory用户属性
选择“保存”。
将配置保留为禁用状态，直到查看范围、目标容器和映射。

设置	Value
映射类型	直接
源属性	`extension_<AppIdWithoutHyphens>_EmployeeCode`
目标属性	`extensionAttribute1`或另一个可写Active Directory用户属性

测试和验证

组
用户

注释

使用按需预配时，不会自动预配成员。您需要选择要对哪些成员进行测试，且最多只能选择五名成员。

请以至少混合身份管理员的身份登录Microsoft Entra 管理中心。
浏览到 Entra ID>Entra Connect>云同步。

在 “配置”下，选择配置。
在左侧，选择“按需预配”。
在“所选组”框中输入“市场营销”。
从 “所选用户 ”部分，选择 “Lola Jacobson ”和 “John Smith”。
选择“预配”。它应该会成功预配。
现在尝试销售组，并添加 Britta Simon 和 Anna Ringdahl。这不应预配，因为 Sales 组没有设置扩展值。
在 Active Directory 中，应该会看到新创建的 Marketing 组。
现在可以浏览到 Entra ID>Entra Connect>Cloud 同步>概述，查看并启用配置并开始同步。

请以至少混合身份管理员的身份登录Microsoft Entra 管理中心。
浏览到 Entra ID>Entra Connect>云同步。

在 “配置”下，选择配置。
在左侧，选择“按需预配”。
选择测试用户。如果使用了组范围，请选择该组，然后显式选择测试用户。
选择“预配”。
查看导入、范围评估、匹配和导出步骤。

确认该值已写入 Active Directory：

Get-ADUser -Filter "UserPrincipalName -eq '<test-user-UPN>'" -SearchBase "OU=test,DC=Contoso,DC=com" -Properties extensionAttribute1 |
    Select-Object DistinguishedName,extensionAttribute1

预期值为 extensionAttribute1 = EMP-1001。

若要在预配日志中查看结果，请转到 Entra ID监视和运行状况预配日志，然后按测试用户和云同步配置进行筛选。确认：

范围评估已通过。
用户已在 Active Directory 中创建，或与其中的现有用户匹配。
在 “修改的属性”下，目录扩展已映射到 extensionAttribute1。
导出操作成功。

从Active Directory转换的用户的目录扩展

将用户的授权来源转换为 Microsoft Entra ID 时，先前由 Active Directory 管理的属性必须已在 Microsoft Entra ID 中可见，并且显示为目录属性或目录架构扩展。有关前提条件的完整列表，请参阅准备环境以转换用户授权源。

这意味着转换后的用户通常已经具有所需的扩展值，因此你不会为这些属性创建新的扩展。而是根据已包含这些值的扩展进行映射。

由 Microsoft Entra Connect 创建的扩展位于租户架构扩展应用中，并且与 CloudSyncCustomExtensionsApp 一样，支持作为映射源。添加映射的方式与在“ 用户 ”选项卡中相同，选择现有扩展作为源属性。转换授权源时，无需重新注册或重新创建扩展程序。

后续步骤

测试和启用预配

上次更新时间为 2026-10-23