## **使用说明** SCIM 2.0接口的实现遵循 RFC 7644，具体请求说明请参见 [RFC文档](https://datatracker.ietf.org/doc/html/rfc7644) ## Endpoint 和 Region SCIM服务对应的接入点（Endpoint）：https://cloudidentity\-scim.${region}.volces.com/scim/v2/ ## SCIM 2.0 接口 |分类 |接口 |支持情况 |备注 | |---|---|---|---| |/Me |无 |不支持 |无 | |/Bulk |无 |不支持 |无 | |Discovery Endpoint |/ServiceProviderConfig |支持 |描述服务提供方（Service Provider）支持的 SCIM 规范特性 | |^^|/ResourceTypes |支持 |用于发现 SCIM 服务提供方支持的资源类型（例如：用户 Users、用户组 Groups） | |^^|/Schemas |支持 |用于获取 SCIM 服务提供方支持的资源架构（schema）信息 | |/Users |GET /Users |支持 |按条件查询用户信息或查询所有用户列表|\ | | | |当不指定 filter 时，返回全量用户 | |^^|GET /Users/{id} |支持 |查询指定 ID 的用户 | |^^|POST /Users |支持 |创建用户 | |^^|PUT /Users/{id} |支持 |替换指定 ID 的用户信息 | |^^|DELETE /Users/{id} |支持 |删除指定 ID 的用户 | |^^|PATCH /Users/{id} |支持 |更新指定 ID 的用户信息，支持 add（添加）、remove（移除）、replace（覆盖） | |/Groups |GET /Groups|支持 |按条件查询用户组信息或查询所有用户组列表|\ | | | |当不指定 filter 时，返回全量用户组 | |^^|GET /Groups/{id} |支持 |查询指定 ID 的用户组 | |^^|POST /Groups |支持 |创建用户组 | |^^|PUT /Groups/{id} |支持 |替换指定 ID 的用户组信息 | |^^|DELETE /Groups/{id} |支持 |删除指定 ID 的用户组 | |^^|PATCH /Groups/{id} |支持 |更新指定 ID 的用户组信息 | ## Discovery Endpoint ### /ServiceProviderConfig #### 功能描述获取服务提供方配置 #### 请求示例 ```sql curl --location 'https://cloudidentity-scim.cn-beijing.volces.com/scim/v2/ServiceProviderConfig' \ --header 'Authorization: Bearer ••••••' ``` #### 返回示例 ```json { "authenticationSchemes": [ { "description": "Authentication using OAuth Bearer Token", "documentationUri": "https://www.volcengine.com/docs/7165/1524159", "name": "OAuth Bearer Token", "primary": true, "specUri": "https://tools.ietf.org/html/rfc6750", "type": "oauth2" } ], "bulk": { "maxOperations": 0, "maxPayloadSize": 0, "supported": false }, "changePassword": { "supported": false }, "documentationUri": "https://www.volcengine.com/docs/7165/1524159", "etag": { "supported": false }, "filter": { "maxResults": 100, "supported": true }, "patch": { "supported": true }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig" ], "sort": { "supported": false } } ``` ### /ResourceTypes #### 功能描述用于发现 SCIM 服务提供方支持的资源类型（例如：用户 Users、用户组 Groups）。 #### 请求示例 ```bash curl --location 'https://cloudidentity-scim.cn-beijing.volces.com/scim/v2/ResourceTypes' \ --header 'Authorization: Bearer ••••••' ``` #### 返回示例 ```json { "itemsPerPage": 2, "resources": [ { "description": "Work-Force User", "endpoint": "/Users", "id": "User", "meta": { "location": "/ResourceTypes/User", "resourceType": "ResourceType" }, "name": "User", "schema": "urn:ietf:params:scim:schemas:core:2.0:User", "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:ResourceType" ] }, { "description": "Work-Force User Group", "endpoint": "/Groups", "id": "Group", "meta": { "location": "/ResourceTypes/Group", "resourceType": "ResourceType" }, "name": "Group", "schema": "urn:ietf:params:scim:schemas:core:2.0:Group", "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:ResourceType" ] } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:ListResponse" ], "startIndex": 1, "totalResults": 2 } ``` ### /Schemas #### 功能描述用于获取 SCIM 服务提供方支持的资源架构（schema）信息。 #### 请求示例 ```bash curl --location 'https://cloudidentity-scim.cn-beijing.volces.com/scim/v2/Schemas' \ --header 'Authorization: Bearer ••••••' ``` #### 返回示例 ```json { "itemsPerPage": 2, "resources": [ { "attributes": [ { "caseExact": false, "description": "Human-Readable User Unique Identifier", "multiValued": false, "mutability": "readWrite", "name": "userName", "required": true, "returned": "always", "type": "string", "uniqueness": "server" }, { "caseExact": false, "description": "Display Name for Assisting in User Identity Identification, Non-Unique", "multiValued": false, "mutability": "readWrite", "name": "displayName", "required": false, "returned": "default", "type": "string", "uniqueness": "none" }, { "caseExact": false, "description": "Contact Email of User", "multiValued": true, "mutability": "readWrite", "name": "emails", "required": false, "returned": "default", "subAttributes": [ { "caseExact": false, "multiValued": false, "mutability": "readWrite", "name": "value", "required": true, "returned": "default", "type": "string", "uniqueness": "none" } ], "type": "complex", "uniqueness": "none" }, { "caseExact": false, "description": "Contact mobile number of User", "multiValued": true, "mutability": "readWrite", "name": "phoneNumbers", "required": false, "returned": "default", "subAttributes": [ { "caseExact": false, "multiValued": false, "mutability": "readWrite", "name": "value", "required": true, "returned": "default", "type": "string", "uniqueness": "none" } ], "type": "complex", "uniqueness": "none" } ], "description": "Work-Force User", "id": "urn:ietf:params:scim:schemas:core:2.0:User", "meta": { "location": "/Schemas/urn:ietf:params:scim:schemas:core:2.0:User", "resourceType": "Schema" }, "name": "User", "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Schema" ] }, { "attributes": [ { "caseExact": false, "description": "Human-Readable User Group Unique Identifier", "multiValued": false, "mutability": "readWrite", "name": "displayName", "required": true, "returned": "always", "type": "string", "uniqueness": "none" }, { "caseExact": false, "description": "Display Name for User Group, Non-Unique", "multiValued": true, "mutability": "readWrite", "name": "members", "required": false, "returned": "default", "subAttributes": [ { "caseExact": false, "multiValued": false, "mutability": "readWrite", "name": "value", "required": true, "returned": "default", "type": "string", "uniqueness": "none" } ], "type": "complex", "uniqueness": "none" } ], "description": "Work-Force User Group", "id": "urn:ietf:params:scim:schemas:core:2.0:Group", "meta": { "location": "/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group", "resourceType": "Schema" }, "name": "Group", "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Schema" ] } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:ListResponse" ], "startIndex": 1, "totalResults": 2 } ``` ## /Users ### GET /Users #### 功能描述按条件查询用户信息或查询所有用户列表。 #### 使用约束 * filter 只支持 externalId、userName、id 过滤，且只支持 eq 和 and 操作符。 * 支持 SCIM 协议的分页方式，每页最多返回 100 条记录，如果记录条数大于 100（count \> 100），则按 100 处理。 * 仅能查询由 SCIM 同步的用户 |参数 |参数取值说明 |示例 | |---|---|---| |filter |仅支持 userName、externalId、id 的 eq 和 and 表达式。 |* filter=Id eq 3001234662656|\ | | |* filter=externalId eq exid\-sfji2ni3ti3|\ | | |* filter=userName eq test\-user | |startIndex |可置空，默认值为1，表示标号。 |\- startIndex=1 | |count |可置空，默认值为10，表示每页用户个数。 |\- count=100 | #### 请求示例 ```bash curl --location 'https://cloudidentity-scim.cn-beijing.volces.com/scim/v2/Users?filter=id+eq+%223001234662656%22' \ --header 'Authorization: Bearer ••••••' ``` #### 返回示例 ```json { "itemsPerPage": 100, "resources": [ { "displayName": "test-user", "emails": [], "id": "3001234662656", "meta": { "created": "2025-04-15T08:17:13Z", "lastModified": "2025-04-15T08:17:13Z", "location": "/Users/3001234662656", "resourceType": "User" }, "phoneNumbers": [], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "userName": "test" } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:ListResponse" ], "startIndex": 1, "totalResults": 1 } ``` ### GET /Users/{id} #### 功能描述查询指定 ID 的用户 #### 使用约束 * 如果 id 对应的用户不存在，则会拒绝访问 #### 请求示例 ```bash curl --location 'https://cloudidentity-scim.cn-beijing.volces.com/scim/v2/Users/3001234662656' \ --header 'Authorization: Bearer ••••••' ``` #### 返回示例 ```json { "displayName": "test-user", "emails": [], "id": "3001234662656", "meta": { "created": "2025-04-15T08:17:13Z", "lastModified": "2025-04-15T08:17:13Z", "location": "/Users/3001234662656", "resourceType": "User" }, "phoneNumbers": [], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "userName": "test" } ``` ### POST /Users #### 功能描述创建用户 #### 使用约束 * 如果云身份中心实例中存在同名的用户，会拒绝创建 * 如果云身份中心实例中存在相同 externalId 的用户，会拒绝创建 #### 请求示例 ```bash curl --location --request POST 'https://cloudidentity-scim.cn-beijing.volces.com/scim/v2/Users' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ••••••' \ --data-raw '{ "displayName": "test-user", "emails": [ { "value":"" } ], "phoneNumbers": [ { "value":"" } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "userName": "test-user" }' ``` #### 返回示例 ```json { "displayName": "test-user", "emails": [ { "primary": true, "type": "work", "value": "" } ], "id": "3158367515904", "meta": { "created": "2025-05-08T10:52:32Z", "lastModified": "2025-05-08T10:52:32Z", "location": "/Users/3158367515904", "resourceType": "User" }, "phoneNumbers": [ { "primary": true, "value": "", "type": "work" } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "userName": "test-user" } ``` ### PUT /Users/{id} #### 功能描述替换指定 ID 的用户信息 #### 使用约束 * {id}必传，修改的字段范围为 Schema 中定义的字段 * 如果 id 对应的用户不存在，则会拒绝访问 * PUT 为覆盖原有属性 * PUT 如果不传字段则不更新该字段，如果字段为空则会将该字段覆盖为空 * 仅能修改 SCIM 同步的用户 #### 请求示例 ```bash curl --location --request PUT 'https://cloudidentity-scim.cn-beijing.volces.com/scim/v2/Users/3158367515904' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ••••••' \ --data '{ "externalId": "test-exid", "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "userName": "test-user" }' ``` #### 返回示例 ```json { "displayName": "test-user", "emails": [ { "primary": true, "type": "work", "value": "" } ], "externalId": "test-exid", "id": "3158367515904", "meta": { "created": "2025-05-08T10:52:32Z", "lastModified": "2025-05-08T10:59:08Z", "location": "/Users/3158367515904", "resourceType": "User" }, "phoneNumbers": [ { "primary": true, "value": "", "type": "work" } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "userName": "test-user" } ``` ### DELETE /Users/{id} #### 功能描述删除指定 ID 的用户 #### 使用约束 * {id}必传 * 如果 id 对应的用户不存在，则会拒绝访问 * 仅能删除 SCIM 同步的用户 #### 请求示例 ```bash curl --location --request DELETE 'https://cloudidentity-scim.cn-beijing.volces.com/scim/v2/Users/3158367515904' \ --header 'Authorization: Bearer ••••••' ``` ### PATCH /Users/{id} #### 功能描述更新指定 ID 的用户信息 #### 使用约束 * {id}必传 * 如果 id 对应的用户不存在，则会拒绝访问 * 仅能修改 SCIM 同步的用户信息 * Operation 最大支持长度为 10 * Patch 支持 Add、Replace 和 Remove #### 请求示例 ```bash curl --location --request PATCH 'https://cloudidentity-scim.cn-beijing.volces.com/scim/v2/Users/3158367515904' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ••••••' \ --data '{ "Operations": [ { "op": "remove", "path": "displayName" } ], "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ] }' ``` #### Operation 示例 ```json // 清除 displayName { "Operations": [ { "op": "remove", "path": "displayName" } ], "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ] } // 覆盖邮箱、展示名、用户名 { "Operations": [ { "op": "replace", "value": { "emails": [ { "primary": true, "type": "work", "value": "youremail2@test.com" } ], "displayName": "test-displayName", "userName": "test-userName" } } ], "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ] } // 添加邮箱 { "Operations": [ { "op": "add", "path": "emails[type eq \"work\"]", "value": { "value": "" } } ], "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ] } ``` ## /Groups ### GET /Groups #### 功能描述按条件查询用户组信息或查询所有用户组列表。 #### 使用约束 * filter 只支持 externalId、displayName、id 过滤，且只支持 eq 和 and 操作符。 * 支持 SCIM 协议的分页方式，每页最多返回 100 条记录，如果记录条数大于 100（count \> 100），则按 100 处理。 * 仅能查询由 SCIM 同步的用户组 |参数 |参数取值说明 |示例 | |---|---|---| |filter |仅支持 displayName、externalId、id 的 eq 和 and 表达式。 |* filter=Id eq 30012346621521|\ | | |* filter=externalId eq exid\-g\-sfji2ni3ti3|\ | | |* filter=displayName eq test\-group | |startIndex |可置空，默认值为1，表示标号。 |startIndex=1 | |count |可置空，默认值为10，表示每页用户组个数。 |count=100 | #### 请求示例 ```bash curl --location 'https://https://cloudidentity-scim.cn-beijing.volces.com/scim/v2/Groups?filter=id%20eq%20%223000927463168%22' \ --header 'Authorization: Bearer ••••••' ``` #### 返回示例 ```json { "itemsPerPage": 100, "resources": [ { "displayName": "test-group", "id": "3000927463168", "members": [], "meta": { "created": "2025-04-15T10:02:08Z", "lastModified": "2025-04-21T03:17:53Z", "location": "/Groups/3000927463168", "resourceType": "Group" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ] } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:ListResponse" ], "startIndex": 1, "totalResults": 1 } ``` ### GET /Groups/{id} #### 功能描述查询指定 ID 的用户组 #### 使用约束 * 如果 id 对应的用户组不存在，则会拒绝访问 #### 请求示例 ```bash curl --location 'https://cloudidentity-scim.cn-beijing.volces.com/scim/v2/Groups/3000927463168' \ --header 'Authorization: Bearer ••••••' ``` #### 返回示例 ```json { "displayName": "displayName", "id": "3000927463168", "members": [], "meta": { "created": "2025-04-15T10:02:08Z", "lastModified": "2025-04-21T03:17:53Z", "location": "/Groups/3000927463168", "resourceType": "Group" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ] } ``` ### POST /Groups #### 功能描述创建用户组 #### 使用约束 * 如果云身份中心实例中存在同名的用户组，会拒绝创建 * 如果云身份中心实例中存在相同 externalId 的用户组，会拒绝创建 #### 请求示例 ```bash curl --location 'https://cloudidentity-scim.cn-beijing.volces.com/scim/v2/Groups' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ••••••' \ --data '{ "displayName": "test-group-12519512", "externalId": "ex-g-2139251251", "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ] }' ``` #### 返回示例 ```json { "displayName": "test-group-12519512", "externalId": "ex-g-2139251251", "id": "3162821984768", "members": [], "meta": { "created": "2025-05-08T12:05:50Z", "lastModified": "2025-05-08T12:05:50Z", "location": "/Groups/3162821984768", "resourceType": "Group" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ] } ``` ### PUT /Groups/{id} #### 功能描述替换指定 ID 的用户组信息 #### 使用约束 * {id} 必传，修改的字段范围为 Schema 中定义的字段。 * 如果 id 对应的用户组不存在，则会拒绝访问 * PUT 为覆盖原有属性 * PUT 如果不传字段则不更新该字段，如果字段为空则会将该字段覆盖为空 * 仅能修改 SCIM 同步的用户组 * 仅能添加 SCIM 同步的用户加入用户组 * 不会返回用户组成员列表 * PUT 覆盖用户组成员时，一次 PUT 仅支持覆盖 100 个用户 #### 请求示例 ```json { "displayName": "test-group", "externalId": "ex-g-124924", "members": [ { "value": "3001234662656" } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ] } ``` #### 返回示例 ```json { "displayName": "test-group", "externalId": "ex-g-124924", "id": "3162821984768", "members": [], "meta": { "created": "2025-05-08T12:05:50Z", "lastModified": "2025-05-08T12:08:02Z", "location": "/Groups/3162821984768", "resourceType": "Group" }, "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ] } ``` ### DELETE /Groups/{id} #### 功能描述删除指定 ID 的用户组 #### 使用约束 * {id}必传 * 如果 id 对应的用户组不存在，则会拒绝访问 * 仅能删除 SCIM 同步的用户组 #### 请求示例 ```bash curl --location --request DELETE 'https://cloudidentity-scim.cn-beijing.volces.com/scim/v2/Groups/3162821984768' \ --header 'Authorization: Bearer ••••••' ``` ### PATCH /Groups/{id} #### 功能描述更新指定 ID 的用户组信息 #### 使用约束 * {id}必传 * 如果 id 对应的用户组不存在，则会拒绝访问 * 仅能修改 SCIM 同步的用户组信息 * Operation 最大支持长度为 10 * Patch 支持 Add、Replace 和 Remove * 一个 Operation 仅支持传入 100 个 members #### 请求示例 ```bash curl --location --request PATCH 'https://cloudidentity-scim.cn-beijing.volces.com/scim/v2/Groups/3000927463168' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data ' { "Operations": [ { "op": "remove", "path": "members[value eq \"21425125124312\"]" } ], "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ] } ' ``` #### Operation 示例 ```json // 清除 externalId { "Operations": [ { "op": "remove", "path": "externalId" } ], "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ] } // 清除指定 id 的 members { "Operations": [ { "op": "remove", "path": "members[value eq \"21425125124312\"]" } ], "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ] } // 覆盖展示名，成员 { "Operations": [ { "op": "replace", "value": { "displayName": "test-displayName", "members": [ { "value": "" } ] } } ], "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ] } // 添加成员 { "Operations": [ { "op": "add", "path": "members", "value": { "value": "" } } ], "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ] } ```