为 Microsoft Entra 应用程序预配同步扩展属性

项目
04/15/2024

将用户帐户从 Microsoft Entra ID 预配到 SaaS 应用或本地应用程序时，Microsoft Entra ID 必须包含创建用户配置文件所需的所有数据（属性）。在为用户预配自定义属性映射时，你可能会发现要映射的属性不会显示在 Microsoft Entra ID 的源属性列表中。本文介绍了如何添加缺少的属性。

确定需要添加扩展的位置

将在本地 Active Directory 或 Microsoft Entra ID 中开始添加应用程序所需的缺失属性，具体取决于用户帐户所在的位置以及将其引入 Microsoft Entra ID 的方式。

首先，确定 Microsoft Entra 租户中的哪些用户需要访问应用程序，因此需要将这些用户纳入范围，以预配到应用程序中。

接下来，确定属性源以及将这些用户引入 Microsoft Entra ID 的方式的拓扑。

属性源	拓扑	所需步骤
HR 系统	HR 系统中的工作人员作为用户预配到 Microsoft Entra ID 中。	在 Microsoft Entra ID 中创建扩展属性。更新 HR 入站映射，以基于 HR 系统填充 Microsoft Entra ID 用户的扩展属性。
HR 系统	HR 系统中的工作人员作为用户预配到 Windows Server AD 中。 Microsoft Entra Connect 云同步将他们同步到 Microsoft Entra ID 中。	扩展 AD 架构（如有必要）。在 Microsoft Entra ID 中使用云同步创建扩展属性。更新 HR 入站映射，以基于 HR 系统填充 AD 用户的扩展属性。
HR 系统	HR 系统中的工作人员作为用户预配到 Windows Server AD 中。 Microsoft Entra Connect 将他们同步到 Microsoft Entra ID 中。	扩展 AD 架构（如有必要）。使用 Microsoft Entra Connect 在 Microsoft Entra ID 中创建扩展属性。更新 HR 入站映射，以基于 HR 系统填充 AD 用户的扩展属性。

如果组织的用户已在本地 Active Directory 中，或者你正在 Active Directory 中创建他们，则必须将用户从 Active Directory 同步到 Microsoft Entra ID。可以使用 Microsoft Entra Connect 或 Microsoft Entra Connect 云同步同步用户和属性。

请与本地 Active Directory 域管理员核实所需的属性是否是 AD DS 架构 User 对象类的一部分；如果不是，请在这些用户拥有帐户的域中扩展 Active Directory 域服务架构。
配置 Microsoft Entra Connect 或 Microsoft Entra Connect 云同步，将用户与其扩展属性从 Active Directory 同步到 Microsoft Entra ID。这两个解决方案都会自动将某些属性（但不是所有属性）同步到 Microsoft Entra ID。另外，使用 Graph API 时，可能不会公开默认情况下同步的某些属性（例如 sAMAccountName）。在这些情况下，可以使用 Microsoft Entra Connect 目录扩展功能将属性同步到 Microsoft Entra ID 或使用 Microsoft Entra Connect 云同步。这样，该属性就会对图形 API 和 Microsoft Entra 预配服务可见。
如果本地 Active Directory 中的用户尚无所需属性，则需要在 Active Directory 中更新用户。此更新可以通过从 Workday、SAP SuccessFactors 中读取属性来完成；如果使用其他 HR 系统，也可使用入站 HR API 来完成。
等待 Microsoft Entra Connect 或 Microsoft Entra Connect 云同步将在 Active Directory 架构中进行的更新和 Active Directory 用户同步到 Microsoft Entra ID。

或者，如果需要访问应用程序的用户都不是来自本地 Active Directory，则需要先在 Microsoft Entra ID 中使用 PowerShell 或 Microsoft Graph 创建架构扩展，然后再配置应用程序预配。

以下部分概述了如何为具有纯云用户的租户和具有 Active Directory 用户的租户创建扩展属性。

在具有纯云用户的租户中创建扩展属性

你可以使用 Microsoft Graph 和 PowerShell 为 Microsoft Entra ID 中的用户扩展用户架构。如果你有需要该属性的用户，并且这些用户都不是源自本地 Active Directory 或从本地 Active Directory 同步而来，则需要执行此步骤。（如果有 Active Directory，请继续阅读下面介绍如何使用 Microsoft Entra Connect 目录扩展功能将属性同步到 Microsoft Entra ID 的部分。）

创建架构扩展后，当下次访问 Microsoft Entra 管理中心内的预配页时，系统在大多数情况下会自动发现这些扩展属性。

当你的服务主体超过 1000 个时，你可能会发现源属性列表中缺少扩展。如果你创建的属性未自动显示，请验证是否已创建该属性，然后手动将其添加到你的架构。若要验证是否已创建该属性，请使用 Microsoft Graph 和 Graph 浏览器。若要手动将其添加到架构，请参阅编辑受支持属性的列表。

使用 Microsoft Graph 为纯云用户创建扩展属性

你可以使用 Microsoft Graph 扩展 Microsoft Entra 用户的架构。

首先，列出你的租户中的应用，获取你正在处理的应用的 ID。若要了解详细信息，请参阅列出 extensionProperties。

GET https://graph.microsoft.com/v1.0/applications

接下来，创建扩展属性。将下面的 ID 属性替换为在上一步骤中检索到的 ID。你需要使用“ID”属性而不是“appId”属性。若要了解详细信息，请参阅 [Create extensionProperty]/graph/api/application-post-extensionproperty)。

POST https://graph.microsoft.com/v1.0/applications/{id}/extensionProperties
Content-type: application/json

{
    "name": "extensionName",
    "dataType": "string",
    "targetObjects": [
      "User"
    ]
}

上一请求创建了一个 extension_appID_extensionName 格式的扩展属性。现在，你可以使用此扩展属性更新用户。若要了解详细信息，请参阅更新用户。

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
  "extension_inputAppId_extensionName": "extensionValue"
}

最后，验证用户的属性。若要了解详细信息，请参阅获取用户。默认情况下，Graph v1.0 不返回用户的任何目录扩展属性，除非在请求中将属性指定为要返回的属性之一。

GET https://graph.microsoft.com/v1.0/users/{id}?$select=displayName,extension_inputAppId_extensionName

使用 PowerShell 为纯云用户创建扩展属性

可以使用 PowerShell 创建自定义扩展。

注意

自 2024 年 3 月 30 日起，Azure AD 和 MSOnline PowerShell 模块已弃用。若要了解详细信息，请阅读有关弃用的更新。在此日期之后，对这些模块的支持仅限于到 Microsoft Graph PowerShell SDK 的迁移帮助和安全性修复。弃用的模块将持续运行至 2025 年 3 月 30 日。

我们建议迁移到 Microsoft Graph PowerShell，以便与 Microsoft Entra ID（以前称为 Azure AD）进行交互。有关常见迁移问题，请参阅迁移常见问题解答。 注意：2024 年 6 月 30 日之后，MSOnline 版本 1.0.x 可能会遇到中断。

#Connect to your Azure AD tenant
Connect-AzureAD

#Create an application (you can instead use an existing application if you would like)
$App = New-AzureADApplication -DisplayName “test app name” -IdentifierUris https://testapp

#Create a service principal
New-AzureADServicePrincipal -AppId $App.AppId

#Create an extension property
New-AzureADApplicationExtensionProperty -ObjectId $App.ObjectId -Name “TestAttributeName” -DataType “String” -TargetObjects “User”

（可选）可以测试是否可以为纯云用户设置扩展属性。

#List users in your tenant to determine the objectid for your user
Get-AzureADUser

#Set a value for the extension property on the user. Replace the objectid with the ID of the user and the extension name with the value from the previous step
Set-AzureADUserExtension -objectid aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb -ExtensionName “extension_6552753978624005a48638a778921fan3_TestAttributeName”

