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

SCIM API (SILVER ONLY)

Introduced in GitLab Silver 11.10.

The SCIM API implements the the RFC7644 protocol.

CAUTION: Caution: This API is for internal system use for connecting with a SCIM provider. While it can be used directly, it is subject to change without notice.

NOTE: Note: Group SSO must be enabled for the group. For more information, see SCIM setup documentation.

Get a list of SAML users

NOTE: Note: This endpoint is used as part of the SCIM syncing mechanism and 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: 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://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"

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

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

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

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

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