Microsoft Entra ID SCIM API 参考文档

使用此参考指南通过跨域标识管理系统（SCIM）v2.0 协议将用户和组预配到 Microsoft Entra ID 中。

SCIM API 概述

Microsoft Entra ID SCIM 实现基于以下 IETF 草稿：

所有 SCIM API 终结点都位于基础 URL 下：https://microsoftgraph.chinacloudapi.cn/rp/scim

终结点 支持的 HTTP 方法 说明
/serviceproviderconfig GET 获取有关 SCIM 实现Microsoft Entra ID的配置详细信息，例如支持的身份验证方案、可用的终结点以及 SCIM 协议的符合性。
/resourcetypes GET 检索有关Microsoft Entra ID支持的资源类型（用户和组）的信息。
/schemas GET 检索有关Microsoft Entra ID支持的架构的详细信息。
/users GET、POST、PATCH、DELETE 读取、创建、更新和删除Microsoft Entra ID中的用户数据。
/groups GET、POST、PATCH、DELETE 读取、创建、更新和删除Entra ID中的组和组成员身份数据。

以下部分包含MICROSOFT ENTRA ID SCIM 实现中当前支持的 API 请求和响应示例，以及设计中要考虑的重要说明和约束。

调用 SCIM API

必须先启用 SCIM 预配 API 功能、配置计费、设置凭据并获取访问令牌，然后才能调用本文中所述的 SCIM API 终结点。 有关分步说明，请参阅 启用 Microsoft Entra ID 中的 SCIM 预配 API。

注释

SCIM API 仅在应用程序上下文（仅限应用令牌）中运行，不支持用户代理/委派场景。

映射到 Graph 用户和组属性

若要了解 Microsoft Graph 用户和组属性如何映射到 SCIM 用户和组属性，请参阅 Microsoft Entra ID SCIM API 架构参考。

Throttling

适用于Microsoft Graph API 的相同限制指南和服务特定的限制也适用于Microsoft Entra ID SCIM API。 有关适用于 Microsoft Graph 用户和组 API 的限制策略，请参阅 Microsoft Graph 限制指南 和 Microsoft Graph 标识和访问 API 的服务特定限制。

错误

有关 SCIM API 终结点返回的常见错误代码的列表，请参阅 SCIM API 错误代码参考。

获取服务提供程序配置

使用 /ServiceProviderConfig 终结点查看有关 Microsoft Entra ID SCIM 实现的其他信息。 /ServiceProviderConfig 终结点是只读的。

API 终结点：https://microsoftgraph.chinacloudapi.cn/rp/scim/serviceproviderconfig

成功后，API 返回 HTTP 状态 200。

权限

权限类型 权限（从最低到最高特权）
应用程序 User.Read.All 和 Group.Read.All， User.ReadWrite.All 和 Group.ReadWrite.All

示例 1 - 请求服务提供商配置

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/serviceproviderconfig
Authorization: Bearer {token}
Accept: application/json

响应（200 正常）：

响应已为提高可读性而被截短。

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
  "documentationUri": "/graph/overview",
  "pagination": {
    "cursor": true,
    "index": false,
    "defaultPaginationMethod": "cursor",
    "defaultPageSize": 100,
    "maxPageSize": 1000
  },
  "patch": {
    "supported": true
  },
  "bulk": {
    "supported": false,
    "maxOperations": 0,
    "maxPayloadSize": 0
  },
  "filter": {
    "supported": true,
    "maxResults": 200
  }
}

列出资源类型

可以通过向 /resourcetypes 终结点发出请求来检索有关支持的资源类型的信息。

API 终结点：

  • https://microsoftgraph.chinacloudapi.cn/rp/scim/resourcetypes
  • https://microsoftgraph.chinacloudapi.cn/rp/scim/resourcetypes/{identifier}

成功后，API 返回 HTTP 状态 200。

权限

权限类型 权限（从最低到最高特权）
应用程序 User.Read.All 和 Group.Read.All， User.ReadWrite.All 和 Group.ReadWrite.All

