同步 Microsoft Entra 应用程序配置的扩展属性

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

确定需要添加扩展的位置

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

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

接下来，确定属性的源和拓扑，了解如何将这些用户引入 Microsoft Entra ID。

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

1. 请与本地 Active Directory 域管理员检查所需属性是否是 AD DS 架构 User 对象类的一部分，如果不是，请在这些用户拥有帐户的域中 扩展 Active Directory 域服务架构 。
2. 配置 Microsoft Entra Connect 或 Microsoft Entra Connect 云同步，以便将用户与其扩展属性从 Active Directory 同步到 Microsoft Entra ID。 这两种解决方案都会自动将某些属性同步到 Microsoft Entra ID，但并非所有属性。 此外，默认情况下同步的某些属性（例如 sAMAccountName）可能不会使用图形 API 公开。 在这些情况下，可以使用 Microsoft Entra Connect 目录扩展功能将属性同步到 Microsoft Entra ID ，或使用 Microsoft Entra Connect 云同步。这样，图形 API 和 Microsoft Entra 预配服务即可看到该属性。
3. 如果本地 Active Directory 中的用户还没有所需的属性，则需要更新 Active Directory 中的用户。 可以使用 入站 HR API 完成此更新。
4. 等待 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，请继续阅读以下部分，了解如何 使用 Microsoft Entra Connect 目录扩展功能将属性同步到 Microsoft Entra ID。

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

如果服务主体超过 1,000 个，则可能会在源属性列表中发现缺少扩展。 如果已创建的属性未自动显示，请验证是否已创建该属性并将其手动添加到架构。 若要验证是否已创建，请使用 Microsoft Graph。 若要手动将其添加到架构，请参阅 编辑受支持的属性列表。

使用 Microsoft Graph 为仅限云的用户创建扩展属性

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

首先，列出您租户中的应用程序，以获取您要处理的应用程序的 ID。 若要了解详细信息，请参阅 列表 extensionProperties。

GET https://microsoftgraph.chinacloudapi.cn/v1.0/applications

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

POST https://microsoftgraph.chinacloudapi.cn/v1.0/applications/{id}/extensionProperties
Content-type: application/json

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

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

PATCH https://microsoftgraph.chinacloudapi.cn/v1.0/users/{id}
Content-type: application/json

{
  "extension_inputAppId_extensionName": "extensionValue"
}

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

GET https://microsoftgraph.chinacloudapi.cn/v1.0/users/{id}?$select=displayName,extension_inputAppId_extensionName

使用 PowerShell 为仅限云的用户创建扩展属性

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

#Connect to your Entra tenant
Connect-Entra -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes 'Application.ReadWrite.All'

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

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

#Create an extension property
New-EntraApplicationExtensionProperty -ApplicationId $App.ObjectId -Name "TestAttributeName" -DataType "String" -TargetObjects "User"

（可选）可以测试是否可以在仅限云的用户上设置扩展属性。

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

#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-EntraUserExtension -ObjectId aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb -ExtensionName "extension_6552753978624005a48638a778921fan3_TestAttributeName"

#Verify that the attribute was added correctly.
Get-EntraUser -ObjectId aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb | Select -ExpandProperty ExtensionProperty

使用云同步创建扩展属性

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

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

1. 请以至少混合身份管理员的身份登录Microsoft Entra 管理中心。
2. 浏览到 Entra ID>Entra Connect>云同步。
3. 选择要添加扩展属性和映射的配置。
4. 在管理属性下，选择单击以编辑映射。
5. 选择 “添加属性映射”。 会自动发现这些属性。
6. 源属性下的下拉列表中提供了新 属性。
7. 填写所需的映射类型，然后选择“应用”。

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

使用 Microsoft Entra Connect 创建扩展属性

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

1. 请与本地 Active Directory 域管理员检查所需属性是否是 AD DS 架构 User 对象类的一部分，如果不是，请在这些用户拥有帐户的域中 扩展 Active Directory 域服务架构 。

2. 打开Microsoft Entra Connect 向导，选择“任务”，然后选择“ 自定义同步选项”。

3. 以 混合标识管理员身份登录。

4. 在 “可选功能 ”页上，选择 “目录扩展属性同步”。

5. 选择要扩展到 Microsoft Entra ID 的属性。

   注释

   可用属性下的搜索区分大小写。

6. 完成 Microsoft Entra Connect 向导，并允许运行一次完整的同步周期。 完成周期后，架构会扩展，并且新值在本地 AD 与 Microsoft Entra ID 之间同步。

填充和使用新属性

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

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

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

后续步骤

• 定义预配范围内的人员