SAML API

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

Introduced in GitLab 15.5.

Use this API to interact with SAML features.

GitLab.com endpoints

List all SAML identities for a group

plaintext

GET /groups/:id/saml/identities

Lists all the SAML identities for a group.

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or 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:

shell

curl --location --request GET \
  --header "PRIVATE-TOKEN: <PRIVATE-TOKEN>" \
  --url "https://gitlab.com/api/v4/groups/33/saml/identities"

Example response:

json

[
    {
        "extern_uid": "yrnZW46BrtBFqM7xDzE7dddd",
        "user_id": 48
    }
]

Retrieve a single SAML identity

Introduced in GitLab 16.1.

Retrieves a single SAML identity.

plaintext

GET /groups/:id/saml/:uid

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the group
`uid`	string	yes	External UID of the user.

Example request:

shell

curl --location --request GET \
  --header "PRIVATE-TOKEN: <PRIVATE TOKEN>" \
  --url "https://gitlab.com/api/v4/groups/33/saml/yrnZW46BrtBFqM7xDzE7dddd"

Example response:

json

{
    "extern_uid": "yrnZW46BrtBFqM7xDzE7dddd",
    "user_id": 48
}

Update `extern_uid` field for a SAML identity

Updates extern_uid field for a SAML identity:

SAML IdP attribute	GitLab field
`id/externalId`	`extern_uid`

plaintext

PATCH /groups/:id/saml/:uid

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	yes	The ID or URL-encoded path of the group
`uid`	string	yes	External UID of the user.

Example request:

shell

curl --request PATCH \
  --location \
  --header "PRIVATE-TOKEN: <PRIVATE TOKEN>" \
  --url "https://gitlab.com/api/v4/groups/33/saml/yrnZW46BrtBFqM7xDzE7dddd" \
  --form "extern_uid=be20d8dcc028677c931e04f387"

Delete a single SAML identity

Introduced in GitLab 16.5.

plaintext

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:

shell

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.com/api/v4/groups/33/saml/be20d8dcc028677c931e04f387"

Example response:

json

{
    "message" : "204 No Content"
}

GitLab Self-Managed endpoints

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

List, get, add, and delete SAML group links by using the REST API.

List all SAML group links

Lists all SAML group links for a group.

plaintext

GET /groups/:id/saml_group_links

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or 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	The default access level for members of the SAML group. Possible values: `0` (No access), `5` (Minimal access), `10` (Guest), `15` (Planner), `20` (Reporter), `25` (Security Manager), `30` (Developer), `40` (Maintainer), or `50` (Owner).
`[].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:

shell

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

Example response:

json

[
  {
    "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"
  }
]

Retrieve a SAML group link

Retrieves a SAML group link for a group.

plaintext

GET /groups/:id/saml_group_links/:saml_group_name

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.
`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	The default access level for members of the SAML group. Possible values: `0` (No access), `5` (Minimal access), `10` (Guest), `15` (Planner), `20` (Reporter), `25` (Security Manager), `30` (Developer), `40` (Maintainer), or `50` (Owner).
`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:

shell

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

Example request with provider parameter:

shell

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

Example response:

json

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

Add a SAML group link

Adds a SAML group link for a group.

plaintext

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	The default access level for members of the SAML group. Possible values: `0` (No access), `5` (Minimal access), `10` (Guest), `15` (Planner), `20` (Reporter), `25` (Security Manager), `30` (Developer), `40` (Maintainer), or `50` (Owner).
`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	The default access level for members of the SAML group. Possible values: `0` (No access), `5` (Minimal access), `10` (Guest), `15` (Planner), `20` (Reporter), `25` (Security Manager), `30` (Developer), `40` (Maintainer), or `50` (Owner).
`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:

shell

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:

json

{
"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.

plaintext

DELETE /groups/:id/saml_group_links/:saml_group_name

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.
`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:

shell

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

Example request with provider parameter:

shell

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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.

GitLab.com endpoints

List all SAML identities for a group

Retrieve a single SAML identity

Update extern_uid field for a SAML identity

Delete a single SAML identity

GitLab Self-Managed endpoints

Retrieve a single SAML identity

Update extern_uid field for a SAML identity

Delete a single SAML identity

SAML group links

List all SAML group links

Retrieve 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