示例 1 - 请求所有资源类型

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/resourcetypes
Authorization: Bearer {token}
Accept: application/json

响应（200 正常）：

响应已为提高可读性而被截短。

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 2,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
      "id": "User",
      "name": "User",
      "endpoint": "/Users",
      "description": "User Account",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
      "schemaExtensions": [
        {
          "schema": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
          "required": true
        },
        {
          "schema": "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User",
          "required": true
        }
      ],
      "meta": {
        "location": "/resourcetypes/user",
        "resourceType": "resourceType"
      }
    },
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
      "id": "Group",
      "name": "Group",
      "endpoint": "/Groups",
      "description": "Group",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:Group",
      "schemaExtensions": [
        {
          "schema": "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group",
          "required": true
        }
      ],
      "meta": {
        "location": "/resourcetypes/group",
        "resourceType": "resourceType"
      }
    }
  ]
}

示例 2 - 请求用户资源类型

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/resourcetype/User
Authorization: Bearer {token}
Accept: application/json

响应（200 正常）：

响应已为提高可读性而被截短。

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
  "id": "User",
  "name": "User",
  "endpoint": "/Users",
  "description": "User Account",
  "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
  "schemaExtensions": [
    {
      "schema": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
      "required": true
    }
  ],
  "meta": {
    "location": "/resourcetypes/user",
    "resourceType": "resourceType"
  }
}

获取架构

可以通过向 /schemas 终结点发出请求来检索有关支持的 SCIM 架构的信息。

API 终结点：

  • https://microsoftgraph.chinacloudapi.cn/rp/scim/schemas
  • https://microsoftgraph.chinacloudapi.cn/rp/scim/schemas/{identifier}

成功后，API 返回 HTTP 状态 200。

权限

权限类型 权限（从最低到最高特权）
应用程序 User.Read.All 和 Group.Read.All， User.ReadWrite.All 和 Group.ReadWrite.All

注释

若要读取自定义安全属性架构，应用还需要 CustomSecAttributeDefinition.Read.All。

示例 1 - 请求所有架构

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/schemas
Authorization: Bearer {token}
Accept: application/json

响应（200 正常）：

响应已为提高可读性而被截短。

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 5,
  "Resources": [
    {
      "id": "urn:ietf:params:scim:schemas:core:2.0:User",
      "name": "User",
      "description": "User Account",
      "attributes": [...]
    },
    {
      "id": "urn:ietf:params:scim:schemas:core:2.0:Group",
      "name": "Group",
      "description": "Group",
      "attributes": [...]
    }
  ]
}

示例 2 - 请求用户架构

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/schemas/urn:ietf:params:scim:schemas:core:2.0:User
Authorization: Bearer {token}
Accept: application/json

响应（200 正常）：

响应已为提高可读性而被截短。

{
  "id": "urn:ietf:params:scim:schemas:core:2.0:User",
  "name": "User",
  "description": "User Account",
  "attributes": [...]
}

示例 3 - 请求自定义安全属性架构

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/schemas/urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes
Authorization: Bearer {token}
Accept: application/json

响应（200 正常）：

响应已为提高可读性而被截短。

{
  "id": "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes",
  "name": "MicrosoftEntraCustomSecurityAttributes",
  "description": "Microsoft Entra Custom Security Attributes",
  "attributes": [
    {
      "name": "Project",
      "type": "complex",
      "multiValued": false,
      "description": "Projects assigned to the user",
      "required": false,
      "caseExact": false,
      "subAttributes": [
        {
          "name": "ProjectName",
          "type": "String",
          "multiValued": false,
          "description": "Name of the project",
          "required": false,
          "caseExact": false,
          "mutability": "readWrite",
          "returned": "default",
          "uniqueness": "none"
        }
      ],
      "mutability": "readWrite",
      "returned": "request",
      "uniqueness": "none"
    }, …
]
}

列出用户

