云同步目录扩展和自定义属性映射

将用户帐户从 Microsoft Entra ID 预配到业务线 (LOB)、SaaS 应用或本地应用程序时，Microsoft Entra ID 必须包含创建用户配置文件所需的所有数据（属性）。 可以通过目录扩展来使用你自己的属性扩展 Microsoft Entra ID 中的架构。 借助此功能，你可以使用继续在本地管理的属性来构建 LOB 应用，将用户从 Active Directory 预配到 Microsoft Entra ID 或 SaaS 应用，并使用 Microsoft Entra ID 和 Microsoft Entra ID 治理功能中的扩展属性（如动态成员资格组或预配到 Active Directory 的组）。

有关目录扩展的详细信息，请参阅在声明中使用目录扩展属性、Microsoft Entra Connect 同步：目录扩展和为 Microsoft Entra 应用程序预配同步扩展属性。

可以使用 Microsoft Graph 浏览器查看可用属性。

注意

若要发现新的 Active Directory 扩展属性，需要重启预配代理。 应在创建目录扩展后重启代理。 对于 Microsoft Entra 扩展属性，无需重启代理。

同步 Microsoft Entra 云同步的目录扩展

可以使用目录扩展通过你自己的属性扩展 Microsoft Entra ID 中的同步架构目录定义。

重要

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

针对目录扩展创建应用程序和服务主体

如果不存在具有标识符 URI API://<tenantId>/CloudSyncCustomExtensionsApp 的应用程序，请创建一个，并为该应用程序创建一个服务主体（若不存在）。

1. 检查是否存在标识符 URI API://<tenantId>/CloudSyncCustomExtensionsApp 的应用程序。

   • 使用 Microsoft Graph

   GET /applications?$filter=identifierUris/any(uri:uri eq 'api://<tenantId>/CloudSyncCustomExtensionsApp')
   

   有关详细信息，请参阅获取应用程序

   • 使用 PowerShell

   $tenantId = (Get-MgOrganization).Id
   
   Get-MgApplication -Filter "identifierUris/any(uri:uri eq 'API://$tenantId/CloudSyncCustomExtensionsApp')"
   

   有关详细信息，请参阅 Get-MgApplication

2. 如果应用程序不存在，请使用标识符 URI 创建应用程序 API://<tenantId>/CloudSyncCustomExtensionsApp。

   • 使用 Microsoft Graph

   POST https://graph.microsoft.com/v1.0/applications
   Content-type: application/json
   
   {
    "displayName": "CloudSyncCustomExtensionsApp",
    "identifierUris": ["api://<tenant id>/CloudSyncCustomExtensionsApp"]
   }
   

   有关详细信息，请参阅创建应用程序

   • 使用 PowerShell （注意：从前面的步骤中获取 $tenantId 变量）

   New-MgApplication -DisplayName "CloudSyncCustomExtensionsApp" -IdentifierUris "API://$tenantId/CloudSyncCustomExtensionsApp"
   

   有关详细信息，请参阅 New-MgApplication

3. 检查具有标识符 URI API://<tenantId>/CloudSyncCustomExtensionsApp 的应用程序是否具有服务主体。

   • 使用 Microsoft Graph

   GET /servicePrincipals?$filter=(appId eq '{appId}')
   

   有关详细信息，请参阅获取服务主体

   • 使用 PowerShell （注意：从前面的步骤中获取 $tenantId 变量）

   $appId = (Get-MgApplication -Filter "identifierUris/any(uri:uri eq 'API://$tenantId/CloudSyncCustomExtensionsApp')").AppId
   
   Get-MgServicePrincipal -Filter "AppId eq '$appId'"
   

   有关详细信息，请参阅 Get-MgServicePrincipal

4. 如果服务主体不存在，请为具有标识符 URI 的应用程序创建新的服务主体 API://<tenantId>/CloudSyncCustomExtensionsApp。

   • 使用 Microsoft Graph

   POST https://graph.microsoft.com/v1.0/servicePrincipals
   Content-type: application/json
   
   {
   "appId": 
   "<application appId>"
   }
   

   有关详细信息，请参阅创建 servicePrincipal

   • 使用 PowerShell （注意：从前面的步骤中获取 $appId 变量）

   New-MgServicePrincipal -AppId $appId
   

   有关详细信息，请参阅 New-MgServicePrincipal

5. 在 Microsoft Entra ID 中创建目录扩展。 例如，对于 Group 对象，有一种名为“WritebackEnabled”的类型为布尔的新扩展。

   • 使用 Microsoft Graph

   POST https://graph.microsoft.com/v1.0/applications/<ApplicationId>/extensionProperties
   Content-type: application/json
   
   {
       "name": "WritebackEnabled",
       "dataType": "Boolean",
       "isMultiValued": false,
       "targetObjects": [
           "Group"
       ]
   }    
   

   • 使用 PowerShell （注意：从前面的步骤中获取 $tenantId 变量）

   $appObjId = (Get-MgApplication -Filter "identifierUris/any(uri:uri eq 'API://$tenantId/CloudSyncCustomExtensionsApp')").Id
   
   New-MgApplicationExtensionProperty -ApplicationId $appObjId -Name WritebackEnabled -DataType Boolean -TargetObjects Group
   

可以通过多种不同的方式在 Microsoft Entra ID 中创建目录扩展，如下表所述：

方法	说明	URL
MS Graph	使用 GRAPH 创建扩展	创建 extensionProperty
PowerShell	使用 PowerShell 创建扩展	New-MgApplicationExtensionProperty
使用云同步和 Microsoft Entra Connect	使用 Microsoft Entra Connect 创建扩展	使用 Microsoft Entra Connect 创建扩展属性
自定义要同步的属性	有关自定义要同步的属性的信息	自定义要与 Microsoft Entra ID 同步的属性

使用属性映射来映射目录扩展

如果扩展 Active Directory 以包含自定义属性，可以添加这些属性并将其映射到用户。

若要发现和映射属性，请选择 添加属性映射，并且属性在 源属性下的下拉列表中可用。 填写所需的映射类型，然后选择“应用”。

有关在 Microsoft Entra ID 中添加和更新的新属性的信息，请参阅 user 资源类型，并考虑订阅更改通知。

有关扩展属性的详细信息，请参阅为 Microsoft Entra 应用程序预配同步扩展属性。

更多资源

• 了解 Microsoft Entra 架构和自定义表达式
• Microsoft Entra Connect 同步：目录扩展
• Microsoft Entra 云同步中的特性映射