opensource/grafana
1
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-08-01 18:13:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Update RBAC documentation (#75869)

Browse Source 
* Align docs to current permissions in code

* Update permissions list

* Add example responses, fix link

* Apply suggestions from code review

Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>

* Update based on reviews

---------

Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>
This commit is contained in:
Misi
2023-10-04 17:53:26 +02:00
committed by GitHub
parent 69b2442a0d
commit e1aad9c9bf
3 changed files with 120 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

104
docs/sources/developers/http_api/access_control.md
View File

@ -311,14 +311,84 @@ Content-Type: application/json; charset=UTF-8
| name | string | Yes | Name of the role. |
| description | string | No | Description of the role. |
| displayName | string | No | Display name of the role, visible in the UI. |
| group | string | No | The group name the role belongs to. |
| hidden | boolean | No | Specify whether the role is hidden or not. If set to `true`, then the role does not show in the role picker. It will not be listed by API endpoints unless explicitly specified. |
| permissions | List of Permissions | No | The full list of permissions for the role after the update. |
**Permission**
| Field Name | Data Type | Required | Description |
| ---------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| action | string | Yes | Refer to [Custom role actions and scopes]({{< relref "/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes" >}}) for full list of available actions. |
| scope | string | No | If not present, no scope will be mapped to the permission. Refer to [Custom role actions and scopes]({{< relref "/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes" >}}) for full list of available scopes. |
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
```
#### Update role validation errors
Permission validation only occurs when permission validation is enabled (`rbac.permission_validation_enabled = true`).
> It has been enabled by default since Grafana 10.2.
For more information, refer to [Create role validation errors]({{< ref "#create-role-validation-errors" >}}).
#### Status codes
| Code | Description |
| ---- | ------------------------------------------------------------------------------------- |
| 200 | Role is updated. |
| 400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.). |
| 403 | Access denied (one of the specified permissions is not assigned to the the requester) |
| 404 | Role was not found to update. |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
### Delete a custom role
`DELETE /api/access-control/roles/:uid?force=false`
Delete a role with the given UID, and it's permissions. If the role is assigned, the deletion operation will fail, unless the `force` query param is set to `true`, and in that case all assignments will also be deleted.
#### Required permissions
`permissions:type:delegate` scope ensures that users can only delete a custom role with the 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 delete a custom role which allows to do that.
| Action | Scope |
| ------------ | ------------------------- |
| roles:delete | permissions:type:delegate |
#### Example request
```http
DELETE /api/access-control/roles/jZrmlLCGka?force=true&global=false
Accept: application/json
```
#### Query parameters
| Param | Type | Required | Description |
| ------ | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| force | boolean | No | When set to `true`, the role will be deleted with all it's assignments. |
| global | boolean | No | A flag indicating if the role is global or not. If set to false, the default org ID of the authenticated user will be used from the request. Refer to the [About RBAC]({{< relref "/docs/grafana/latest/administration/roles-and-permissions/access-control" >}}) for more information. |
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
| Action | Scope |
| ------------ | ------------------------- |
| roles:delete | permissions:type:delegate |
#### Example request
```
#### Status codes
| Code | Description |
| ---- | ---------------------------------------------------------------------------------- |
| 200 | Role is deleted. |
| 400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.). |
| 403 | Access denied |
@ -418,15 +488,23 @@ Content-Type: application/json; charset=UTF-8
#### Example request
```http
GET /api/access-control/users/1/permissions
Accept: application/json
```
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
#### Status codes
| Code | Description |
| ---- | -------------------------------------------------------------------- |
| 200 | Set of assigned permissions is returned. |
| 403 | Access denied. |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
```
#### Status codes
| Code | Description |
| ---- | -------------------------------------------------------------------- |
| 200 | Set of assigned permissions is returned. |
| 403 | Access denied. |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |