SCIM API · Gitlab 中文文档

# SCIM API > 原文：[https://docs.gitlab.com/ee/api/scim.html](https://docs.gitlab.com/ee/api/scim.html) * [Get a list of SAML users](#get-a-list-of-saml-users) * [Get a single SAML user](#get-a-single-saml-user) * [Create a SAML user](#create-a-saml-user) * [Update a single SAML user](#update-a-single-saml-user) * [Remove a single SAML user](#remove-a-single-saml-user) * [Available filters](#available-filters) * [Available operations](#available-operations) # SCIM API[](#scim-api-silver-only "Permalink") [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in [GitLab Silver](https://about.gitlab.com/pricing/) 11.10. SCIM API 实现[RFC7644 协议](https://tools.ietf.org/html/rfc7644) . **警告：**此 API 供内部系统用于与 SCIM 提供程序连接. 虽然可以直接使用，但如有更改，恕不另行通知.**注意：**必须为组启用[组 SSO](../user/group/saml_sso/index.html) . 有关更多信息，请参见[SCIM 设置文档](../user/group/saml_sso/scim_setup.html#requirements) . ## Get a list of SAML users[](#get-a-list-of-saml-users "Permalink") **注意：**此端点用作 SCIM 同步机制的一部分，并且它仅基于唯一 ID（应与用户的`extern_uid`相匹配）返回一个用户. ``` GET /api/scim/v2/groups/:group_path/Users ``` Parameters: | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `filter` | string | no | A [filter](#available-filters) expression. | | `group_path` | string | yes | 组的完整路径. | | `startIndex` | integer | no | 从 1 开始的索引，指示从何处开始返回结果. 小于 1 的值将被解释为 1. | | `count` | integer | no | 所需的最大查询结果数. | **注意：**分页遵循[SCIM 规范，](https://tools.ietf.org/html/rfc7644#section-3.4.2.4)而不是其他地方使用的 GitLab 分页. 如果记录在请求之间更改，则页面可能丢失已移至其他页面的记录，或者重复上一个请求的记录. 请求示例： ``` curl 'https://example.gitlab.com/api/scim/v2/groups/test_group/Users?filter=id%20eq%20"0b1d561c-21ff-4092-beab-8154b17f82f2"' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" ``` 响应示例： ``` { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ], "totalResults": 1, "itemsPerPage": 20, "startIndex": 1, "Resources": [ { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "0b1d561c-21ff-4092-beab-8154b17f82f2", "active": true, "name.formatted": "Test User", "userName": "username", "meta": { "resourceType":"User" }, "emails": [ { "type": "work", "value": "name@example.com", "primary": true } ] } ] } ``` ## Get a single SAML user[](#get-a-single-saml-user "Permalink") ``` GET /api/scim/v2/groups/:group_path/Users/:id ``` Parameters: | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | yes | 用户的外部 UID. | | `group_path` | string | yes | 组的完整路径. | 请求示例： ``` curl "https://example.gitlab.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" ``` 响应示例： ``` { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "0b1d561c-21ff-4092-beab-8154b17f82f2", "active": true, "name.formatted": "Test User", "userName": "username", "meta": { "resourceType":"User" }, "emails": [ { "type": "work", "value": "name@example.com", "primary": true } ] } ``` ## Create a SAML user[](#create-a-saml-user "Permalink") ``` POST /api/scim/v2/groups/:group_path/Users/ ``` Parameters: | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `externalId` | string | yes | 用户的外部 UID. | | `userName` | string | yes | 用户的用户名. | | `emails` | JSON 字符串 | yes | 工作电子邮件. | | `name` | JSON 字符串 | yes | 用户名. | | `meta` | string | no | 资源类型（ `User` ）. | 请求示例： ``` curl --verbose --request POST "https://example.gitlab.com/api/scim/v2/groups/test_group/Users" --data '{"externalId":"test_uid","active":null,"userName":"username","emails":[{"primary":true,"type":"work","value":"name@example.com"}],"name":{"formatted":"Test User","familyName":"User","givenName":"Test"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"meta":{"resourceType":"User"}}' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" ``` 响应示例： ``` { "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "id": "0b1d561c-21ff-4092-beab-8154b17f82f2", "active": true, "name.formatted": "Test User", "userName": "username", "meta": { "resourceType":"User" }, "emails": [ { "type": "work", "value": "name@example.com", "primary": true } ] } ``` 如果成功，则返回`201`状态代码. ## Update a single SAML user[](#update-a-single-saml-user "Permalink") 可以更新的字段是： | SCIM / IdP 字段 | GitLab 领域 | | --- | --- | | `id/externalId` | `extern_uid` | | `name.formatted` | `name` | | `emails\[type eq "work"\].value` | `email` | | `active` | 如果`active` = `false`删除身份 | | `userName` | `username` | ``` PATCH /api/scim/v2/groups/:group_path/Users/:id ``` Parameters: | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | yes | 用户的外部 UID. | | `group_path` | string | yes | 组的完整路径. | | `Operations` | JSON 字符串 | yes | An [operations](#available-operations) expression. | 请求示例： ``` curl --verbose --request PATCH "https://example.gitlab.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" --data '{ "Operations": [{"op":"Add","path":"name.formatted","value":"New Name"}] }' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" ``` 如果成功，则返回带有`204`状态代码的空响应. ## Remove a single SAML user[](#remove-a-single-saml-user "Permalink") 删除用户的 SSO 身份和组成员身份. ``` DELETE /api/scim/v2/groups/:group_path/Users/:id ``` Parameters: | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | yes | 用户的外部 UID. | | `group_path` | string | yes | 组的完整路径. | 请求示例： ``` curl --verbose --request DELETE "https://example.gitlab.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" ``` 如果成功，则返回带有`204`状态代码的空响应. ## Available filters[](#available-filters "Permalink") 它们与[RFC7644 过滤部分中](https://tools.ietf.org/html/rfc7644#section-3.4.2.2)指定的表达式匹配. | Filter | Description | | --- | --- | | `eq` | 该属性与指定值完全匹配. | Example: ``` id eq a-b-c-d ``` ## Available operations[](#available-operations "Permalink") They perform an operation as specified in [the RFC7644 update section](https://tools.ietf.org/html/rfc7644#section-3.5.2). | Operator | Description | | --- | --- | | `Replace` | 该属性的值已更新. | | `Add` | 该属性具有新值. | Example: ``` { "op": "Add", "path": "name.formatted", "value": "New Name" } ```