如何通过 PowerShell 使用 Entra ID 目录扩展

用于自定义 Entra ID 对象存储数据的目录扩展

如果您使用过 PowerShell 来处理 Exchange 邮箱，您可能了解 15 个单值自定义属性和 5 个多值自定义属性。组织可以在选择存储有关邮箱、通讯组列表和其他启用邮件的对象的信息时使用自定义属性。 Entra ID 将邮箱的自定义属性同步到拥有邮箱的用户帐户，并将值存储在 onPremisesExtensionAttributes 属性中。多值自定义属性不会从 Exchange 同步到 Entra ID。

Exchange 中自定义属性的使用多种多样，从存储有关对邮箱执行的某些处理的详细信息到有关邮箱所有者的静态详细信息（如徽章号码）。关键是微软并没有规定组织如何使用自定义属性，这些属性的存在是为了让 Exchange 对客户更有用。

目录扩展与 Entra ID 等效。与 Exchange 自定义属性不同，目录扩展特定于各个租户，并与 Entra ID 注册的应用程序相关联。

听起来很复杂？嗯，实践中更简单，所以让我们使用 Microsoft Graph PowerShell SDK 定义和使用一些目录扩展。不幸的是，微软当前的文档使用 Azure AD 模块，但在查阅目录扩展如何工作的基于图形的描述后，很容易切换到现已弃用的 cmdlet。

创建目录扩展

第一步是创建注册的 Entra ID 应用程序或选择现有的注册应用程序来保存扩展属性。我们可以使用 PowerShell 或通过 Entra ID 管理中心创建新应用程序。需要注意的重要信息是应用程序的标识符（ID 属性），因为创建目录扩展需要它。此代码创建一个新应用程序及其服务主体。

$ExtensionApp = New-MgApplication -DisplayName "Extension App to Store Properties for My Tenant"
New-MgServicePrincipal -AppId $ExtensionApp.AppId

有了应用程序，我们就可以添加一些目录扩展。此示例演示如何向应用程序添加两个目录扩展。第一个目录扩展（“CostCenter”）只能与用户对象一起使用，而另一个目录扩展（“Subsidiary”）可用于用户和组。其他支持的类型包括设备、应用程序和管理单元。目录扩展名中不能包含空格：

$ExtensionProperty1 = New-MgApplicationExtensionProperty -Name "CostCenter" -DataType "String" -TargetObjects "User" -ApplicationId $ExtensionApp.Id
$ExtensionProperty2 = New-MgApplicationExtensionProperty -Name "Subsidiary" -DataType "String" -TargetObjects "User", "Group" -ApplicationId $ExtensionApp.Id

与 PowerShell 变量不同，目录扩展是强类型的。在本例中，两者都被定义为字符串，并且最多可以存储 256 个字符。其他支持的数据类型包括二进制、布尔值、日期时间、整数和大整数。

要检查为注册应用定义的目录扩展集并查看扩展可用于哪些对象，请运行 Get-MgApplicationExtensionProperty cmdlet：

Get-MgApplicationExtensionProperty -ApplicationId $ExtensionApp.Id | Format-Table Name, DataType, TargetObjects

Name                                                  DataType TargetObjects
----                                                  -------- -------------
extension_450c03488bae4eb98cc22699c0b46690_Subsidiary String   {User, Group}
extension_450c03488bae4eb98cc22699c0b46690_CostCenter String   {User}

该文档表示，“所有者”应用程序最多可以保存五个定义（如图 1 所示，文档的这方面可能不正确或过时），并且组织可以为每种资源类型支持最多 100 个目录扩展（例如用户）。

使用目录扩展

要将值写入目录扩展，我们创建一个哈希表来保存要更新的扩展的名称和要分配的值。在此示例中，我们使用刚刚定义的两个目录扩展名和要分配的值填充哈希表。您可以组合不同应用程序拥有的扩展程序。

$Properties = @{}
$Properties.Add('extension_450c03488bae4eb98cc22699c0b46690_CostCenter', "8ZW")
$Properties.Add('extension_450c03488bae4eb98cc22699c0b46690_Subsidiary', "Contoso U.S.A")

$UserId = (Get-MgUser -UserId [email protected]).Id
Update-MgUser -UserId $UserId -AdditionalProperties $Properties

要检索存储在目录扩展中的值，请在运行 Get-MgUser 时指定扩展名称：

