opensource/grafana
1
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-07-31 12:12:35 +08:00
Code Issues Packages Projects Releases Wiki Activity

Documentation for granting and revoking access for teams. (#44863)

Browse Source
This commit is contained in:
Vardan Torosyan
2022-02-04 13:17:25 +01:00
committed by GitHub
parent 6bb6b13379
commit b38d3f339a
6 changed files with 261 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

212
docs/sources/http_api/access_control.md
View File

@ -726,6 +726,218 @@ Content-Type: application/json; charset=UTF-8
PUT /api/access-control/teams/1/roles
Accept: application/json
Content-Type: application/json
{
"roleUids": [
"ZiHQJq5nk",
"GzNQ1357k"
]
}
```
#### JSON body schema
| Field Name | Date Type | Required | Description |
| ---------- | --------- | -------- | ------------------ |
| roleUids | list | Yes | List of role UIDs. |
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Team roles have been updated."
}
```
#### Status codes
| Code | Description |
| ---- | -------------------------------------------------------------------- |
| 200 | Roles have been assigned. |
| 403 | Access denied. |
| 404 | Role not found. |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
## Create and remove built-in role assignments
API set allows to create or remove [built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) and list current assignments.
### Get all built-in role assignments
`GET /api/access-control/builtin-roles`
Gets all built-in role assignments.
#### Required permissions
| Action | Scope |
| ------------------ | -------- |
| roles.builtin:list | roles:\* |
#### Example request
```http
GET /api/access-control/builtin-roles
Accept: application/json
Content-Type: application/json
```
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"Admin": [
{
"version": 1,
"uid": "qQui_LCMk",
"name": "fixed:users:writer",
"name": "User writer",
"description": "Read and update all attributes and settings for all users in Grafana: update user information, read user information, create or enable or disable a user, make a user a Grafana administrator, sign out a user, update a user’s authentication token, or update quotas for all users",
"global": true,
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
},
{
"version": 1,
"uid": "PeXmlYjMk",
"name": "fixed:users:reader",
"displayName": "User reader",
"description": "Allows every read action for user organizations and in addition allows to administer user organizations",
"global": true,
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
}
],
"Grafana Admin": [
{
"version": 1,
"uid": "qQui_LCMk",
"name": "fixed:users:writer",
"displayName": "User writer",
"description": "Read and update all attributes and settings for all users in Grafana: update user information, read user information, create or enable or disable a user, make a user a Grafana administrator, sign out a user, update a user’s authentication token, or update quotas for all users",
"global": true,
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
}
]
}
```
#### Status codes
| Code | Description |
| ---- | -------------------------------------------------------------------- |
| 200 | Built-in role assignments are returned. |
| 403 | Access denied |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
### Create a built-in role assignment
`POST /api/access-control/builtin-roles`
Creates a new built-in role assignment.
#### Required permissions
`permission:delegate` scope ensures that users can only create built-in role assignments with the roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won't be able to create a built-in role assignment which will allow to do that. This is done to prevent escalation of privileges.
| Action | Scope |
| ----------------- | -------------------- |
| roles.builtin:add | permissions:delegate |
#### Example request
```http
POST /api/access-control/builtin-roles
Accept: application/json
Content-Type: application/json
{
"roleUid": "LPMGN99Mk",
"builtinRole": "Grafana Admin",
"global": false
}
```
#### JSON body schema
| Field Name | Date Type | Required | Description |
| ----------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| roleUid | string | Yes | UID of the role. |
| builtinRole | boolean | Yes | Can be one of `Viewer`, `Editor`, `Admin` or `Grafana Admin`. |
| global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to create organization local assignment. Refer to the [Built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information. |
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Built-in role grant added"
}
```
#### Status codes
| Code | Description |
| ---- | ---------------------------------------------------------------------------------- |
| 200 | Role was assigned to built-in role. |
| 400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.). |
| 403 | Access denied |
| 404 | Role not found |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
### Remove a built-in role assignment
`DELETE /api/access-control/builtin-roles/:builtinRole/roles/:roleUID`
Deletes a built-in role assignment (for one of _Viewer_, _Editor_, _Admin_, or _Grafana Admin_) to the role with the provided UID.
#### Required permissions
`permission:delegate` scope ensures that users can only remove built-in role assignments with the roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won't be able to remove a built-in role assignment which allows to do that.
| Action | Scope |
| -------------------- | -------------------- |
| roles.builtin:remove | permissions:delegate |
#### Example request
```http
DELETE /api/access-control/builtin-roles/Grafana%20Admin/roles/LPMGN99Mk?global=false
Accept: application/json
```
#### Query parameters
| Param | Type | Required | Description |
| ------ | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to remove assignment. Refer to the [Built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information. |
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Built-in role grant removed"
}
```
#### Status codes
| Code | Description |
| ---- | ---------------------------------------------------------------------------------- |
| 200 | Role was unassigned from built-in role. |
| 400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.). |
| 403 | Access denied |