# 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"  } 
```