Skip to content
Snippets Groups Projects
Verified Commit a90bf903 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis Committed by GitLab
Browse files

Move SAML group links to the SAML API page

parent add2f65e
No related branches found
No related tags found
1 merge request!165103Move SAML group links to the SAML API page
Hide whitespace changes
Inline Side-by-side
doc/api/group_saml_group_links.md deleted 100644 → 0
+ 0
− 167
View file @ add2f65e
---
stage: Govern
group: Authentication
info: 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 group links API
DETAILS:
**Tier:** Premium, Ultimate
**Offering:** GitLab.com, Self-managed, GitLab Dedicated
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3.0.
> - `access_level` type [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95607) from `string` to `integer` in GitLab 15.3.3.
> - `member_role_id` type [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/417201) in GitLab 16.7 [with a flag](../administration/feature_flags.md) named `custom_roles_for_saml_group_links`. Disabled by default.
> - `member_role_id` type [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/417201) in GitLab 16.8. Feature flag `custom_roles_for_saml_group_links` removed.
List, get, add, and delete [SAML group links](../user/group/saml_sso/group_sync.md#configure-saml-group-links) by using
the REST API.
## List SAML group links
List SAML group links for a group.
```plaintext
GET /groups/:id/saml_group_links
```
Supported attributes:
| Attribute | Type | Required | Description |
|:----------|:---------------|:---------|:------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) |
If successful, returns [`200`](rest/index.md#status-codes) and the following response attributes:
| Attribute | Type | Description |
|:--------------------|:--------|:------------|
| `[].name` | string | Name of the SAML group |
| `[].access_level` | integer | [Role (`access_level`)](members.md#roles) 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`)](member_roles.md) for members of the SAML group. |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "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
},
{
"name": "saml-group-2",
"access_level": 40,
"member_role_id": 99
}
]
```
## Get a SAML group link
Get 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/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) |
| `saml_group_name` | string | yes | Name of an SAML group |
If successful, returns [`200`](rest/index.md#status-codes) and the following response attributes:
| Attribute | Type | Description |
|:-----------------|:--------|:------------|
| `name` | string | Name of the SAML group |
| `access_level` | integer | [Role (`access_level`)](members.md#roles) 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`)](member_roles.md) for members of the SAML group. |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/saml_group_links/saml-group-1"
```
Example response:
```json
{
"name": "saml-group-1",
"access_level": 10,
"member_role_id": 12
}
```
## Add a SAML group link
Add 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](rest/index.md#namespaced-path-encoding) |
| `saml_group_name` | string | yes | Name of a SAML group |
| `access_level` | integer | yes | [Role (`access_level`)](members.md#roles) for members of the SAML group |
| `member_role_id` | integer | no | [Member Role ID (`member_role_id`)](member_roles.md) for members of the SAML group. |
If successful, returns [`201`](rest/index.md#status-codes) and the following response attributes:
| Attribute | Type | Description |
|:-----------------|:--------|:------------|
| `name` | string | Name of the SAML group |
| `access_level` | integer | [Role (`access_level`)](members.md#roles) 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`)](member_roles.md) for members of the SAML group. |
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> }' --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
}
```
## 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/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) |
| `saml_group_name` | string | yes | Name of a SAML group |
If successful, returns [`204`](rest/index.md#status-codes) status code without any response body.
Example request:
```shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/saml_group_links/saml-group-1"
```
doc/api/saml.md
+ 158
− 0
View file @ a90bf903
......@@ -155,3 +155,161 @@ Use the Users API to [update the `extern_uid` field of a user](../api/users.md#u
### Delete a single SAML identity
Use the Users API to [delete a single identity of a user](../api/users.md#delete-authentication-identity-from-user).
## SAML group links
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3.0.
> - `access_level` type [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95607) from `string` to `integer` in GitLab 15.3.3.
> - `member_role_id` type [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/417201) in GitLab 16.7 [with a flag](../administration/feature_flags.md) named `custom_roles_for_saml_group_links`. Disabled by default.
> - `member_role_id` type [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/417201) in GitLab 16.8. Feature flag `custom_roles_for_saml_group_links` removed.
List, get, add, and delete [SAML group links](../user/group/saml_sso/group_sync.md#configure-saml-group-links) by using
the REST API.
### List SAML group links
List SAML group links for a group.
```plaintext
GET /groups/:id/saml_group_links
```
Supported attributes:
| Attribute | Type | Required | Description |
|:----------|:---------------|:---------|:------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). |
If successful, returns [`200`](rest/index.md#status-codes) and the following response attributes:
| Attribute | Type | Description |
|:--------------------|:--------|:------------|
| `[].name` | string | Name of the SAML group. |
| `[].access_level` | integer | [Role (`access_level`)](members.md#roles) 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`)](member_roles.md) for members of the SAML group. |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "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
},
{
"name": "saml-group-2",
"access_level": 40,
"member_role_id": 99
}
]
```
### Get a SAML group link
Get 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/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). |
| `saml_group_name` | string | yes | Name of the SAML group. |
If successful, returns [`200`](rest/index.md#status-codes) and the following response attributes:
| Attribute | Type | Description |
|:-----------------|:--------|:------------|
| `name` | string | Name of the SAML group. |
| `access_level` | integer | [Role (`access_level`)](members.md#roles) 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`)](member_roles.md) for members of the SAML group. |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/saml_group_links/saml-group-1"
```
Example response:
```json
{
"name": "saml-group-1",
"access_level": 10,
"member_role_id": 12
}
```
### Add a SAML group link
Add 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](rest/index.md#namespaced-path-encoding). |
| `saml_group_name` | string | yes | Name of the SAML group. |
| `access_level` | integer | yes | [Role (`access_level`)](members.md#roles) for members of the SAML group. |
| `member_role_id` | integer | no | [Member Role ID (`member_role_id`)](member_roles.md) for members of the SAML group. |
If successful, returns [`201`](rest/index.md#status-codes) and the following response attributes:
| Attribute | Type | Description |
|:-----------------|:--------|:------------|
| `name` | string | Name of the SAML group. |
| `access_level` | integer | [Role (`access_level`)](members.md#roles) 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`)](member_roles.md) for members of the SAML group. |
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> }' --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
}
```
### 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/string | yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). |
| `saml_group_name` | string | yes | Name of the SAML group. |
Example request:
```shell
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`](rest/index.md#status-codes) status code without any response body.
doc/update/versions/gitlab_15_changes.md
+ 2
− 2
View file @ a90bf903
......@@ -709,8 +709,8 @@ A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706)
## 15.3.3
- In GitLab 15.3.3, the [SAML group links](../../api/group_saml_group_links.md) API `access_level` attribute type changed to
`integer`. See [the API documentation](../../api/members.md).
- In GitLab 15.3.3, [SAML Group Links](../../api/saml.md#saml-group-links) API `access_level` attribute type changed to `integer`. See
[the API documentation](../../api/members.md).
- A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) prevents some premium features of GitLab from working correctly if you add a new license. Workarounds for this issue:
- Restart all Rails, Sidekiq and Gitaly nodes after applying a new license. This clears the relevant license caches and allows all premium features to operate correctly.
......
doc/user/group/saml_sso/group_sync.md
+ 1
− 1
View file @ a90bf903
......@@ -106,7 +106,7 @@ Users granted:
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290367) in GitLab 15.3.
You can use the GitLab API to [list, add, and delete](../../../api/group_saml_group_links.md) SAML group links.
You can use the GitLab API to [list, add, and delete](../../../api/saml.md#saml-group-links) SAML group links.
## Configure SAML Group Sync
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment