debian-mirror-gitlab/doc/api/scim.md

88 lines
2.7 KiB
Markdown
Raw Normal View History

2021-01-29 00:20:46 +05:30
---
type: reference, howto
stage: Manage
2022-04-04 11:22:00 +05:30
group: Authentication and Authorization
2022-11-25 23:54:43 +05:30
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
2021-01-29 00:20:46 +05:30
---
2022-11-25 23:54:43 +05:30
# SCIM API **(PREMIUM SAAS)**
2019-09-04 21:01:54 +05:30
2022-11-25 23:54:43 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/98354) in GitLab 15.5.
2020-05-24 23:13:21 +05:30
2023-04-23 21:23:45 +05:30
GitLab provides an SCIM API that both implements [the RFC7644 protocol](https://www.rfc-editor.org/rfc/rfc7644)
2023-03-04 22:38:38 +05:30
and provides the `/Users` endpoint. The base URL is `/api/scim/v2/groups/:group_path/Users/`.
2021-01-29 00:20:46 +05:30
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-09-04 21:01:54 +05:30
2023-03-17 16:20:25 +05:30
Not to be confused with the [internal group SCIM API](../development/internal_api/index.md#group-scim-api).
2019-09-04 21:01:54 +05:30
2022-11-25 23:54:43 +05:30
## Get SCIM identities for a group
2019-09-04 21:01:54 +05:30
2022-11-25 23:54:43 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5.
2019-09-04 21:01:54 +05:30
2020-05-24 23:13:21 +05:30
```plaintext
2022-11-25 23:54:43 +05:30
GET /groups/:id/scim/identities
2019-09-04 21:01:54 +05:30
```
2022-11-25 23:54:43 +05:30
Supported attributes:
2019-09-04 21:01:54 +05:30
2022-11-25 23:54:43 +05:30
| Attribute | Type | Required | Description |
|:------------------|:--------|:---------|:----------------------|
2023-01-13 00:05:48 +05:30
| `id` | integer | Yes | Return SCIM identities for the given group ID. |
2019-09-04 21:01:54 +05:30
2023-04-23 21:23:45 +05:30
If successful, returns [`200`](rest/index.md#status-codes) and the following
2022-11-25 23:54:43 +05:30
response attributes:
2019-09-04 21:01:54 +05:30
2023-04-23 21:23:45 +05:30
| Attribute | Type | Description |
| ------------ | ------- | ------------------------- |
| `extern_uid` | string | External UID for the user |
| `user_id` | integer | ID for the user |
| `active` | boolean | Status of the identity |
2019-09-04 21:01:54 +05:30
Example response:
```json
2022-11-25 23:54:43 +05:30
[
2019-09-04 21:01:54 +05:30
{
2022-11-25 23:54:43 +05:30
"extern_uid": "4",
2023-04-23 21:23:45 +05:30
"user_id": 48,
"active": true
2019-09-04 21:01:54 +05:30
}
2022-11-25 23:54:43 +05:30
]
2019-09-04 21:01:54 +05:30
```
Example request:
2020-03-13 15:44:24 +05:30
```shell
2023-01-13 00:05:48 +05:30
curl --location --request GET "https://gitlab.example.com/api/v4/groups/33/scim/identities" \
2023-03-04 22:38:38 +05:30
--header "PRIVATE-TOKEN: <PRIVATE-TOKEN>"
2019-09-04 21:01:54 +05:30
```
2023-03-04 22:38:38 +05:30
## Update `extern_uid` field for a SCIM identity
2019-09-04 21:01:54 +05:30
2022-11-25 23:54:43 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227841) in GitLab 15.5.
2019-09-04 21:01:54 +05:30
Fields that can be updated are:
2022-11-25 23:54:43 +05:30
| SCIM/IdP field | GitLab field |
| --------------- | ------------ |
| `id/externalId` | `extern_uid` |
2019-09-04 21:01:54 +05:30
2020-05-24 23:13:21 +05:30
```plaintext
2023-04-23 21:23:45 +05:30
PATCH /groups/:groups_id/scim/:uid
2019-09-04 21:01:54 +05:30
```
Parameters:
2022-11-25 23:54:43 +05:30
| Attribute | Type | Required | Description |
| --------- | ------ | -------- | ------------------------- |
| `uid` | string | yes | External UID of the user. |
2019-09-04 21:01:54 +05:30
Example request:
2020-03-13 15:44:24 +05:30
```shell
2023-01-13 00:05:48 +05:30
curl --location --request PATCH "https://gitlab.example.com/api/v4/groups/33/scim/sydney_jones" \
--header "PRIVATE-TOKEN: <PRIVATE TOKEN>" \
2023-03-04 22:38:38 +05:30
--form "extern_uid=sydney_jones_new"
2019-09-04 21:01:54 +05:30
```