使用 /users 终结点执行以下操作：

  • 获取租户中的所有用户（分页）。

  • 获取符合特定筛选条件的用户。

API 终结点：

https://microsoftgraph.chinacloudapi.cn/rp/scim/users

成功后，API 返回 HTTP 状态 200。

如果响应包含多个页面，请使用 基于游标的分页 检索结果中的所有页面。

权限

权限类型 权限（从最低到最高特权）
应用程序 User.Read.All、User.ReadWrite.All

注释

若要读取用户的自定义安全属性，应用还需要 CustomSecAttributeAssignment.Read.All 或 CustomSecAttributeAssignment.ReadWrite.All。

列表用户的查询参数

以下 SCIM 查询参数可用于此 API 终结点：

  • filter - 指定要应用的筛选条件

  • attributes - 指定服务器应返回的用户属性。

  • excludedAttributes - 指定服务器应排除哪些用户属性。

  • count - 指定要检索的结果数（默认值为 100）

  • cursor - 前进到下一个结果页

列表用户的约束

Microsoft Entra ID SCIM 实现具有以下约束：

  • 当结果中涉及多个页面时：

    • 每个页面的默认页面大小为 10 个条目。
    • 每个页面的最大页大小为 100 个条目。

  • 在“filter”查询参数中，仅支持“and”逻辑运算符。 “eq”比较运算符允许以下用户属性：

    • username
    • externalId
    • id
    • groups.value
    • urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mailNickname

  • 以下用户属性可用于“ew”（endsWith）比较运算符。

    • 用户名
    • urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mailNickname

  • 在查询参数中 filter ，组合筛选器仅支持 和 逻辑运算符。

  • 在“=”周围的查询字符串中编码或未编码的任何空格都会导致拒绝请求并出现“BadRequest”错误。 这适用于所有查询参数 -filter、attributes、excludedAttributes、count 和 cursor。

  • 不支持将组合筛选器与属性一起使用 externalId 。 例如，无法使用以下组合筛选器：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/users?filter=externalId eq '12345' and userName eq 'user@contoso.com'

以下示例仅包含请求详细信息。 为了简洁，不包括响应。 它符合 SCIM 标准的响应负载。

示例 1A - 获取所有用户

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/users
Authorization: Bearer {token}
Accept: application/json

响应（200 正常）：


{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "itemsPerPage": 100,
  "nextCursor": "RFNwdAIAAQAAAB06MTAyMDE4QHhmcDFiLm9ubWljcm9zb2Z0LmNvbS...",
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
        "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User"
      ],
      "id": "d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4",
      "active": true,
      "displayName": "Ellen Reckert",
      "name": {
        "familyName": "Reckert",
        "givenName": "Ellen"
      },
      "userName": "100009@contoso.com",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "department": "Human Resources US",
        "employeeNumber": "100009",
        "manager": {
          "value": "bbbbbbbb-7777-8888-9999-cccccccccccc"
        }
      },
      "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User": {
        "mailNickname": "100009",
        "userType": "Member"
      },
      "meta": {
        "location": "/users/d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4",
        "resourceType": "user"
      }
    },
    { ... }
  ]
}

示例 1B - 检索下一页以获取所有用户

上述查询默认返回每页 100 个用户。 如果租户中有超过 100 个用户，请使用分页功能，通过在查询参数中设置响应中收到的cursor 值，以检索下一组用户。

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/users?cursor=RFNwdAIAAQAAAB06MTAyMDE4QHhmcDFiLm9ubWljcm9zb2Z0LmNvbS...
Authorization: Bearer {token}
Accept: application/json

示例 1C - 使用 count 参数来控制返回的用户数量

可以使用参数 count 检索特定数量的用户。

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/users?count=1000
Authorization: Bearer {token}
Accept: application/json

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/users?count=1000&cursor=RFNwdAIAAQAAAB06MTAyMDE4QHhmcDFiLm9ubWljcm9zb2Z0LmNvbS...
Authorization: Bearer {token}
Accept: application/json

