Help us learn about your current experience with the documentation. Take the survey.

SAML API

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

使用此 API 与 SAML 功能进行交互。

GitLab.com endpoints

获取组的 SAML 身份

GET /groups/:id/saml/identities

获取组的 SAML 身份。

支持的属性：

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group

如果成功，返回 200 和以下响应属性：

Attribute Type Description
extern_uid string External UID for the user
user_id string ID for the user

示例请求：

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

示例响应：

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

获取单个 SAML 身份

GET /groups/:id/saml/:uid

支持的属性：

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.

示例请求：

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

示例响应：

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

更新 SAML 身份的 extern_uid 字段

更新 SAML 身份的 extern_uid 字段：

SAML IdP attribute GitLab field
id/externalId extern_uid 
PATCH /groups/:id/saml/:uid

支持的属性：

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.

示例请求：

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

删除单个 SAML 身份

DELETE /groups/:id/saml/:uid

支持的属性：

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

示例请求：

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

示例响应：

{
    "message" : "204 No Content"
}

GitLab Self-Managed endpoints

获取单个 SAML 身份

使用 Users API 获取单个 SAML 身份。

更新 SAML 身份的 extern_uid 字段

使用 Users API 更新用户的 extern_uid 字段。

删除单个 SAML 身份

使用 Users API 删除用户的单个身份。

使用 REST API 列出、获取、添加和删除 SAML group links。

列出组的 SAML group links。

GET /groups/:id/saml_group_links

支持的属性：

Attribute Type Required Description
id integer/string yes ID or URL-encoded path of the group.

如果成功，返回 200 和以下响应属性：

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.

示例请求：

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

示例响应：

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

获取组的 SAML group link。

GET /groups/:id/saml_group_links/:saml_group_name

支持的属性：

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.

如果成功，返回 200 和以下响应属性：

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.

如果存在多个同名但不同提供商的 SAML group links，且未指定 provider 参数，则返回 422 并附带错误消息，指示需要 provider 参数来消除歧义。

示例请求：

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

带 provider 参数的示例请求：

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"

示例响应：

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

为组添加 SAML group link。

POST /groups/:id/saml_group_links

支持的属性：

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.

如果成功，返回 201 和以下响应属性：

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.

示例请求：

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"

示例响应：

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

删除组的 SAML group link。

DELETE /groups/:id/saml_group_links/:saml_group_name

支持的属性：

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.

示例请求：

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

带 provider 参数的示例请求：

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"

如果成功，返回 204 状态码，无响应体。

如果存在多个同名但不同提供商的 SAML group links，且未指定 provider 参数，则返回 422 并附带错误消息，指示需要 provider 参数来消除歧义。