Microsoft Entra 用户预配服务 SCIM 2.0 协议合规性的已知问题和解决方法

项目
2025-04-30

Microsoft Entra ID 可以自动将用户和组预配到 Web 服务前端的任何应用程序或系统，该接口在跨域标识管理系统（SCIM） 2.0 协议规范中定义。

Microsoft SciM 2.0 协议的 Entra 支持在“使用跨域标识管理系统”（SCIM）中介绍了如何自动将用户和组从Microsoft Entra ID 预配到应用程序，其中列出了它实现的协议的特定部分，以便自动将用户和组从 Microsoft Entra ID 预配到支持 SCIM 2.0 的应用程序。

本文介绍 Microsoft Entra 用户预配服务遵循 SCIM 2.0 协议当前和过去面临的问题，以及如何解决这些问题。

理解预配作业

预配服务使用作业的概念来对应用程序进行操作。可在进度栏中找到 jobID。所有新的预配应用程序都以 jobID 开头 scim创建。 scim 作业表示服务的当前状态。较旧的作业具有 ID customappsso。此类作业表示2018年的服务状态。

如果在库中使用应用程序，该作业通常包含应用的名称（例如 zoom snowFlake 或 dataBricks）。如果使用的是库应用程序，则可以跳过此文档。此文档主要适用于 jobID 为 SCIM 或 customAppSSO 的非库应用程序。

SCIM 2.0 合规性问题和状态

在中，任何标记为固定的项都意味着可以在 SCIM 作业上找到适当的行为。我们努力确保所做更改的后向兼容性。我们建议对于所有新实现都使用新行为，并更新现有实现。不再支持在 2018 年 12 月之前默认的 customappSSO 行为。

注意

对于 2018 年所做的更改，可以恢复为 customappsso 行为。对于 2018 年以来所做的更改，可以使用 Url 恢复到旧行为。我们努力通过允许还原到旧的 jobID 或使用标记来确保所做更改的后向兼容性。但是，如前所述，我们不建议实施旧行为，因为它不再受支持。我们建议对于所有新实现都使用新行为，并更新现有实现。

SCIM 2.0 符合性问题	固定？	修复日期	向后兼容性
Microsoft Entra ID 要求“/scim”位于应用程序的 SCIM 终结点 URL 的根路径中	是	2018 年 12 月 18 日	降级到 customappSSO
扩展属性在属性名称之前使用点 `.` 表示法，而不是冒号“：”表示法	是	2018 年 12 月 18 日	降级到 customappSSO
多值属性的批量请求包含无效路径筛选器语法	是	2018 年 12 月 18 日	降级到 customappSSO
组创建请求包含无效架构 URI	是	2018 年 12 月 18 日	降级到 customappSSO
更新 PATCH 行为以确保合规性（例如，作为布尔值活动并适当删除组成员）	否	待定	使用功能标志

用于更改 SCIM 行为的标志

使用应用程序的租户 URL 中的标志来更改默认 SCIM 客户端行为。

SCIM 标志到以后的行为。

使用以下 URL 更新 PATCH 行为，并确保 SCIM 合规性。该标志更改以下行为：

请求禁用用户
请求添加单值字符串属性
请求替换多个属性
请求删除组成员

目前此行为仅在使用标志时可用，但在未来几个月内将成为默认行为。请注意，此功能标志当前不适用于按需预配。

URL（符合 SCIM）：aadOptscim062020
SCIM RFC 参考：
- https://tools.ietf.org/html/rfc7644#section-3.5.2

用于帮助概述同步引擎当前发送的内容的示例请求，以及启用功能标志后发送的请求。

对禁用用户的请求：

没有功能标志

{
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
      {
          "op": "Replace",
          "path": "active",
          "value": "False"
      }
  ]
}

使用功能标志

{
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
      {
          "op": "replace",
          "path": "active",
          "value": false
      }
  ]
}

请求添加单值字符串属性：

没有功能标志

{
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "Add",
      "path": "nickName",
      "value": "Babs"
    }
  ]
}

使用功能标志

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "nickName",
      "value": "Babs"
    }
  ]
}

替换多个属性的请求：

没有功能标志

{
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
      {
          "op": "Replace",
          "path": "displayName",
          "value": "Pvlo"
      },
      {
          "op": "Replace",
          "path": "emails[type eq \"work\"].value",
          "value": "TestBcwqnm@test.microsoft.com"
      },
      {
          "op": "Replace",
          "path": "name.givenName",
          "value": "Gtfd"
      },
      {
          "op": "Replace",
          "path": "name.familyName",
          "value": "Pkqf"
      },
      {
          "op": "Replace",
          "path": "externalId",
          "value": "Eqpj"
      },
      {
          "op": "Replace",
          "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber",
          "value": "Eqpj"
      }
  ]
}

