排查 Microsoft Entra ID SCIM API 错误

本文可帮助解决调用Microsoft Entra ID SCIM API 进行用户和组管理的常见问题。

错误：401 - 身份验证令牌无效

症状

SCIM API 请求返回：

HTTP 401 Unauthorized

原因

请求不包括 HTTP Authorization 标头中的有效访问令牌。

解决方案

1. 确认请求的 HTTP Authorization 标头中包含了 Bearer 令牌。
2. 使用 https://jwt.ms/ 验证访问令牌
3. 验证以下令牌声明：
   • iat
   • exp
4. 如果问题仍然存在：
   • 收集失败 API 调用的详细信息
   • 创建支持票证

错误：403 - 禁止

症状

SCIM API 请求返回：

HTTP 403 Forbidden

原因

SCIM API 客户端使用的应用注册没有所需的 API 权限，也没有授予管理员许可。

解决方案

1. 查看 SCIM API 客户端使用的应用注册。
2. 确认已分配的 Microsoft Graph API 权限符合 Microsoft Entra ID SCIM API 参考文档的描述：
3. 确认已为所有分配的权限授予 管理员许可 。
4. 如果问题仍然存在：
   • 收集 API 请求详细信息
   • 创建支持票证

错误：404 - 找不到资源

症状

以下 API 调用返回：

HTTP 404 Not Found

• GET /users/{id}
• GET /groups/{id}

原因

请求中的 {id} 值无法解析为 Microsoft Entra ID 租户中的有效用户或组对象。

解决方案

1. 请确认在 Microsoft Entra ID 租户中是否存在{id} 值。
2. 如果问题仍然存在：
   • 收集 API 请求详细信息
   • 创建支持票证

错误：400 - 请求错误

症状

SCIM API 请求返回：

HTTP 400 Bad Request

此错误可能在以下过程中发生：

• 用户创建或更新操作
  （POST /Users 或 PATCH /Users）
• 组创建或更新操作
  （POST /Groups 或 PATCH /Groups）
• 用户或组筛选器查询
  （GET）

原因

请求有效负载或查询参数不符合为 SCIM API 定义的约束，或引用无效的 SCIM 架构属性。

解决方案

1. 对于POST操作：
   • 确保在请求有效负载中包含所有必需属性。
2. 对于PATCH操作：
   • 确保请求符合 SCIM API 约束。
3. 对于GET操作：
   • 确认仅使用支持的 API 筛选器。
4. 确保请求属性映射到有效的Microsoft Entra SCIM 架构属性。
5. 使用更正重新发送请求。
6. 如果问题仍然存在：
   • 收集 API 请求详细信息
   • 创建支持票证

错误：400 - 未启用 SCIM 预配 API 功能

症状

SCIM API 请求返回：

HTTP 400 Bad Request

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "detail": "No 'scimapiconsumptions' resource found for TenantId: <tenant-id>. Please ensure 'SCIM Provisioning API' feature is enabled and only one 'scimapiconsumptions' resource exists.",
  "status": "400"
}

原因

在 Microsoft Entra 管理中心中，SCIM 预配 API 功能未启用，或者该功能所需的计费订阅尚未链接。 当管理员打开该功能并链接Azure订阅进行计费时，将创建Azure资源。 如果没有此资源，SCIM 服务将拒绝所有 API 调用。

解决方案

1. 登录到 Microsoft Entra admin center。
2. 导航到 ID 治理>仪表板。
3. 在 SCIM 预配 API 磁贴上，选择 “入门”（如果先前已配置，则选择 “编辑”）。
4. 链接Azure订阅，选择资源组，然后选择打开。
5. 启用该功能后，请重试 SCIM API 请求。

有关详细步骤，请参阅 “启用 SCIM 预配 API”。

错误：500 - 内部服务器错误

症状

SCIM API 请求返回：

HTTP 500 Internal Server Error

原因

处理 SCIM API 请求时出现意外的服务器端错误。

解决方案

1. 收集失败的 API 调用的详细信息。
2. 创建支持票证。

错误：504 - 网关超时

症状

SCIM API 请求返回：

HTTP 504 Gateway Timeout

原因

SCIM 服务可能会返回间歇性 504 响应。

解决方案

1. 收集失败的 API 调用及其错误和错误出现的时间段的详细信息。
2. 如果问题仍然持续存在，请创建支持票证。

SCIM API 错误代码参考

下表列出了MICROSOFT ENTRA ID SCIM API 可以返回的所有错误代码。 使用此表可识别 SCIM API 请求故障排除时的错误及其原因。