1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
---
type: reference, howto
stage: Govern
group: Authentication
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# SCIM API **(PREMIUM SAAS)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98354) in GitLab 15.5.
The GitLab SCIM API manages SCIM identities within groups and provides the `/Users` endpoint. The base URL is `/api/scim/v2/groups/:group_path/Users/`.
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.
This API is different to the [internal group SCIM API](../development/internal_api/index.md#group-scim-api) and the [instance SCIM API](../development/internal_api/index.md#instance-scim-api):
- This API:
- Does not implement the [RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644).
- Gets, checks, updates, and deletes SCIM identities within groups.
- The internal group and instance SCIM APIs:
- Are for system use for SCIM provider integration.
- Implement the [RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644).
- Get a list of SCIM provisioned users for the group or instance.
- Create, delete and update SCIM provisioned users for the group or instance.
## Get SCIM identities for a group
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5.
```plaintext
GET /groups/:id/scim/identities
```
Supported attributes:
| Attribute | Type | Required | Description |
|:------------------|:--------|:---------|:----------------------|
| `id` | integer/string | Yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) |
If successful, returns [`200`](rest/index.md#status-codes) and the following
response attributes:
| Attribute | Type | Description |
| ------------ | ------- | ------------------------- |
| `extern_uid` | string | External UID for the user |
| `user_id` | integer | ID for the user |
| `active` | boolean | Status of the identity |
Example response:
```json
[
{
"extern_uid": "4",
"user_id": 48,
"active": true
}
]
```
Example request:
```shell
curl --location --request GET "https://gitlab.example.com/api/v4/groups/33/scim/identities" \
--header "PRIVATE-TOKEN: <PRIVATE-TOKEN>"
```
## Get a single SCIM identity
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123591) in GitLab 16.1.
```plaintext
GET /groups/:id/scim/:uid
```
Supported attributes:
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ------------------------- |
| `id` | integer | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) |
| `uid` | string | yes | External UID of the user. |
Example request:
```shell
curl --location --request GET "https://gitlab.example.com/api/v4/groups/33/scim/sydney_jones" --header "PRIVATE-TOKEN: <PRIVATE TOKEN>"
```
Example response:
```json
{
"extern_uid": "4",
"user_id": 48,
"active": true
}
```
## Update `extern_uid` field for a SCIM identity
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5.
Fields that can be updated are:
| SCIM/IdP field | GitLab field |
| --------------- | ------------ |
| `id/externalId` | `extern_uid` |
```plaintext
PATCH /groups/:groups_id/scim/:uid
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ------ | -------- | ------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) |
| `uid` | string | yes | External UID of the user. |
Example request:
```shell
curl --location --request PATCH "https://gitlab.example.com/api/v4/groups/33/scim/sydney_jones" \
--header "PRIVATE-TOKEN: <PRIVATE TOKEN>" \
--form "extern_uid=sydney_jones_new"
```
## Delete a single SCIM identity
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/423592) in GitLab 16.5.
```plaintext
DELETE /groups/:id/scim/:uid
```
Supported attributes:
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | ------------------------- |
| `id` | integer | yes | The ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). |
| `uid` | string | yes | External UID of the user. |
Example request:
```shell
curl --request DELETE --header "Content-Type: application/json" --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/groups/33/scim/sydney_jones"
```
Example response:
```json
{
"message" : "204 No Content"
}
```
|
