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

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.
`[].provider`	string	Unique provider name that must match for this group link to be applied.

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,
    "provider": null
  },
  {
    "name": "saml-group-2",
    "access_level": 40,
    "member_role_id": 99,
    "provider": "saml_provider_1"
  }
]

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.
`provider`	string	no	Unique provider name to disambiguate when multiple links exist with the same name. Required when multiple links exist with the same `saml_group_name`.

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.
`provider`	string	Unique provider name that must match for this group link to be applied.

If multiple SAML group links exist with the same name but different providers, and no provider parameter is specified, returns 422 with an error message indicating that the provider parameter is required to disambiguate.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/saml_group_links/saml-group-1"

Example request with provider parameter:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/saml_group_links/saml-group-1?provider=saml_provider_1"

Example response:

{
"name": "saml-group-1",
"access_level": 10,
"member_role_id": 12,
"provider": "saml_provider_1"
}

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.
`provider`	string	no	Unique provider name that must match for this group link to be applied.

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.
`provider`	string	Unique provider name that must match for this group link to be applied.

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>, "provider": "<your_provider>" }' --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,
"provider": "saml_provider_1"
}

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.
`provider`	string	no	Unique provider name to disambiguate when multiple links exist with the same name. Required when multiple links exist with the same `saml_group_name`.

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"

Example request with provider parameter:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/saml_group_links/saml-group-1?provider=saml_provider_1"

If successful, returns 204 status code without any response body.

SAML API

GitLab.com endpoints

Get SAML identities for a group

Get a single SAML identity

Update extern_uid field for a SAML identity

Delete a single SAML identity

GitLab Self-Managed endpoints

Get a single SAML identity

Update extern_uid field for a SAML identity

Delete a single SAML identity

SAML group links

List SAML group links

Get a SAML group link

Add a SAML group link

Delete a SAML group link

Update `extern_uid` field for a SAML identity

Update `extern_uid` field for a SAML identity