- 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.
Get a list of SAML users
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. |
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" }