示例 2 - 通过 ID 获取具有特定属性的用户

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/users?filter=id eq "97c0abe1-14f7-417b-951c-bc8e2a17f200"&attributes=name.familyName,displayName
Authorization: Bearer {token}

示例 3 - 获取具有自定义安全属性集的用户

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/users?attributes=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes:attributeSetName
Authorization: Bearer {token}

示例 4 - 使用被排除的属性按 ID 获取用户

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/users?filter=id eq "97c0abe1-14f7-417b-951c-bc8e2a17f200"&excludedAttributes=name.familyName,displayName
Authorization: Bearer {token}

示例 5 - 通过 mailNickname 获取用户

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/users?filter=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User:mailNickname eq "100009"&attributes=displayName
Authorization: Bearer {token}

响应（200 正常）：

响应已为提高可读性而被截短。

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User"
      ],
      "id": "f5f5f5f5-aaaa-bbbb-cccc-d6d6d6d6d6d6",
      "displayName": "Ellen Reckert",
      "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User": {
        "mailNickname": "100009"
      },
      "meta": {
        "location": "/users/f5f5f5f5-aaaa-bbbb-cccc-d6d6d6d6d6d6",
        "resourceType": "user"
      }
    }
  ]
}

示例 6 - 按 userName 获取用户

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/users?filter=userName eq "AdeleV@contoso.com"
Authorization: Bearer {token}

示例 7 - 按用户 ID 和组 ID 获取用户

请求：使用group objectId属性中的Entragroups.value和user objectId属性中的id来检查用户是否属于特定群组。

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/users?filter=filter=groups.value eq "dddddddd-3333-4444-5555-eeeeeeeeeeee" and id eq "19134e88-95eb-4616-89af-189f0a4e2abf"&attributes=displayName
Authorization: Bearer {token}

响应 (200 OK) 为改善可读性，响应内容已截断。

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4",
      "displayName": "Tanya Clifton",
      "meta": {
        "location": "/users/d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4",
        "resourceType": "user"
      }
    }
  ]
}

示例 8 - 检索用户的特定自定义安全属性

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/users?filter=userName eq "AdeleV@contoso.com"&attributes=urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes:Project
Authorization: Bearer {token}

响应 (200 OK) 为改善可读性，响应内容已截断。

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes"
      ],
      "id": "b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2",
      "userName": "AdeleV@contoso.com",
      "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes": {
        "Project": {
          "ProjectName": "IdentityHub"
        }
      },
      "meta": {
        "location": "/users/b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2",
        "resourceType": "user"
      }
    }
  ]
}

按 ID 获取用户

可以通过向具有用户 ID 的 /users 终结点发出 GET 请求来检索现有用户。

API 终结点：

https://microsoftgraph.chinacloudapi.cn/rp/scim/users/{id}

成功后，API 返回 HTTP 状态 200。

权限

权限类型 权限（从最低到最高特权）
应用程序 User.Read.All、User.ReadWrite.All

按 ID 获取用户的查询参数

以下 SCIM 查询参数可用于此 API 终结点：

  • attributes - 指定服务器应返回的用户属性。

  • excludedAttributes - 指定服务器应排除哪些用户属性。

示例 1 - 按 ID 获取具有特定属性的用户

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/users/aaaaaaaa-6666-7777-8888-bbbbbbbbbbbb?attributes=displayName,userName
Authorization: Bearer {token}

响应（200 正常）：

响应已为提高可读性而被截短。

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "aaaaaaaa-6666-7777-8888-bbbbbbbbbbbb",
  "displayName": "Adele Vance",
  "userName": "AdeleV@contoso.com",
  "meta": {
    "location": "/users/aaaaaaaa-6666-7777-8888-bbbbbbbbbbbb",
    "resourceType": "user"
  }
}

创建用户

可以通过向 /users 终结点发送 POST 请求，在 Microsoft Entra ID 中创建新用户。

API 终结点：

发布 https://microsoftgraph.chinacloudapi.cn/rp/scim/users

成功后，API 返回 HTTP 状态 201。

权限

权限类型 权限（从最低到最高特权）
应用程序 User.ReadWrite.All

创建用户所需的属性

成功创建用户时需要以下属性：

  • userName

  • password

  • name.familyName

  • name.givenName

  • active

  • displayName

  • urn：ietf：params：scim：schemas：extension：Microsoft：Entra：2.0：User：mailNickname

示例 1 - 创建新用户

请求：

POST https://microsoftgraph.chinacloudapi.cn/rp/scim/users
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User"
  ],
  "active": true,
  "displayName": "Example User",
  "userName": "abc123@contoso.com",
  "password": "password",
  "name": {
    "familyName": "Example familyName",
    "givenName": "Example givenName"
  },
  "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:User": {
    "mailNickname": "abc123"
  }
}

响应（201 已创建）：

返回创建的用户的 SCIM 表示形式。

更新用户

/users 终结点允许发出 PATCH 请求来更新现有用户配置文件。

API 终结点：

补丁 https://microsoftgraph.chinacloudapi.cn/rp/scim/users/{id}

成功后，API 返回 HTTP 状态 204。

权限

权限类型 权限（从最低到最高特权）
应用程序 User.ReadWrite.All

注释

若要更新用户的自定义安全属性，应用还需要 CustomSecAttributeAssignment.ReadWrite.All。 若要更新 employeeLeaveDateTime 等生命周期属性，应用还需要 User-LifeCycleInfo.ReadWrite.All。

更新用户的限制条件

  • 对于 PATCH 操作，在更新复杂的多值属性（如地址）时，路径属性仅支持“[type eq ”work“]”筛选器。

  • 无法使用 PATCH 操作删除强制属性 mailNickname 。

示例 1 - 更新属性值

请求：

PATCH https://microsoftgraph.chinacloudapi.cn/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json

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

响应（204 无内容）：

响应符合 SCIM 规范。

示例 2 - 更新复杂值

请求：

PATCH https://microsoftgraph.chinacloudapi.cn/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "operations": [
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:core:2.0:User:name",
      "value": {
        "familyName": "Jane",
        "givenName": "Doe"
      }
    }
  ]
}

响应（204 无内容）：

响应符合 SCIM 规范。

示例 3 - 更新复杂多值属性

请求：

PATCH https://microsoftgraph.chinacloudapi.cn/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "operations": [
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:core:2.0:User:addresses",
      "value": [
        {
          "type": "work",
          "streetAddress": "4567 Main Street",
          "locality": "Buffalo",
          "region": "NY",
          "postalCode": "98052",
          "country/region": "United States"
        }
      ]
    }
  ]
}

响应（204 无内容）：

响应符合 SCIM 规范。

示例 4 - 使用筛选器更新复杂多值属性

请求：

PATCH https://microsoftgraph.chinacloudapi.cn/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "operations": [
    {
      "op": "replace",
      "path": "emails[type eq \"work\" and primary eq true].value",         
      "value": "{edited_username}@{{tenant_domain}}"      
    }
  ]
}

响应（204 无内容）：

响应符合 SCIM 规范。

示例 5 - 更新用户管理器

请求：

PATCH https://microsoftgraph.chinacloudapi.cn/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "operations": [
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager",
      "value": {
        "value": "915f96af-ea85-4687-b972-b26f69d719f9"
      }
    }
  ]
}

响应（204 无内容）：

响应符合 SCIM 规范。

示例 6 - 更新自定义安全属性

请求：

PATCH https://microsoftgraph.chinacloudapi.cn/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "operations": [
    {
      "op": "add",
      "path": "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:CustomSecurityAttributes:Project.ProjectName",
      "value": "IdentityHubV2"
    }
  ]
}

响应（204 无内容）： 响应符合 SCIM 规范。

删除用户

可以通过向具有现有用户 ID 的 /users 终结点发出 DELETE 请求来删除用户。

API 终结点：

删除 https://microsoftgraph.chinacloudapi.cn/rp/scim/users/{id}

成功后，API 返回 HTTP 状态 204。

权限

权限类型 权限（从最低到最高特权）
应用程序 User.ReadWrite.All

示例 1 - 删除用户

请求：

DELETE https://microsoftgraph.chinacloudapi.cn/rp/scim/users/ec3f07a3-2aa4-4666-b2fd-90e479428791
Authorization: Bearer {token}

响应（204 无内容）：

响应符合 SCIM 规范。

列出用户组

使用 /groups 终结点执行以下操作：

  • 获取租户中的所有组（使用分页）。

  • 获取与特定筛选条件匹配的组。

API 终结点：

https://microsoftgraph.chinacloudapi.cn/rp/scim/groups

成功后，API 返回 HTTP 状态 200。

如果响应包含多个页面，请使用 基于游标的分页 检索结果中的所有页面。

权限

权限类型 权限（从最低到最高特权）
应用程序 Group.Read.All、Group.ReadWrite.All

列表组的查询参数

以下 SCIM 查询参数可用于此 API 终结点：

  • filter - 指定要应用的筛选条件

  • attributes - 指定服务器应返回的组属性

  • excludedAttributes - 指定服务器应排除的组属性

  • count - 指定要检索的结果数（default=100）

  • cursor - 转到下一个结果页

列表组的约束

Microsoft Entra ID SCIM 实现具有以下约束：

  • 当结果中涉及多个页面时：

    • 每个页面的默认页面大小为 10 个条目。

    • 每个页面的最大页大小为 100 个条目。

  • 在查询参数中 filter ，仅支持“and”逻辑运算符。 “eq”比较运算符允许以下组属性。

    • displayName：将此属性设置为有效的Microsoft Entra组显示名称。
    • id：将此属性设置为租户中的有效Microsoft Entra组对象 ID（GUID）。
    • members.value：将此属性设置为租户中的有效Microsoft Entra用户对象 ID（GUID）。

  • 以下组属性可用于“ew”（以...结尾）比较运算符

    • displayName

  • 使用 member.value 筛选器时，不会评估嵌套组成员身份。 仅评估直接成员身份。

示例

以下示例仅包含请求详细信息。 为简洁起见，不包括响应。 它符合 SCIM 标准的响应负载。

示例 1 - 获取所有组

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/groups
Authorization: Bearer {token}

响应（200 正常）：

如果组数超过 100，则响应将包含 itemsPerPage 和 nextCursor 属性。 nextCursor使用该值检索结果的下一页。

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "itemsPerPage": 100,
  "nextCursor": "RFNwdAIAAQAAACpHcm91cF8zMDhiMzNkOC0wNjkxLTQzZTktOTA4Mi1kNG...",
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group",
        "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group"
      ],
      "id": "c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3",
      "displayName": "Sales and Marketing",
      "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group": {
        "description": "Description of Sales and Marketing",
        "groupTypes": [
          "Unified"
        ],
        "mailEnabled": true,
        "mailNickname": "SalesandMarketing",
        "securityEnabled": false,
        "securityIdentifier": "ffffffff-5a5a-6b6b-7c7c-888888888888"
      },
      "meta": {
        "created": "2022-01-11T01:23:26+00:00",
        "location": "/groups/c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3",
        "resourceType": "group"
      }
    },    
    { ... }
  ]
}

示例 1B - 检索下一页以获取所有组

上述查询默认返回每页 100 个组。 如果租户中有超过 100 个组，请使用分页处理，通过将查询参数设置为响应中收到的值 cursor 来检索下一组组。

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/groups?cursor=RFNwdAIAAQAAACpHcm91cF8zMDhiMzNkOC0wNjkxLTQzZTktOTA4Mi1kNG...
Authorization: Bearer {token}
Accept: application/json

示例 1C - 使用 count 参数控制返回的组

可以使用参数 count 检索特定数量的组。

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/groups?count=1000
Authorization: Bearer {token}
Accept: application/json

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/groups?count=1000&cursor=RFNwdAIAAQAAACpHcm91cF8zMDhiMzNkOC0wNjkxLTQzZTktOTA4Mi1kNG...
Authorization: Bearer {token}
Accept: application/json

示例 2 - 通过 ID 获取具有特定属性的组

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/groups?filter=id eq "dddddddd-3333-4444-5555-eeeeeeeeeeee"&attributes=displayName
Authorization: Bearer {token}

示例 3 - 按 ID 获取排除属性的分组

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/groups?filter=id eq "dddddddd-3333-4444-5555-eeeeeeeeeeee"&excludedAttributes=displayName
Authorization: Bearer {token}

示例 4 - 按 displayName 获取组

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/groups?filter=displayName eq "GroupA"
Authorization: Bearer {token}

响应（200 正常）：

响应已为提高可读性而被截短。

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "a6a6a6a6-bbbb-cccc-dddd-e7e7e7e7e7e7",
      "displayName": "GroupA",
      "meta": {
        "location": "/groups/a6a6a6a6-bbbb-cccc-dddd-e7e7e7e7e7e7",
        "resourceType": "group"
      }
    }
  ]
}

示例 5 - 按成员获取组

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/groups?filter=members.value eq "d4b34e9e-0ad7-42df-b1f6-401b41fe1bee"
Authorization: Bearer {token}

响应（200 正常）：

响应包括用户所属的已分配组和动态组。

根据ID获取组

通过向具有组 ID 的 /groups 终结点发出 GET 请求来检索现有组。

API 终结点：

https://microsoftgraph.chinacloudapi.cn/rp/scim/groups/{id}

成功后，API 返回 HTTP 状态 200。

权限

权限类型 权限（从最低到最高特权）
应用程序 Group.Read.All、Group.ReadWrite.All

按 ID 获取组的约束

  • 此 API 调用不会返回组成员。 将 GET /groups 与 members.value 筛选器配合使用，检索用户是成员的组。

按 ID 获取组的查询参数

以下 SCIM 查询参数可用于此 API 终结点：

  • attributes - 指定服务器应返回哪些组属性。

  • excludedAttributes - 指定服务器应排除哪些组属性。

示例 1 - 按 ID 获取组

请求：

GET https://microsoftgraph.chinacloudapi.cn/rp/scim/groups/dddddddd-3333-4444-5555-eeeeeeeeeeee
Authorization: Bearer {token}

响应（200 正常）：

响应已为提高可读性而被截短。

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group"
  ],
  "id": "dddddddd-3333-4444-5555-eeeeeeeeeeee",
  "displayName": "GroupA",
  "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group": {
    "description": "Group for All Employees - Baseline access",
    "mailEnabled": false,
    "mailNickname": "3c998a58-6",
    "securityEnabled": true,
    "securityIdentifier": "ffffffff-5a5a-6b6b-7c7c-888888888888"
  },
  "meta": {
    "created": "2024-05-23T17:21:41+00:00",
    "location": "/groups/dddddddd-3333-4444-5555-eeeeeeeeeeee",
    "resourceType": "group"
  }
}

创建组

可以通过向 /groups 终结点发送 POST 请求，在 Microsoft Entra ID 中创建新组。

API 终结点：

发布 https://microsoftgraph.chinacloudapi.cn/rp/scim/groups

成功后，API 返回 HTTP 状态 201。

权限

权限类型 权限（从最低到最高特权）
应用程序 Group.ReadWrite.All

创建组所需的属性

成功创建组需要以下属性：

  • displayName

示例 1 - 创建新组

请求：

POST https://microsoftgraph.chinacloudapi.cn/rp/scim/groups
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group"
  ],
  "displayName": "Test SCIM Group",
  "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group": { 
    "mailEnabled": false, 
    "mailNickname": "test-scim-group", 
    "securityEnabled": true 
  }
}

