教程 - 在 Microsoft Entra ID 中为 SaaS 应用程序自定义用户预配属性映射

Microsoft Entra ID 为非Microsoft SaaS 应用程序（如 Salesforce、G Suite 等）的用户预配提供支持。如果为非Microsoft SaaS 应用程序启用用户预配，Microsoft Entra 管理中心会通过属性映射控制其属性值。

在开始之前，请确保熟悉应用管理和 单一登录（SSO） 概念。查看以下链接：

Microsoft Entra 用户对象和每个 SaaS 应用的用户对象之间有一组预配置的属性和属性映射。某些应用管理其他类型的对象以及用户，例如组。

可以根据业务需求自定义默认的属性映射。因此，可以更改或删除现有属性映射或者创建新的属性映射。

注释

除了通过 Microsoft Entra 接口配置属性映射之外，还可以查看、下载和编辑架构的 JSON 表示形式。

编辑用户属性映射

按照以下步骤访问用户预配的映射功能：

至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。
浏览到 Entra ID>企业应用。
系统显示所有已配置的应用（包括从库中添加的应用）的列表。
选择要加载其应用管理窗格的任何应用，可在其中查看报表和管理应用设置。
选择 “预配 ”以管理所选应用的用户帐户预配设置。
展开映射，以查看和编辑 Microsoft Entra ID 与目标应用程序之间的用户属性。如果目标应用程序支持它，此部分允许你选择配置组和用户帐户的预配。
选择 “映射 ”配置以打开相关的 “属性映射” 屏幕。 SaaS 应用程序需要某些属性映射才能正常运行。对于必需的属性， “删除” 功能不可用。

在此屏幕截图中，可以看到 Salesforce 中托管对象的 Username 属性已填充链接Microsoft Entra 对象的 userPrincipalName 值。

注释

清除创建不会影响现有用户。如果未选择 “创建” ，则无法创建新用户。
选择现有的 属性映射 以打开 “编辑属性” 屏幕。在这里，可以编辑在 Microsoft Entra ID 与目标应用程序之间流动的用户属性。

了解属性映射类型

使用属性映射，可以控制如何在非Microsoft SaaS 应用程序中填充属性。支持四种不同的映射类型：

Direct - 目标属性使用 Microsoft Entra ID 中链接对象的属性值填充。
常量 - 目标属性使用指定的特定字符串填充。
表达式 - 基于类似脚本的表达式的结果填充目标属性。有关表达式的更多信息，请参阅在 Microsoft Entra ID 中编写 Attribute-Mappings 表达式。
无 - 目标属性未修改。但是，如果目标属性为空，则使用指定的默认值填充。

除了这四种基本类型外，自定义属性映射还支持可选 默认值 分配的概念。当 Microsoft Entra ID 或目标对象中没有值时，默认值赋值会确保目标属性被填充值。最常见的配置是将此项留空。有关映射属性的详细信息，请参阅应用程序预配在 Microsoft Entra ID 中的工作原理。

理解属性映射的性质

在上一部分中，你被介绍了属性映射类型属性。除了此属性，属性映射还支持属性：

源属性 - 源系统中的用户属性（示例：Microsoft Entra ID）。
目标属性 - 目标 系统中的用户属性（示例：ServiceNow）。
默认值（如果为 null（可选） - 如果源属性为 null，则传递给目标系统的值。仅当创建用户时，才会预配此值。更新现有用户时未预配“null 时的默认值”。例如，在创建用户时，使用表达式为职务添加默认值：Switch(IsPresent([jobTitle]), "DefaultValue", "True", [jobTitle]) 有关表达式的详细信息，请参阅参考，了解如何在 Microsoft Entra ID 中编写属性映射的表达式。
使用此属性匹配对象 - 是否应使用此映射来唯一标识源系统和目标系统之间的用户。在 Microsoft Entra ID 中，用于 userPrincipalName 或邮件属性，并映射到目标应用程序的用户名字段中。
匹配优先级 - 可以设置多个匹配属性。当存在多个时，会按照此字段定义的顺序进行评估。一旦找到匹配，就不会进一步评估其他匹配属性。尽管您可以根据需要设置任意数量的匹配属性，但请考虑您用作匹配的属性是否真正独一无二，并且确实需要用作匹配属性。一般情况下，客户在其配置中有一个或两个匹配的属性。
应用映射。
- 始终 - 在用户创建和更新操作上应用此映射。
- 仅在创建期间 - 仅在用户创建操作上应用此映射。

匹配源系统和目标系统中的用户

Microsoft Entra 预配服务可以部署在“绿色字段”方案中（其中目标系统中不存在用户）和“brownfield”方案（其中用户已存在于目标系统中）。为了支持这两种方案，预配服务使用匹配属性的概念。通过匹配属性，可以确定如何唯一标识源中的用户，并匹配目标中的用户。在规划部署过程中，确定可用于唯一标识源系统和目标系统中的用户的属性。注意事项：

匹配属性应是唯一的： 客户通常使用 userPrincipalName、mail 或对象 ID 等属性作为匹配属性。
多个属性可用作匹配属性： 可以定义在匹配用户时要计算的多个属性及其计算顺序（在 UI 中定义为匹配优先级）。例如，如果将三个属性定义为匹配属性，并且评估前两个属性后用户将唯一匹配，则服务不会评估第三个属性。服务按指定的顺序评估匹配属性，并在找到匹配项时停止评估。
源和目标中的值不必完全匹配： 目标中的值可以是源中值的函数。因此，可能在源中具有 emailAddress 属性，而在目标中具有 userPrincipalName，并通过 emailAddress 属性的某个函数进行匹配，该函数将某些字符替换为某个常量值。
不支持基于属性组合进行匹配： 大多数应用程序不支持基于两个属性进行查询。因此，无法基于属性的组合进行匹配。可以连续评估单个属性。
所有用户必须具有至少一个匹配属性的值： 如果定义一个匹配属性，则所有用户必须在源系统中具有该属性的值。例如，如果将 userPrincipalName 定义为匹配属性，则所有用户都必须具有 userPrincipalName。如果定义了多个匹配属性（例如，extensionAttribute1 和 mail），则并非所有用户必须具有相同的匹配属性。一个用户可以具有 extensionAttribute1，但不能发送邮件，而另一个用户可以有邮件，但没有 extensionAttribute1。
目标应用程序必须支持对匹配属性进行筛选： 应用程序开发人员允许筛选其用户或组 API 上的一部分属性。对于库中的应用程序，我们确保默认属性映射适用于目标应用程序的 API 支持筛选的属性。更改目标应用程序的默认匹配属性时，请检查非Microsoft API 文档，以确保可以筛选该属性。

编辑组属性映射

所选数量的应用程序（如 ServiceNow、Box 和 G Suite）支持预配组和用户对象的功能。组对象可以包含组属性，例如显示名称和电子邮件别名，以及组成员。

示例显示了 ServiceNow 具有已预配的组和用户对象

可以选择启用或禁用组预配，方法是选择“ 映射”下的组映射，并将“ 已启用” 设置为“ 属性映射 ”屏幕中所需的选项。

作为组对象的一部分预配的属性可以像前面所述的用户对象一样自定义。

小窍门

组对象（属性和成员）的预配置与将组分配到应用程序是两个不同的概念。可以将组分配给应用程序，但只能预配组中包含的用户对象。在分配中使用组时，无需预配完整的组对象。

编辑支持的属性列表

预配置给定应用程序支持的用户属性。大多数应用程序的用户管理 API 不支持架构发现。因此，Microsoft Entra 预配服务无法通过调用应用程序来动态生成受支持的属性列表。

但是，某些应用程序支持自定义属性，Microsoft Entra 预配服务可以读取和写入自定义属性。若要在Microsoft Entra 管理中心输入其定义，请在“属性映射”屏幕底部选中“显示高级选项”复选框，然后选择应用的“编辑属性列表”。

支持自定义属性列表的应用程序和系统包括：

Salesforce
ServiceNow
Microsoft Entra ID（Microsoft Entra ID 图形 API 默认属性和自定义目录扩展受支持）。有关创建扩展的详细信息，请参阅同步Microsoft Entra 应用程序预配的扩展属性，以及有关在 Microsoft Entra ID 中预配的已知问题
支持跨域标识系统（SCIM） 2.0 的应用

注释

仅建议那些已经自定义其应用程序和系统架构的管理员编辑支持的属性列表，并且需具备对其自定义属性定义方式的第一手知识，或者在 Microsoft Entra 管理中心 UI 中未自动显示源属性的情况下进行编辑。这有时需要熟悉应用程序或系统提供的 API 和开发人员工具。默认情况下，编辑支持属性列表的功能已锁定，但客户可以通过导航到以下 URL 来启用该功能： https://portal.azure.cn/?Microsoft_AAD_Connect_Provisioning_forceSchemaEditorEnabled=true 然后，可以导航到应用程序以查看属性列表。

注释

当Microsoft Entra ID 中的目录扩展属性不会在属性映射下拉列表中自动显示时，可以手动将其添加到“Microsoft Entra 属性列表”。手动将 Microsoft Entra 目录扩展属性添加到预配应用时，请注意，目录扩展属性名称区分大小写。例如：如果有一个名为extension_53c9e2c0exxxxxxxxxxxxxxxx_acmeCostCenter的目录扩展属性，请确保按照目录中定义的相同格式输入它。不支持预配多值目录扩展属性。

编辑支持的属性列表时，会提供以下属性：

名称 - 在目标对象的架构中定义的属性的系统名称。
类型 - 属性存储的数据类型，如目标对象的架构中定义，可以是下列类型之一。
- 二进制 - 属性包含二进制数据。
- 布尔型 - 属性包含 True 或 False 值。
- DateTime - 属性包含日期字符串。
- Integer - 属性包含整数。
- 引用 - 属性包含一个 ID，该 ID 引用存储在目标应用程序中另一个表中的值。
- 字符串 - 属性包含文本字符串。
主键？ - 属性是否定义为目标对象的架构中的主键字段。
Required? - 是否需要在目标应用程序或系统中填充属性。
多重数值？ - 特性是否支持多个值。
确切情况？ - 是否以区分大小写的方式计算属性值。
API 表达式 - 除非文档指示使用特定预配连接器，否则请勿使用。
引用的对象属性 - 如果是引用类型属性，则此菜单允许在包含与属性关联的值的目标应用程序中选择表和属性。例如，如果你有一个名为“Department”的属性，其存储值引用了单独的“Departments”表中的对象，则可以选择 Departments.Name。给定应用程序支持的引用表和主 ID 字段已预配置，无法使用 Microsoft Entra 管理中心进行编辑。但是，可以使用 Microsoft 图形 API 对其进行编辑。

将自定义扩展属性预配到符合 SCIM 的应用程序

SCIM 注释请求（RFC）定义核心用户和组架构，同时允许扩展架构以满足应用程序的需求。若要向 SCIM 应用程序添加自定义属性，请执行以下操作：

至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。
浏览到 Entra ID>企业应用。
选择应用程序，然后选择“ 预配”。
在 “映射”下，选择要为其添加自定义属性的对象（用户或组）。
在页面底部，选择“显示高级选项”。
选择“编辑 AppName 的属性列表”。
在属性列表底部，在提供的字段中输入有关自定义属性的信息。然后选择 “添加属性”。

对于 SCIM 应用程序，属性名称必须遵循示例中所示的模式。可以根据应用程序的要求自定义“CustomExtensionName”和“CustomAttribute”，例如：urn：ietf：params：scim：schemas：extension：CustomExtensionName：2.0：User：CustomAttribute

这些说明仅适用于已启用 SCIM 的应用程序。 ServiceNow 和 Salesforce 等应用程序不使用 SCIM 与 Microsoft Entra ID 集成，因此在添加自定义属性时不需要此特定命名空间。

自定义属性不能是引用属性、多值或复杂类型属性。自定义多值和复杂类型的扩展属性目前仅支持库中的应用程序。示例中省略自定义扩展架构标头，因为它不会在来自 Microsoft Entra SCIM 客户端的请求中发送。

具有扩展属性的用户的示例表示形式：

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "userName": "bjensen",
  "id": "48af03ac28ad4fb88478",
  "externalId": "bjensen",
  "name": {
    "formatted": "Ms. Barbara J Jensen III",
    "familyName": "Jensen",
    "givenName": "Barbara"
  },
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "701984",
    "costCenter": "4130",
    "organization": "Universal Studios",
    "division": "Theme Park",
    "department": "Tour Operations",
    "manager": {
      "value": "26118915-6090-4610-87e4-49d8ca9f808d",
      "$ref": "../Users/26118915-6090-4610-87e4-49d8ca9f808d",
      "displayName": "John Smith"
    }
  },
  "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User": {
    "CustomAttribute": "701984",
  },
  "meta": {
    "resourceType": "User",
    "created": "2010-01-23T04:56:22Z",
    "lastModified": "2011-05-13T04:42:34Z",
    "version": "W\/\"3694e05e9dff591\"",
    "location": "https://example.com/v2/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
  }
}

为 SCIM 应用预配角色

使用示例中的步骤将用户的应用程序角色预配到应用程序。说明特定于自定义 SCIM 应用程序。对于 Salesforce 和 ServiceNow 等展览型应用程序，请使用预定义的角色映射。要点描述如何将 AppRoleAssignments 属性转换为您的应用程序期望的格式。

将 Microsoft Entra ID 中的 appRoleAssignment 映射到应用程序中的角色需要通过表达式来转换相关属性。 appRoleAssignment 属性 不应直接映射到 角色属性，而无需使用表达式分析角色详细信息。

注释

从企业应用程序预配角色时，SCIM 标准以不同的方式定义企业用户角色属性。有关详细信息，请参阅在 Microsoft Entra ID 中规划和实施 SCIM 终结点的预配。

单一应用角色分配

何时使用： 使用 SingleAppRoleAssignment 表达式为用户预配单个角色并指定主角色。

如何配置： 使用描述的步骤导航到属性映射页，并使用 SingleAppRoleAssignment 表达式映射到角色属性。有三个角色属性可供选择（roles[primary eq "True"].display和roles[primary eq "True"].typeroles[primary eq "True"].value）。可以选择在映射中包含任何或所有角色属性。如果要包含多个映射，只需添加一个新映射并将其作为目标属性进行添加。

添加单个应用角色分配

要考虑的事项

确保未向用户分配多个角色。不能保证预配了哪个角色。
检查SingleAppRoleAssignments属性。该属性与设置范围 Sync All users and groups不兼容。

示例请求（POST）

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "externalId": "alias",
  "userName": "alias@contoso.partner.onmschina.cn",
  "active": true,
  "displayName": "First Name Last Name",
  "meta": {
    "resourceType": "User"
  },
  "roles": [
    {
      "primary": true,
      "type": "WindowsAzureActiveDirectoryRole",
      "value": "Admin"
    }
  ]
}

示例输出（PATCH）

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "Add",
      "path": "roles",
      "value": [
        {
          "value": "{\"id\":\"06b07648-ecfe-589f-9d2f-6325724a46ee\",\"value\":\"25\",\"displayName\":\"Role1234\"}"
        }
      ]
    }
  ]
}

PATCH 和 POST 中的请求格式有所不同。若要确保 POST 和 PATCH 以相同的格式发送，可以使用此处所述的功能标志。

AppRoleAssignmentsComplex

何时使用： 使用 AppRoleAssignmentsComplex 表达式为用户预配多个角色。

如何配置： 编辑受支持的属性列表，如所述，包括角色的新属性：

添加角色

然后使用 AppRoleAssignmentsComplex 表达式映射到自定义角色属性，如下图所示：

添加 AppRoleAssignmentsComplex

要考虑的事项

所有角色都配置为“primary = false”。
SCIM 角色中不需要该 id 属性。请改用该 value 属性。例如，如果 value 属性包含角色的名称或标识符，请使用它来预配角色。可以使用此处的功能标志来修复 ID 属性问题。但是，仅依赖值属性并不总是足够;例如，如果有多个具有相同名称或标识符的角色。在某些情况下，必须使用 ID 属性来正确预配角色

局限性

AppRoleAssignmentsComplex 与将范围设置为“同步所有用户和组”不兼容。

示例请求（POST）

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "externalId": "alias",
  "userName": "alias@contoso.partner.onmschina.cn",
  "active": true,
  "displayName": "First Name Last Name",
  "meta": {
    "resourceType": "User"
  },
  "roles": [
    {
      "primary": false,
      "type": "WindowsAzureActiveDirectoryRole",
      "displayName": "Admin",
      "value": "Admin"
    },
    {
      "primary": false,
      "type": "WindowsAzureActiveDirectoryRole",
      "displayName": "User",
      "value": "User"
    }
  ]
}

示例输出（PATCH）

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "Add",
      "path": "roles",
      "value": [
        {
          "value": "{\"id\":\"06b07648-ecfe-589f-9d2f-6325724a46ee\",\"value\":\"Admin\",\"displayName\":\"Admin\"}"
        },
        {
          "value": "{\"id\":\"06b07648-ecfe-599f-9d2f-6325724a46ee\",\"value\":\"User\",\"displayName\":\"User\"}"
        }
      ]
    }
  ]
}

AssertiveAppRoleAssignmentsComplex （建议用于复杂角色）

何时使用： 使用 AssertiveAppRoleAssignmentsComplex 启用 PATCH Replace 功能。对于支持多个角色的 SCIM 应用程序，这可确保目标应用程序中也会删除Microsoft Entra ID 中删除的角色。替换功能还将删除用户未反映在 Entra ID 中的任何其他角色

AppRoleAssignmentsComplex 和 AssertiveAppRoleAssignmentsComplex 之间的差异是修补程序调用模式和对目标系统的影响。前者仅执行 PATCH 添加操作，因此不会删除目标上的任何现有角色。如果某个角色尚未在 Entra ID 上被分配给用户，PATCH 操作将从目标系统中删除该角色。

如何配置： 编辑受支持的属性列表，如所述，包括角色的新属性：

添加角色

然后使用 AssertiveAppRoleAssignmentsComplex 表达式映射到自定义角色属性，如下图所示：

添加AssertiveAppRoleAssignmentsComplex

要考虑的事项

所有角色都预配为 primary = false。
SCIM 角色中不需要该 id 属性。请改用该 value 属性。例如，如果 value 属性包含角色的名称或标识符，请使用它来预配角色。可以使用此处的功能标志来修复 ID 属性问题。但是，仅依赖值属性并不总是足够;例如，如果有多个具有相同名称或标识符的角色。在某些情况下，必须使用 ID 属性来正确预配角色

局限性

AssertiveAppRoleAssignmentsComplex 不兼容于将范围设置为“同步所有用户和组。”

示例请求（POST）

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "externalId": "contoso",
  "userName": "contoso@alias.partner.onmschina.cn",
  "active": true,
  "roles": [
    {
      "primary": false,
      "type": "WindowsAzureActiveDirectoryRole",
      "display": "User",
      "value": "User"
    },
    {
      "primary": false,
      "type": "WindowsAzureActiveDirectoryRole",
      "display": "Test",
      "value": "Test"
    }
  ]
}

示例输出（PATCH）

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "roles",
      "value": [
        {
          "primary": false,
          "type": "WindowsAzureActiveDirectoryRole",
          "display": "User",
          "value": "User"
        },
        {
          "primary": false,
          "type": "WindowsAzureActiveDirectoryRole",
          "display": "Test",
          "value": "Test"
        }
      ]
    }
  ]
}

预配多值属性

某些属性（如 phoneNumbers 和电子邮件）是多值属性，你需要指定不同类型的电话号码或电子邮件。将表达式用于多值属性。它允许您指定属性类型，并将此类型映射到与该值对应的Microsoft Entra用户属性。

phoneNumbers[type eq "work"].value
phoneNumbers[type eq "mobile"].value
phoneNumbers[type eq "fax"].value

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "phoneNumbers": [
    {
      "value": "555-555-5555",
      "type": "work"
    },
    {
      "value": "555-555-5555",
      "type": "mobile"
    },
    {
      "value": "555-555-5555",
      "type": "fax"
    }
  ]
}

还原默认属性和属性映射

如果需要重新开始并将现有映射重置回其默认状态，则可以选中“ 还原默认映射 ”复选框并保存配置。这样做会设置所有映射和范围筛选器，就像应用程序已从应用程序库添加到 Microsoft Entra 租户一样。

选择此选项会强制所有用户在预配服务运行时重新同步。

重要

强烈建议在调用此选项之前将 预配状态 设置为 “关闭 ”。

你需要知道的事

Microsoft Entra ID 提供了同步过程的高效实现。在初始化的环境中，同步周期期间仅处理需要更新的对象。
更新属性映射会影响同步周期的性能。对属性映射配置的更新需要重新评估所有托管对象。
一个推荐的最佳实践是将属性映射的连续更改次数保持在最低限度。
目前不支持向应用添加要预配的照片属性，因为无法指定要同步照片的格式。可以在用户语音上请求该功能。
该属性 IsSoftDeleted 通常是应用程序的默认映射的一部分，可能在以下四种情况中的一种为 true：
- 由于未从应用程序分配，用户已脱离范围。
- 由于不满足范围筛选器，用户不在范围内。
- 在 Microsoft Entra ID 中，用户已被软删除。
- 该属性 AccountEnabled 已对用户设置为 false。尝试将 IsSoftDeleted 属性保留在属性映射中。
Microsoft Entra 预配服务不支持预配 null 值。
它们的主键，通常 ID，不应作为目标属性包含在属性映射中。
角色属性通常需要使用表达式进行映射，而不是直接映射。有关角色映射的详细信息，请参阅将角色预配到 SCIM 应用。
虽然可以从映射中禁用组，但不支持禁用用户。

后续步骤

Last updated on 2026-03-27

通过

教程 - 在 Microsoft Entra ID 中为 SaaS 应用程序自定义用户预配属性映射

编辑用户属性映射

了解属性映射类型

理解属性映射的性质

匹配源系统和目标系统中的用户

编辑组属性映射

编辑支持的属性列表

将自定义扩展属性预配到符合 SCIM 的应用程序

为 SCIM 应用预配角色

预配多值属性

还原默认属性和属性映射

你需要知道的事

后续步骤

其他资源