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

  • 项目

Microsoft Entra ID 可以使用跨域身份管理系统 (SCIM) 2.0 协议规范中定义的接口，将用户和组自动预配到以 Web 服务为前端的任何应用程序或系统。

Microsoft Entra ID 对 SCIM 2.0 协议的支持在使用跨域身份管理系统 (SCIM) 将用户和组从 Microsoft Entra ID 自动预配到应用程序中进行介绍，其中列出为了将用户和组从 Microsoft Entra ID 自动预配到支持 SCIM 2.0 的应用程序而实现的具体协议部分。

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

理解预配作业

预配服务使用作业的概念来对应用程序进行操作。 可在进度栏中找到 jobID。 所有新的预配应用程序都用以“scim”开头的 jobID 创建。 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 行为以确保合规性（例如，作为布尔值活动并适当删除组成员） 否 TBD 使用功能标志

用于更改 SCIM 行为的标志

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

SCIM flags to later behavior.

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

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

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

下面的示例请求帮助概述同步引擎当前发送的内容与启用功能标志后发送的请求。

请求禁用用户：

没有功能标志

{
  "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 作业。

  1. 至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。

  2. 浏览到“标识”>“应用程序”>“企业应用程序”。

  3. 找到并选择现有的 SCIM 应用程序。

  4. 在现有 SCIM 应用的“属性”部分，复制“对象 ID”。

  5. 在新的 Web 浏览器窗口中，转到 https://developer.microsoft.com/graph/graph-explorer 并以要向其中添加应用的 Microsoft Entra 租户的管理员身份登录。

  6. 在 Graph 资源管理器中，运行以下命令以找到预配作业的 ID。 将“[object-id]”替换为从第三步复制的服务主体 ID（对象 ID）。

    GET https://graph.microsoft.com/beta/servicePrincipals/[object-id]/synchronization/jobs

    Get Jobs

  7. 在结果中，复制以“customappsso”或“scim”开头的完整“ID”字符串。

  8. 运行以下命令，检索属性映射配置，以便执行备份。 使用和之前一样的 [object-id]，并将 [job-id] 替换为从最后一步复制的预配作业 ID。

    GET https://graph.microsoft.com/beta/servicePrincipals/[object-id]/synchronization/jobs/[job-id]/schema

    Get Schema

  9. 复制最后一步的 JSON 输出，并保存到文本文件。 此 JSON 输出包含向旧应用添加的所有自定义属性映射，应该约有数千行 JSON。

  10. 运行以下命令，删除预配作业：

    DELETE https://graph.microsoft.com/beta/servicePrincipals/[object-id]/synchronization/jobs/[job-id]

  11. 运行以下命令，创建具有最新服务修补程序的新预配作业。

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

  1. 在最后一步的结果中，复制以“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> }

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

我们允许降级到旧行为，但不推荐这样做，因为 customappsso 不能从我们所做的一些更新中受益，而且可能不会被永久支持。

  1. 至少以应用程序管理员的身份登录到 Microsoft Entra 管理中心。

  2. 浏览到“标识”>“应用程序”>“企业应用程序”。

  3. 在“创建应用程序”部分中，创建新的非库应用程序。

  4. 在新的自定义应用的“属性”部分，复制“对象 ID”。

  5. 在新的 Web 浏览器窗口中，转到 https://developer.microsoft.com/graph/graph-explorer 并以要向其中添加应用的 Microsoft Entra 租户的管理员身份登录。

  6. 在 Graph 资源管理器中，运行以下命令，初始化应用的预配配置。 将“[object-id]”替换为从第三步复制的服务主体 ID（对象 ID）。

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

  7. 返回第一个 Web 浏览器窗口，选择应用程序的“预配”选项卡。

  8. 照常完成用户预配配置。

后续步骤

了解关于 SaaS 应用程序预配和取消预配的详细信息