SAML API
- Tier: Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Use this API to interact with SAML features.
GitLab.com endpoints
Get SAML identities for a group
GET /groups/:id/saml/identities
Fetch SAML identities for a group.
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the group |
If successful, returns 200
and the following
response attributes:
Attribute | Type | Description |
---|---|---|
extern_uid |
string | External UID for the user |
user_id |
string | ID for the user |
Example request:
curl --location --request GET "https://gitlab.com/api/v4/groups/33/saml/identities" --header "PRIVATE-TOKEN: <PRIVATE-TOKEN>"
Example response:
[
{
"extern_uid": "yrnZW46BrtBFqM7xDzE7dddd",
"user_id": 48
}
]
Get a single SAML identity
GET /groups/:id/saml/:uid
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the group |
uid |
string | yes | External UID of the user. |
Example request:
curl --location --request GET "https://gitlab.com/api/v4/groups/33/saml/yrnZW46BrtBFqM7xDzE7dddd" --header "PRIVATE-TOKEN: <PRIVATE TOKEN>"
Example response:
{
"extern_uid": "yrnZW46BrtBFqM7xDzE7dddd",
"user_id": 48
}
Update extern_uid
field for a SAML identity
Update extern_uid
field for a SAML identity:
SAML IdP attribute | GitLab field |
---|---|
id/externalId |
extern_uid |
PATCH /groups/:id/saml/:uid
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the group |
uid |
string | yes | External UID of the user. |
Example request:
curl --location --request PATCH "https://gitlab.com/api/v4/groups/33/saml/yrnZW46BrtBFqM7xDzE7dddd" \
--header "PRIVATE-TOKEN: <PRIVATE TOKEN>" \
--form "extern_uid=be20d8dcc028677c931e04f387"
Delete a single SAML identity
DELETE /groups/:id/saml/:uid
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer | yes | The ID or URL-encoded path of the group. |
uid |
string | yes | External UID of the user. |
Example request:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.com/api/v4/groups/33/saml/be20d8dcc028677c931e04f387"
Example response:
{
"message" : "204 No Content"
}
GitLab Self-Managed endpoints
Get a single SAML identity
Use the Users API to get a single SAML identity.
Update extern_uid
field for a SAML identity
Use the Users API to update the extern_uid
field of a user.
Delete a single SAML identity
Use the Users API to delete a single identity of a user.
SAML group links
List, get, add, and delete SAML group links by using the REST API.
List SAML group links
List SAML group links for a group.
GET /groups/:id/saml_group_links
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | ID or URL-encoded path of the group. |
If successful, returns 200
and the following response attributes:
Attribute | Type | Description |
---|---|---|
[].name |
string | Name of the SAML group. |
[].access_level |
integer | Role (access_level ) for members of the SAML group. The attribute had a string type from GitLab 15.3.0 to GitLab 15.3.3. |
[].member_role_id |
integer | Member Role ID (member_role_id ) for members of the SAML group. |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/saml_group_links"
Example response:
[
{
"name": "saml-group-1",
"access_level": 10,
"member_role_id": 12
},
{
"name": "saml-group-2",
"access_level": 40,
"member_role_id": 99
}
]
Get a SAML group link
Get a SAML group link for a group.
GET /groups/:id/saml_group_links/:saml_group_name
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | ID or URL-encoded path of the group. |
saml_group_name |
string | yes | Name of the SAML group. |
If successful, returns 200
and the following response attributes:
Attribute | Type | Description |
---|---|---|
name |
string | Name of the SAML group. |
access_level |
integer | Role (access_level ) for members of the SAML group. The attribute had a string type from GitLab 15.3.0 to GitLab 15.3.3. |
member_role_id |
integer | Member Role ID (member_role_id ) for members of the SAML group. |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/saml_group_links/saml-group-1"
Example response:
{
"name": "saml-group-1",
"access_level": 10,
"member_role_id": 12
}
Add a SAML group link
Add a SAML group link for a group.
POST /groups/:id/saml_group_links
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer or string | yes | ID or URL-encoded path of the group. |
saml_group_name |
string | yes | Name of the SAML group. |
access_level |
integer | yes | Role (access_level ) for members of the SAML group. |
member_role_id |
integer | no | Member Role ID (member_role_id ) for members of the SAML group. |
If successful, returns 201
and the following response attributes:
Attribute | Type | Description |
---|---|---|
name |
string | Name of the SAML group. |
access_level |
integer | Role (access_level ) for members of the for members of the SAML group. The attribute had a string type from GitLab 15.3.0 to GitLab 15.3.3. |
member_role_id |
integer | Member Role ID (member_role_id ) for members of the SAML group. |
Example request:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{ "saml_group_name": "<your_saml_group_name`>", "access_level": <chosen_access_level>, "member_role_id": <chosen_member_role_id> }' --url "https://gitlab.example.com/api/v4/groups/1/saml_group_links"
Example response:
{
"name": "saml-group-1",
"access_level": 10,
"member_role_id": 12
}
Delete a SAML group link
Delete a SAML group link for a group.
DELETE /groups/:id/saml_group_links/:saml_group_name
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | ID or URL-encoded path of the group. |
saml_group_name |
string | yes | Name of the SAML group. |
Example request:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/saml_group_links/saml-group-1"
If successful, returns 204
status code without any response body.
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support