使用功能标志

{
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
      {
          "op": "replace",
          "path": "emails[type eq \"work\"].value",
          "value": "TestMhvaes@test.microsoft.com"
      },
      {
          "op": "replace",
          "value": {
              "displayName": "Bjfe",
              "name.givenName": "Kkom",
              "name.familyName": "Unua",
              "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber": "Aklq"
          }
      }
  ]
}

请求删除组成员：

没有功能标志

{
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
      {
          "op": "Remove",
          "path": "members",
          "value": [
              {
                  "value": "u1091"
              }
          ]
      }
  ]
}

使用功能标志

{
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
      {
          "op": "remove",
          "path": "members[value eq \"7f4bc1a3-285e-48ae-8202-5accb43efb0e\"]"
      }
  ]
}

降级 URL：新的 SCIM 合规行为在非库应用程序上成为默认行为后，可以使用以下 URL 回退到旧的非 SCIM 合规行为：AzureAdScimPatch2017

从旧的 customappsso 作业升级到 SCIM 作业

删除现有 customappsso 作业并创建新的 SCIM 作业。

以至少应用程序管理员身份登录到 Microsoft Entra 管理中心。
浏览到 Entra ID>Enterprise 应用。
找到并选择现有的 SCIM 应用程序。
在现有 SCIM 应用的“属性”部分，复制“对象 ID”。
在新的 Web 浏览器窗口中，转到 https://developer.microsoft.com/graph/graph-explorer 并以要向其中添加应用的 Microsoft Entra 租户的管理员身份登录。
在 Graph 资源管理器中，运行以下命令以找到预配作业的 ID。将“[object-id]”替换为从第三步复制的服务主体 ID（对象 ID）。

GET https://graph.microsoft.com/beta/servicePrincipals/[object-id]/synchronization/jobs
在结果中，复制以“customappsso”或“scim”开头的完整“ID”字符串。
运行以下命令，检索属性映射配置，以便执行备份。使用和之前一样的 [object-id]，并将 [job-id] 替换为从最后一步复制的预配作业 ID。

GET https://graph.microsoft.com/beta/servicePrincipals/[object-id]/synchronization/jobs/[job-id]/schema
复制最后一步的 JSON 输出，并保存到文本文件。此 JSON 输出包含向旧应用添加的所有自定义属性映射，应该约有数千行 JSON。
运行以下命令，删除预配作业：

DELETE https://graph.microsoft.com/beta/servicePrincipals/[object-id]/synchronization/jobs/[job-id]
运行以下命令，创建具有最新服务修补程序的新预配作业。

POST https://graph.microsoft.com/beta/servicePrincipals/[object-id]/synchronization/jobs { "templateId": "scim" }

在最后一步的结果中，复制以“scim”开头的完整“ID”字符串。可选择运行以下命令，将 [new-job-id] 替换为复制的新作业 ID，并输入第七步的 JSON 输出作为请求正文来重新应用旧属性映射。

PUT https://graph.microsoft.com/beta/servicePrincipals/[object-id]/synchronization/jobs/[new-job-id]/schema { <your-schema-json-here> }

返回第一个 Web 浏览器窗口，选择应用程序的“预配”选项卡。
验证配置，然后启动预配作业。

将 SCIM 作业降级到 customappsso 作业（不推荐）

我们允许你降级回旧行为，但不推荐它，因为 customappsso 不会受益于我们所做的某些更新，并且可能永远不受支持。

以至少应用程序管理员身份登录到 Microsoft Entra 管理中心。
浏览到 Entra ID>Enterprise 应用。
在“创建应用程序”部分中，创建新的非库应用程序。
在新的自定义应用的“属性”部分，复制“对象 ID”。
在新的 Web 浏览器窗口中，转到 https://developer.microsoft.com/graph/graph-explorer 并以要向其中添加应用的 Microsoft Entra 租户的管理员身份登录。
在 Graph 资源管理器中，运行以下命令，初始化应用的预配配置。将“[object-id]”替换为从第三步复制的服务主体 ID（对象 ID）。

POST https://graph.microsoft.com/beta/servicePrincipals/[object-id]/synchronization/jobs { templateId: "customappsso" }
返回第一个 Web 浏览器窗口，选择应用程序的“预配”选项卡。
照常完成用户预配配置。

后续步骤

详细了解如何预配和取消预配 SaaS 应用程序

通过

Microsoft Entra 用户预配服务 SCIM 2.0 协议合规性的已知问题和解决方法

理解预配作业

SCIM 2.0 合规性问题和状态

用于更改 SCIM 行为的标志

从旧的 customappsso 作业升级到 SCIM 作业

将 SCIM 作业降级到 customappsso 作业（不推荐）

后续步骤

反馈

其他资源