$User = Get-MgUser -UserId $UserId -Property ` extension_450c03488bae4eb98cc22699c0b46690_CostCenter,
extension_450c03488bae4eb98cc22699c0b46690_Subsidiary

$User.AdditionalProperties | Format-List

Key   : @odata.context
Value : https://graph.microsoft.com/v1.0/$metadata#users(extension_450c03488bae4eb98cc22699c0b46690_Subsidiary,extension_450c03488bae4eb98cc22699c0b46690_CostCenter)/$entity

Key   : extension_450c03488bae4eb98cc22699c0b46690_CostCenter
Value : 8ZW

Key   : extension_450c03488bae4eb98cc22699c0b46690_Subsidiary
Value : Contoso U.S.A

编写脚本时，通过查找 additionalProperties 属性中保存的数据，可以更轻松地检索目录扩展的值。例如：

$User.AdditionalProperties['extension_450c03488bae4eb98cc22699c0b46690_Subsidiary']
Contoso U.S.A

目录扩展名是可过滤的。这些示例演示如何使用过滤器查找目录扩展中具有特定值的所有用户帐户：

[array]$Users = Get-MgUser -Filter "extension_450c03488bae4eb98cc22699c0b46690_CostCenter eq '8ZW'"
[array]$Users = Get-MgUser -Filter "extension_450c03488bae4eb98cc22699c0b46690_SeniorityDate ge '1983-10-02T23:59:00'"
[array]$Users = Get-MgUser -Filter "extension_450c03488bae4eb98cc22699c0b46690_WorkRemote eq 'true'"

如上所述，Update-MgUser cmdlet 更新存储在目录扩展中的值。该规则的例外情况是当您想要将空值写入目录扩展时。 Update-MgUser cmdlet 目前无法执行此操作（无法处理 $Null 特殊变量是 Graph SDK 的缺点之一）。解决方法是传递包含目录扩展名称和 $Null 值的哈希表，并使用该表作为由 Invoke-MgGraphRequest cmdlet 运行的补丁请求的输入：

$PropertyNull = @{}
$PropertyNull.add("extension_450c03488bae4eb98cc22699c0b46690_Subsidiary", $Null)

Invoke-MgGraphRequest -Method PATCH -Uri "https://graph.microsoft.com/v1.0/users/[email protected]" -Body $PropertyNull

删除目录扩展

会犯错误，有时需要删除目录扩展名。为此，首先找到扩展的标识符：

Get-MgApplicationExtensionProperty -ApplicationId $ExtensionApp.Id | Format-Table Id, Name

Id                                   Name
--                                   ----
cad8d83d-eada-47c7-9bf4-5c9ef87beed9 extension_450c03488bae4eb98cc22699c0b46690_HiringManager
b4948d37-ce31-4214-b885-8b44f5fbefe3 extension_450c03488bae4eb98cc22699c0b46690_RetirementDate
6af6c7fe-a516-4b3b-ba28-b80d0b91bd9a extension_450c03488bae4eb98cc22699c0b46690_BadgeNumber
de02f69a-d599-4f68-9cb1-9a2b07e8c395 extension_450c03488bae4eb98cc22699c0b46690_LeaveAllowance
7ba15153-d8b6-4ffc-8265-edd8ede66cbf extension_450c03488bae4eb98cc22699c0b46690_Subsidiary
5ce0873c-dc0f-4df0-bdeb-a0db895d5c2b extension_450c03488bae4eb98cc22699c0b46690_CostCenter

然后运行Remove-MgApplicationExtensionProperty cmdlet 以删除目录扩展。在此示例中，我将删除存储子公司信息的目录扩展名。在删除目录扩展之前，cmdlet 不会提示确认。删除它会消除扩展中保存的其他 Entra ID 对象的任何数据，因此请务必在运行 cmdlet 之前继续操作。

Remove-MgApplicationExtensionProperty -ApplicationId $ExtensionApp.Id -ExtensionPropertyId 7ba15153-d8b6-4ffc-8265-edd8ede66cbf

可以重新创建同名的目录扩展。但是，新的目录扩展具有不同的标识符，并且不会恢复删除其他目录扩展时删除的数据。

值得考虑目录扩展

在将数据存储在自定义属性中时，Microsoft 租户有很多选择。 Exchange 自定义属性可供使用 Exchange Online 的每个租户使用和访问，但您只能使用 15 个属性。 Entra ID 目录扩展不依赖于任何其他应用程序，您可以定义更多扩展（最多达到前面提到的限制），并且它们支持更多对象类型（请参阅此比较以获取一些有用的背景信息）。您现在可能不需要使用目录扩展，但您永远不知道将来会发生什么。

Active Directory 的网络安全风险管理

了解如何通过这些网络安全风险管理解决方案预防 AD 攻击并从中恢复。