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

项目
03/05/2024

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

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

Microsoft Entra 用户对象与每个 SaaS 应用的用户对象之间存在一组预先配置的属性和属性映射。某些应用与用户一起管理其他类型的对象，例如“组”。

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

注意

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

编辑用户属性映射

提示

本文中的步骤可能因开始使用的门户而略有不同。

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

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

在此屏幕截图中，可以发现 Salesforce 中托管对象的“用户名”属性由所链接的 Microsoft Entra 对象的“userPrincipalName”值填充。

注意

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

了解属性映射类型

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

直接：使用 Microsoft Entra ID 中链接对象的特性值填充目标特性。
常量 - 目标属性使用你指定的特定字符串填充。
表达式 - 目标属性是基于脚本式表达式的结果填充的。有关表达式的详细信息，请参阅在 Microsoft Entra ID 中编写特性映射的表达式。
无 - 目标属性保持不变。不过，如果目标属性曾经为空，则会使用你指定的默认值进行填充。

除了这四个基本类型之外，自定义属性映射还支持可选的默认值赋值概念。默认值赋值确保当 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 预配服务。为了同时支持这两种场景，预配服务使用匹配属性的概念。可以通过匹配属性确定如何唯一标识源中的用户，并匹配目标中的用户。在规划部署期间，确定可用于唯一标识源系统和目标系统中的用户的属性。注意事项：

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

编辑组属性映射

一些特定的应用程序（例如 ServiceNow、Box 和 G Suite）支持预配组和用户对象。 “组”对象可以包含组属性（例如显示名称和电子邮件别名）以及组成员。

示例显示具有预配“组”和“用户”对象的 ServiceNow

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

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

提示

预配组对象（属性和成员）的过程完全不同于将组分配到应用程序。可以将组分配到应用程序，但只能预配组中包含的用户对象。预配整个组对象不需要使用分配中的组。

编辑受支持属性的列表

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

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

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

Salesforce
ServiceNow
Workday 到 Active Directory/Workday 到Microsoft Entra ID
SuccessFactors 到 Active Directory/successFactors 到 Microsoft Entra ID
Microsoft Entra ID（支持 Microsoft Entra ID 图形 API 默认属性和自定义目录扩展）。有关创建扩展的详细信息，请参阅同步 Microsoft Entra 应用程序预配的扩展属性和在 Microsoft Entra ID 中预配的已知问题
支持跨域标识系统 (SCIM) 2.0 的应用
对于 XPATH 和 JSONPath 元数据，Microsoft Entra ID 支持写回 Workday 或 SuccessFactors。 Microsoft Entra ID 不支持未包含在默认架构中的新 Workday 或 SuccessFactors 属性

注意

建议只让自定义了其应用程序和系统的架构且原本就知道自定义属性定义方式的管理员来编辑受支持属性的列表，或者在 Microsoft Entra 管理中心 UI 中未自动显示源属性的情况下进行编辑。有时，需要熟悉应用程序或系统提供的 API 和开发人员工具才能执行此操作。默认情况下，编辑受支持的属性列表的功能处于锁定状态，但客户可以通过导航到以下 URL 来启用该功能： https://portal.azure.com/?Microsoft_AAD_Connect_Provisioning_forceSchemaEditorEnabled=true 。然后，可以导航到应用程序以查看属性列表。

注意

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

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

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

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

SCIM 请求评论 (RFC) 定义一个核心用户和组模式，同时还允许对模式进行扩展，以满足应用程序的需要。向 SCIM 应用程序添加自定义属性：

至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。
浏览到“标识”>“应用程序”>“企业应用程序”。
选择应用程序，然后选择“预配”。
在“映射”下，选择要为其添加自定义属性的对象（用户或组）。
在页面底部，选择“显示高级选项”。
选择“编辑 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/2819c223-7f76-453a-919d-413861904646"
  }
}

将角色预配到 SCIM 应用

使用示例中的步骤将用户的应用程序角色预配到你的应用程序。说明特定于自定义 SCIM 应用程序。对于 Salesforce 和 ServiceNow 等库应用程序，请使用预定义的角色映射。项目符号说明了如何将 AppRoleAssignments 属性转换为应用程序所需的格式。

将 Microsoft Entra ID 中的 appRoleAssignment 映射到应用程序中的某个角色需要使用表达式来转换该属性。如果不使用表达式来分析角色详细信息，就不应将 appRoleAssignment 属性直接映射到角色属性。

注意

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

SingleAppRoleAssignment

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

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

添加 SingleAppRoleAssignment

注意事项

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

示例请求 (POST)

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

示例输出 (PATCH)

"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

注意事项

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

限制

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

示例请求 (POST)

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "externalId": "alias",
  "userName": "alias@contoso.OnMicrosoft.com",
  "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)

"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

注意事项

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

限制

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

示例请求 (POST)

{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 

"externalId":"contoso", 

"userName":"contoso@alias.onmicrosoft.com", 

"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 和 emails）是多值属性，你需要指定不同类型的电话号码或电子邮件。对于多值属性，请使用该表达式。它允许你指定属性类型，并将其映射到值对应的 Microsoft Entra 用户属性。

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

phoneNumbers[type eq "fax"].value

"phoneNumbers": [
   {
      "value": "555-555-5555",
      "type": "work"
   },
   {
      "value": "555-555-5555",
      "type": "mobile"
   },
   {
      "value": "555-555-5555",
      "type": "fax"
   }
]

还原默认属性和属性映射

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

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

重要

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

要点

Microsoft Entra ID 提供了一个有效的同步进程实现。在初始化环境中，在同步周期中只会处理需要更新的对象。
更新属性映射会影响同步周期的性能。对属性映射配置进行更新需要重新评估所有托管对象。
建议采用的最佳做法是尽量少地连续更改属性映射。
由于不能指定用于同步照片的格式，因此目前不支持添加预配到应用的照片属性。可以在 User Voice 上请求该功能。
IsSoftDeleted 属性通常是应用程序默认映射的一部分。 IsSoftdeleted 在以下四种情况中为 true：1) 由于从应用程序中取消指定用户，该用户不在范围内。 2) 由于未满足范围筛选条件，用户不在范围范围内。 3) 该用户在 Microsoft Entra ID 中被软删除。4) 属性 AccountEnabled 在用户上设置为 false。尝试将 IsSoftDeleted 属性保留在属性映射中。
Microsoft Entra 预配服务不支持预配 NULL 值。
它们的主键通常为“ID”，它不应作为目标属性包含在属性映射中。
角色属性通常需要使用表达式进行映射，而不是直接映射。有关角色映射的详细信息，请参阅向 SCIM 应用预配角色。
虽然可从映射中禁用组，但不支持禁用用户。

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

编辑用户属性映射

了解属性映射类型

了解属性映射的属性

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

编辑组属性映射

编辑受支持属性的列表

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

将角色预配到 SCIM 应用

预配多值属性

还原默认属性和属性映射

要点

后续步骤

其他资源