#Verify that the attribute was added correctly.
Get-AzureADUser -ObjectId bbbbbbbb-1111-2222-3333-cccccccccccc | Select -ExpandProperty ExtensionProperty

使用云同步创建扩展属性

如果 Active Directory 中有用户并且正在使用 Microsoft Entra Connect 云同步，则当你添加新映射时，云同步会自动在本地 Active Directory 中发现你的扩展。如果使用的是 Microsoft Entra Connect 同步，请继续阅读下一部分：使用 Microsoft Entra Connect 创建扩展属性。

使用以下步骤自动发现这些属性并设置到 Microsoft Entra ID 的相应映射。

至少以混合标识管理员身份登录到 Microsoft Entra 管理中心。
浏览到“标识”>“混合管理”>“Microsoft Entra Connet”>“Cloud sync”。
选择希望添加扩展属性和映射的配置。
在“管理属性”下，选择“单击以编辑映射”。
选择“添加属性映射”。会自动发现属性。
新属性将在“源属性”下的下拉列表中提供。
填写所需的映射类型，然后选择“应用”。

有关详细信息，请参阅 Microsoft Entra Connect 云同步中的自定义属性映射。

使用 Microsoft Entra Connect 创建扩展属性

如果要访问应用程序的用户来自本地 Active Directory，则必须将属性与用户从 Active Directory 同步到 Microsoft Entra ID。如果使用 Microsoft Entra Connect，则需要在配置应用程序预配之前执行以下任务。

请与本地 Active Directory 域管理员核实所需的属性是否是 AD DS 架构 User 对象类的一部分；如果不是，请在这些用户拥有帐户的域中扩展 Active Directory 域服务架构。
打开 Microsoft Entra Connect 向导，选择“任务”，然后选择“自定义同步选项”。
以混合标识管理员身份登录。
在“可选功能”页上，选择“目录扩展属性同步” 。
选择要扩展到 Microsoft Entra ID 的属性。

注意

“可用属性”下的搜索区分大小写。
完成 Microsoft Entra Connect 向导，并允许运行完全同步周期。周期完成时，架构被扩展，且新值在本地 AD 和 Microsoft Entra ID 之间同步。

注意

目前，不支持预配本地 AD 中的参考属性（如 managedby 或 DN/DistinguishedName）的功能。可以在 User Voice 上请求此功能。

填充和使用新属性

在 Microsoft Entra 管理中心内编辑用户属性映射以进行单一登录或从 Microsoft Entra ID 到应用程序的预配时，“源属性”列表现在会包含 <attributename> (extension_<appID>_<attributename>) 格式的已添加属性，其中 appID 是租户中占位符应用程序的标识符。选择该属性并将其映射到用于预配的目标应用程序。

Microsoft Entra Connect 向导的“目录扩展”选择页

然后，在启用应用程序的预配之前，需要使用所需的属性填充这些分配给应用程序的用户。如果该属性不是源自 Active Directory，则可通过五种方法批量填充用户：

如果属性源自 HR 系统，并且你要将该 HR 系统中的工作人员预配为 Active Directory 中的用户，则配置从 Workday、SAP SuccessFactors 到 Active Directory 属性的映射，或者如果使用其他 HR 系统，则使用入站 HR API 进行配置。然后，等待 Microsoft Entra Connect 或 Microsoft Entra Connect 云同步将在 Active Directory 架构中进行的更新和 Active Directory 用户同步到 Microsoft Entra ID。
如果属性源自 HR 系统，并且未使用 Active Directory，则可以配置从 Workday、SAP SuccessFactors 到 Microsoft Entra 用户属性的映射，或者如果使用其他系统，则通过入站 API 进行配置。
如果属性源自另一个本地系统，则可以配置适用于 Microsoft Graph 的 MIM 连接器来创建或更新 Microsoft Entra 用户。
如果属性源自用户自身，则可以在权利管理目录中包含特性要求，让用户在请求访问应用程序时提供特性值。
对于所有其他情况，自定义应用程序可以通过 Microsoft Graph API 更新用户。

后续步骤

定义谁在预配范围中

通过