2020-10-28 15:08:49 +00:00
---
2020-10-30 18:08:56 +00:00
type: reference, howto
stage: Manage
group: Access
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-10-28 15:08:49 +00:00
---
2020-10-30 18:08:56 +00:00
# SCIM API (SYSTEM ONLY) **(SILVER ONLY)**
2019-05-18 21:27:41 +00:00
2020-10-30 18:08:56 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.10.
2019-05-18 21:27:41 +00:00
2020-10-30 18:08:56 +00:00
The SCIM API implements the [RFC7644 protocol ](https://tools.ietf.org/html/rfc7644 ). As this API is for
**system** use for SCIM provider integration, it is subject to change without notice.
2019-05-18 21:27:41 +00:00
2020-10-30 18:08:56 +00:00
To use this API, [Group SSO ](../user/group/saml_sso/index.md ) must be enabled for the group.
This API is only in use where [SCIM for Group SSO ](../user/group/saml_sso/scim_setup.md ) is enabled. It's a prerequisite to the creation of SCIM identities.
2019-05-18 21:27:41 +00:00
## Get a list of SAML users
2020-10-30 18:08:56 +00:00
This endpoint is used as part of the SCIM syncing mechanism. It only returns
2019-05-18 21:27:41 +00:00
a single user based on a unique ID which should match the `extern_uid` of the user.
2020-05-20 03:08:04 +00:00
```plaintext
2019-05-18 21:27:41 +00:00
GET /api/scim/v2/groups/:group_path/Users
```
Parameters:
| Attribute | Type | Required | Description |
|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------|
2019-11-12 00:06:21 +00:00
| `filter` | string | no | A [filter ](#available-filters ) expression. |
2019-05-18 21:27:41 +00:00
| `group_path` | string | yes | Full path to the group. |
2019-10-01 09:10:39 +00:00
| `startIndex` | integer | no | The 1-based index indicating where to start returning results from. A value of less than one will be interpreted as 1. |
| `count` | integer | no | Desired maximum number of query results. |
2020-12-04 21:09:29 +00:00
NOTE:
2019-10-01 09:10:39 +00:00
Pagination follows the [SCIM spec ](https://tools.ietf.org/html/rfc7644#section-3.4.2.4 ) rather than GitLab pagination as used elsewhere. If records change between requests it is possible for a page to either be missing records that have moved to a different page or repeat records from a previous request.
2019-05-18 21:27:41 +00:00
Example request:
2020-01-30 15:09:15 +00:00
```shell
2020-08-19 21:10:32 +00:00
curl 'https://gitlab.example.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"
2019-05-18 21:27:41 +00:00
```
Example response:
```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
2020-05-20 03:08:04 +00:00
```plaintext
2019-05-18 21:27:41 +00:00
GET /api/scim/v2/groups/:group_path/Users/:id
```
Parameters:
| Attribute | Type | Required | Description |
|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------|
| `id` | string | yes | External UID of the user. |
| `group_path` | string | yes | Full path to the group. |
Example request:
2020-01-30 15:09:15 +00:00
```shell
2020-08-19 21:10:32 +00:00
curl "https://gitlab.example.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"
2019-05-18 21:27:41 +00:00
```
Example response:
```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
2020-05-20 03:08:04 +00:00
```plaintext
2019-05-18 21:27:41 +00:00
POST /api/scim/v2/groups/:group_path/Users/
```
Parameters:
| Attribute | Type | Required | Description |
|:---------------|:----------|:----|:--------------------------|
| `externalId` | string | yes | External UID of the user. |
| `userName` | string | yes | Username of the user. |
| `emails` | JSON string | yes | Work email. |
| `name` | JSON string | yes | Name of the user. |
2020-03-02 00:07:41 +00:00
| `meta` | string | no | Resource type (`User`). |
2019-05-18 21:27:41 +00:00
Example request:
2020-01-30 15:09:15 +00:00
```shell
2020-08-19 21:10:32 +00:00
curl --verbose --request POST "https://gitlab.example.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"
2019-05-18 21:27:41 +00:00
```
Example response:
```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
}
]
}
```
Returns a `201` status code if successful.
## Update a single SAML user
Fields that can be updated are:
2020-05-07 06:09:38 +00:00
| SCIM/IdP field | GitLab field |
|:---------------------------------|:---------------------------------------|
| `id/externalId` | `extern_uid` |
| `name.formatted` | `name` |
| `emails\[type eq "work"\].value` | `email` |
| `active` | Identity removal if `active` = `false` |
| `userName` | `username` |
2019-05-18 21:27:41 +00:00
2020-05-20 03:08:04 +00:00
```plaintext
2019-05-18 21:27:41 +00:00
PATCH /api/scim/v2/groups/:group_path/Users/:id
```
Parameters:
| Attribute | Type | Required | Description |
|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------|
| `id` | string | yes | External UID of the user. |
| `group_path` | string | yes | Full path to the group. |
| `Operations` | JSON string | yes | An [operations ](#available-operations ) expression. |
Example request:
2020-01-30 15:09:15 +00:00
```shell
2020-08-19 21:10:32 +00:00
curl --verbose --request PATCH "https://gitlab.example.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"
2019-05-18 21:27:41 +00:00
```
Returns an empty response with a `204` status code if successful.
## Remove a single SAML user
Removes the user's SSO identity and group membership.
2020-05-20 03:08:04 +00:00
```plaintext
2019-05-18 21:27:41 +00:00
DELETE /api/scim/v2/groups/:group_path/Users/:id
```
Parameters:
| Attribute | Type | Required | Description |
|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------|
| `id` | string | yes | External UID of the user. |
| `group_path` | string | yes | Full path to the group. |
Example request:
2020-01-30 15:09:15 +00:00
```shell
2020-08-19 21:10:32 +00:00
curl --verbose --request DELETE "https://gitlab.example.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"
2019-05-18 21:27:41 +00:00
```
Returns an empty response with a `204` status code if successful.
## Available filters
They match an expression as specified in [the RFC7644 filtering section ](https://tools.ietf.org/html/rfc7644#section-3.4.2.2 ).
| Filter | Description |
| ----- | ----------- |
| `eq` | The attribute matches exactly the specified value. |
Example:
2020-02-28 03:09:04 +00:00
```plaintext
2019-05-18 21:27:41 +00:00
id eq a-b-c-d
```
## Available operations
They perform an operation as specified in [the RFC7644 update section ](https://tools.ietf.org/html/rfc7644#section-3.5.2 ).
| Operator | Description |
| ----- | ----------- |
| `Replace` | The attribute's value is updated. |
| `Add` | The attribute has a new value. |
Example:
```json
{ "op": "Add", "path": "name.formatted", "value": "New Name" }
```