gitlab-org--gitlab-foss/doc/api/scim.md

type	stage	group	info
reference, howto	Manage	Access	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

SCIM API (SYSTEM ONLY) (SILVER ONLY)

Introduced in GitLab.com Silver 11.10.

The SCIM API implements the RFC7644 protocol. As this API is for system use for SCIM provider integration, it is subject to change without notice.

To use this API, Group SSO must be enabled for the group. This API is only in use where SCIM for Group SSO is enabled. It's a prerequisite to the creation of SCIM identities.

Get a list of SAML users

This endpoint is used as part of the SCIM syncing mechanism. It only returns a single user based on a unique ID which should match the extern_uid of the user.

GET /api/scim/v2/groups/:group_path/Users

Parameters:

Attribute	Type	Required	Description
filter	string	no	A filter expression.
group_path	string	yes	Full path to the group.
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.

NOTE: Pagination follows the SCIM spec 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.

Example request:

curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

Example response:

{
  "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 /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:

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"

Example response:

{
  "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

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.
meta	string	no	Resource type (User).

Example request:

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"

Example response:

{
  "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:

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

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 expression.

Example request:

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"

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.

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:

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"

Returns an empty response with a 204 status code if successful.

Available filters

They match an expression as specified in the RFC7644 filtering section.

Filter	Description
eq	The attribute matches exactly the specified value.

Example:

id eq a-b-c-d

Available operations

They perform an operation as specified in the RFC7644 update section.

Operator	Description
Replace	The attribute's value is updated.
Add	The attribute has a new value.

Example:

{ "op": "Add", "path": "name.formatted", "value": "New Name" }