- Get a list of SAML users
- Get a single SAML user
- Create a SAML user
- Update a single SAML user
- Remove a single SAML user
- Available filters
- Available operations
SCIM API
Introduced in GitLab Silver 11.10.
The SCIM API implements the the RFC7644 protocol.
Note:
Group SSO must be enabled for the group. For more information, see SCIM setup documentation.
Get a list of SAML users
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:
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 | |
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" }
Help and feedback
If there's something you don't like about this feature
To propose functionality that GitLab does not yet offer
To further help GitLab in shaping new features
If you didn't find what you were looking for
If you want help with something very specific to your use case, and can use some community support
POST ON GITLAB FORUM
If you have problems setting up or using this feature (depending on your GitLab subscription)
REQUEST SUPPORT
To view all GitLab tiers and features or to upgrade
If you want to try all features available in GitLab.com
If you want to try all features available in GitLab self-managed
If you spot an error or a need for improvement and would like to fix it yourself in a merge request
EDIT THIS PAGE
If you would like to suggest an improvement to this doc