Skip to content

SAML API

DETAILS: Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

API for accessing 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"
}

Self-managed GitLab 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

  • Introduced in GitLab 15.3.0.
  • access_level type changed from string to integer in GitLab 15.3.3.
  • member_role_id type Introduced in GitLab 16.7 with a flag named custom_roles_for_saml_group_links. Disabled by default.
  • member_role_id type Generally available in GitLab 16.8. Feature flag custom_roles_for_saml_group_links removed.

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.