gitlab-foss/doc/api/saml.md

stage, group, info, title

stage	group	info	title
Software Supply Chain Security	Authentication	To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments	SAML API

{{< details >}}

• Tier: Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

• Introduced in GitLab 15.5.

{{< /history >}}

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

{{< history >}}

• Introduced in GitLab 16.1.

{{< /history >}}

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

{{< history >}}

• Introduced in GitLab 16.5.

{{< /history >}}

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

{{< history >}}

• 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.
• provider parameter Introduced in GitLab 18.2.

{{< /history >}}

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.

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.