AccessControl: Document basic roles changes and provisioning V2 (#48910)
* AccessControl: Document basic roles simplifying * Add sample file for provisioning v2 * WIP * Update provisioning example from docs * Fix wrong permission in docs * Nits on about-rbas.md * Manage rbac roles * Nit. * Nit. * Rephrase * Comment * Add version to the role * Update role * Update role * Spell * Final touch on about-rbac * Add basic role UID mapping about-rbac * Team assignments * assign rbac roles * move for more info * enable rbac and provisioning * spell * plan rbac rollout strategy * Cover factory reset * remove builtin assignment permissions from docs * to -> from * Custom role actions scopes * spell * Update docs/sources/enterprise/access-control/about-rbac.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/about-rbac.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/assign-rbac-roles.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/assign-rbac-roles.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/assign-rbac-roles.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/plan-rbac-rollout-strategy.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/plan-rbac-rollout-strategy.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/manage-rbac-roles.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/custom-role-actions-scopes.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/custom-role-actions-scopes.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/enable-rbac-and-provisioning.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/manage-rbac-roles.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/manage-rbac-roles.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/manage-rbac-roles.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/manage-rbac-roles.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/manage-rbac-roles.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/manage-rbac-roles.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/manage-rbac-roles.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/manage-rbac-roles.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/manage-rbac-roles.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/manage-rbac-roles.md * Update docs/sources/enterprise/access-control/manage-rbac-roles.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Remove factory as much as possible * Update docs/sources/enterprise/access-control/plan-rbac-rollout-strategy.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/plan-rbac-rollout-strategy.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Have -> Must Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Have -> Must Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Replace factory by hard reset * Replace LINK * Update docs/sources/enterprise/access-control/about-rbac.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Suggestion on example descriptions Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/enterprise/access-control/manage-rbac-roles.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Remove comment on permissions escalate * Prettier. * add a sentence to explain the type:escalate * add a sentence to explain the type:escalate * Rephrase * Remove TODOs as discussed with jguer Co-authored-by: Jguer <joao.guerreiro@grafana.com> * Implement vardan's suggestion to have only one mapping: Co-authored-by: Vardan Torosyan <vardants@gmail.com> * Document that you cannot delete basic roles Co-authored-by: Vardan Torosyan <vardants@gmail.com> Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> Co-authored-by: Jguer <joao.guerreiro@grafana.com> Co-authored-by: Vardan Torosyan <vardants@gmail.com>
This commit is contained in:
Gabriel MABILLE
co-authored by
Christopher Moyer
Jguer
Vardan Torosyan
Christopher Moyer
Jguer
Vardan Torosyan
parent
e3c1faad56
commit
83e234d4f6
@@ -9,7 +9,7 @@ aliases = ["/docs/grafana/latest/http_api/accesscontrol/"]
|
||||
|
||||
> Role-based access control API is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../enterprise" >}}).
|
||||
|
||||
The API can be used to create, update, get and list roles, and create or remove built-in role assignments.
|
||||
The API can be used to create, update, get and list roles, and create or remove assignments.
|
||||
To use the API, you would need to [enable role-based access control]({{< relref "../enterprise/access-control/_index.md#enable-role-based-access-control" >}}).
|
||||
|
||||
The API does not currently work with an API Token. So in order to use these API endpoints you will have to use [Basic auth]({{< relref "./auth/#basic-auth" >}}).
|
||||
@@ -62,8 +62,6 @@ Content-Type: application/json; charset=UTF-8
|
||||
|
||||
Gets all existing roles. The response contains all global and organization local roles, for the organization which user is signed in.
|
||||
|
||||
Refer to the [Basic roles]({{< relref "../enterprise/access-control/about-rbac#basic-roles" >}}) for more information.
|
||||
|
||||
Query Parameters:
|
||||
|
||||
- `includeHidden`: Optional. Set to `true` to include roles that are `hidden`.
|
||||
@@ -309,11 +307,13 @@ Content-Type: application/json; charset=UTF-8
|
||||
| 403 | Access denied |
|
||||
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
|
||||
|
||||
### Update a custom role
|
||||
### Update a role
|
||||
|
||||
`PUT /api/access-control/roles/:uid`
|
||||
|
||||
Update the role with the given UID, and it's permissions with the given UID. The operation is idempotent and all permissions of the role will be replaced with what is in the request. You would need to increment the version of the role with each update, otherwise the request will fail.
|
||||
Update the role with the given UID, and its permissions. The operation is idempotent and all permissions of the role will be replaced based on the request content. You need to increment the version of the role with each update, otherwise the request will fail.
|
||||
|
||||
You can update `custom` roles and `basic` roles permissions. However `fixed` roles cannot be updated.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
@@ -419,7 +419,7 @@ Content-Type: application/json; charset=UTF-8
|
||||
|
||||
`DELETE /api/access-control/roles/:uid?force=false`
|
||||
|
||||
Delete a role with the given UID, and it's permissions. If the role is assigned to a built-in role, the deletion operation will fail, unless `force` query param is set to `true`, and in that case all assignments will also be deleted.
|
||||
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
|
||||
|
||||
@@ -470,7 +470,7 @@ Content-Type: application/json; charset=UTF-8
|
||||
|
||||
`GET /api/access-control/users/:userId/roles`
|
||||
|
||||
Lists the roles that have been directly assigned to a given user. The list does not include built-in roles (Viewer, Editor, Admin or Grafana Admin), and it does not include roles that have been inherited from a team.
|
||||
Lists the roles that have been directly assigned to a given user. The list does not include basic roles (Viewer, Editor, Admin or Grafana Admin), and it does not include roles that have been inherited from a team.
|
||||
|
||||
Query Parameters:
|
||||
|
||||
@@ -955,124 +955,38 @@ Content-Type: application/json; charset=UTF-8
|
||||
| 404 | Role not found. |
|
||||
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
|
||||
|
||||
## Create and remove built-in (basic) role assignments
|
||||
## Reset basic roles to their default
|
||||
|
||||
API set allows to create or remove [basic role assignments]({{< relref "../enterprise/access-control/assign-rbac-roles" >}}) and list current assignments.
|
||||
`POST /api/access-control/roles/hard-reset`
|
||||
|
||||
> **Note:** Basic roles are referred to as **"built-in"** roles in the API. "Basic" and "built-in" refer to the same thing: the Grafana Administrator, Org Administrator, Editor, and Viewer roles.
|
||||
`permissions:type:escalate` scope enables users to reset basic roles permissions.
|
||||
This could result in basic roles having permissions exceedind those of callers.
|
||||
|
||||
### Get all built-in role assignments
|
||||
|
||||
`GET /api/access-control/builtin-roles`
|
||||
|
||||
Gets all built-in role assignments.
|
||||
|
||||
Query Parameters:
|
||||
|
||||
- `includeHidden`: Optional. Set to `true` to include roles that are `hidden`.
|
||||
Reset basic roles permissions to their default.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------ | -------- |
|
||||
| roles.builtin:list | roles:\* |
|
||||
| Action | Scope |
|
||||
| ----------- | ------------------------- |
|
||||
| roles:write | permissions:type:escalate |
|
||||
|
||||
#### 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
|
||||
|
||||
`permissions:type: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:type:delegate |
|
||||
|
||||
#### Example request
|
||||
|
||||
```http
|
||||
POST /api/access-control/builtin-roles
|
||||
POST /api/access-control/roles/hard-reset
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"roleUid": "LPMGN99Mk",
|
||||
"builtinRole": "Grafana Admin",
|
||||
"global": false
|
||||
"BasicRoles": true
|
||||
}
|
||||
```
|
||||
|
||||
#### 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. |
|
||||
| Field Name | Data Type | Required | Description |
|
||||
| ---------- | --------- | -------- | ---------------------------------------- |
|
||||
| BasicRoles | boolean | No | Option to reset basic roles permissions. |
|
||||
|
||||
#### Example response
|
||||
|
||||
@@ -1081,65 +995,13 @@ HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
|
||||
{
|
||||
"message": "Built-in role grant added"
|
||||
"message": "Reset performed"
|
||||
}
|
||||
```
|
||||
|
||||
#### 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
|
||||
|
||||
`permissions:type: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:type: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. |
|
||||
|
||||
#### 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 |
|
||||
| 404 | Role not found. |
|
||||
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
|
||||
| Code | Description |
|
||||
| ---- | --------------------------- |
|
||||
| 200 | Reset performed |
|
||||
| 500 | Failed to reset basic roles |
|
||||
|
||||
Reference in New Issue
Block a user