响应（201 已创建）：

返回创建的组的 SCIM 表示形式。

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group",
    "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group"
  ],
  "id": "66aa66aa-bb77-cc88-dd99-00ee00ee00ee",
  "displayName": "Test SCIM Group",
  "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group": {
    "mailEnabled": false,
    "mailNickname": "test-scim-group",
    "securityEnabled": true,
    "securityIdentifier": "ffffffff-5a5a-6b6b-7c7c-888888888888"
  },
  "meta": {
    "created": "2026-03-30T16:28:37+00:00",
    "location": "/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee",
    "resourceType": "group"
  }
}

更新一个组

终结点 /groups 允许发出 PATCH 请求来更新现有组。

API 终结点：

补丁 https://microsoftgraph.chinacloudapi.cn/rp/scim/groups/{id}

成功后，API 返回 HTTP 状态 200。

权限

权限类型 权限（从最低到最高特权）
应用程序 Group.ReadWrite.All

更新组的约束

  • 必须在单个 PATCH 操作 对象中将成员添加到组。  

  • 使用 API 在一个请求中添加多个成员时，最多只能添加 20 个成员。 

  • 每个 PATCH 调用只能从组中删除一个成员。  

  • 删除组成员时，必须完成此操作，且不得在同一 PATCH 调用中包含任何其他属性的更改（包括添加成员）。  

  • 必须在没有任何其他属性更改（包括删除成员）的情况下将成员添加到组。  

  • 添加组成员被视为 幂等 操作。 如果组中已存在特定成员，则不会返回任何错误，并且只要所有组 memberId 指向 有效的用户对象，该操作就成功。

  • 如果在组成员身份添加或删除操作中传递的 memberId 无效，则整个操作将失败，错误消息 “Resource '00000000-0000-0000-0000-000000000000' 不存在，或者其中一个查询的引用属性对象不存在。

示例 1 - 更新组显示名称

请求：

PATCH https://microsoftgraph.chinacloudapi.cn/rp/scim/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "SCIM Testing Group Edited"
    }
  ]
}

响应（204 无内容）：

响应符合 SCIM 规范。

示例 2 - 更新组说明

请求：

PATCH https://microsoftgraph.chinacloudapi.cn/rp/scim/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "operations": [
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:Microsoft:Entra:2.0:Group:description",
      "value": "Finance group"
    }
  ]
}

响应（204 无内容）：

响应符合 SCIM 规范。

示例 3 - 添加组成员

请求：

PATCH https://microsoftgraph.chinacloudapi.cn/rp/scim/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "756b18d2-023a-4fa8-845e-9ac8b524100f"
        },
        {
          "value": "0e4c70dd-c015-48db-bb5a-6264d215ca8e"
        }
      ]
    }
  ]
}

响应（204 无内容）：

响应符合 SCIM 规范。

示例 4 - 删除组成员

请求：

PATCH https://microsoftgraph.chinacloudapi.cn/rp/scim/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee
Authorization: Bearer {token}
Content-Type: application/scim+json

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "remove",
      "path": "members[value eq \"aaaaaaaa-6666-7777-8888-bbbbbbbbbbbb\"]"
    }
  ]
}

响应（204 无内容）：

响应符合 SCIM 规范。

删除组

可以通过向具有现有组 ID 的 /groups 终结点发出 DELETE 请求来删除组。

API 终结点：

删除 https://microsoftgraph.chinacloudapi.cn/rp/scim/groups/{id}

成功后，API 返回 HTTP 状态 204。

权限

权限类型 权限（从最低到最高特权）
应用程序 Group.ReadWrite.All

示例 1 - 删除组

请求：

DELETE https://microsoftgraph.chinacloudapi.cn/rp/scim/groups/66aa66aa-bb77-cc88-dd99-00ee00ee00ee
Authorization: Bearer {token}

响应（204 无内容）：

响应符合 SCIM 规范。

相关内容

  • Last updated on