public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[Docs] Document FGAC user role assignment (#41797) (#42263)

Browse Source 
(cherry picked from commit 5043448769)

Co-authored-by: Mitch Seaman <mjseaman@users.noreply.github.com>
This commit is contained in:
Grot (@grafanabot)
2021-11-24 17:06:28 -05:00
committed by GitHub
parent 5412a903b1
commit 3e437fb3be
10 changed files with 479 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/sources/enterprise/access-control/_index.md
View File

@@ -21,7 +21,7 @@ Fine-grained access control considers a) _who_ has an access (`identity`), and b
You can grant, change, or revoke access to _users_ (`identity`). When an authenticated user tries to access a Grafana resource, the authorization system checks the required fine-grained permissions for the resource and determines whether or not the action is allowed. Refer to [Fine-grained permissions]({{< relref "./permissions.md" >}}) for a complete list of available permissions.
To grant or revoke access to your users, create or remove built-in role assignments. For more information, refer to [Built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}).
Refer to [Assign roles]({{< relref "./roles.md#assign-roles" >}}) to learn about grant or revoke access to your users.
## Resources with fine-grained permissions

4
docs/sources/enterprise/access-control/fine-grained-access-control-references.md
View File

@@ -13,8 +13,8 @@ The reference information that follows complements conceptual information about
| Fixed roles | Permissions | Descriptions |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fixed:roles:reader` | `roles:read`<br>`roles:list`<br>`roles.builtin:list` | Read all access control roles and built-in role assignments. |
| `fixed:roles:writer` | All permissions from `fixed:roles:reader` and <br>`roles:write`<br>`roles:delete`<br>`roles.builtin:add`<br>`roles.builtin:remove` | Create, read, update, or delete all roles and built-in role assignments. |
| `fixed:roles:reader` | `roles:read`<br>`roles:list`<br>`users.roles:list`<br>`users.permissions:list`<br>`roles.builtin:list` | Read all access control roles, roles and permissions assigned to users and built-in role assignments. |
| `fixed:roles:writer` | All permissions from `fixed:roles:reader` and <br>`roles:write`<br>`roles:delete`<br>`users.roles:add`<br>`users.roles:remove`<br>`roles.builtin:add`<br>`roles.builtin:remove` | Create, read, update, or delete all roles, assign or unassign roles to users and built-in role assignments. |
| `fixed:reports:reader` | `reports:read`<br>`reports:send`<br>`reports.settings:read` | Read all reports and shared report settings. |
| `fixed:reports:writer` | All permissions from `fixed:reports:reader` and <br>`reports.admin:write`<br>`reports:delete`<br>`reports.settings:write` | Create, read, update, or delete all reports and shared report settings. |
| `fixed:users:reader` | `users:read`<br>`users.quotas:list`<br>`users.authtoken:list`<br>`users.teams:read` | Read all users and their information, such as team memberships, authentication tokens, and quotas. |

15
docs/sources/enterprise/access-control/manage-role-assignments/_index.md Normal file
View File

@@ -0,0 +1,15 @@
+++
title = "Manage role assignments"
description = ""
keywords = ["grafana", "fine-grained-access-control", "roles", "permissions", "enterprise"]
weight = 115
+++
# Manage role assignments
To grant or revoke access to your users, you can assign [Roles]({{< relref "../roles.md" >}}) to users, [Organization roles]({{< relref "../../../permissions/organization_roles.md" >}}) and [Grafana Server Admin]({{< relref "../../../permissions/_index.md#grafana-server-admin-role" >}}) role.
The following pages provide more information on how to manage role assignments:
- [Manage user role assignments]({{< relref "manage-user-role-assignments.md" >}}).
- [Manage role assignments to Organization roles and Grafana Server Admin role]({{< relref "manage-built-in-role-assignments.md" >}}).

19
docs/sources/enterprise/access-control/manage-role-assignments/manage-built-in-role-assignments.md Normal file
View File

@@ -0,0 +1,19 @@
+++
title = "Manage built-in role assignments"
description = "Manage built-in role assignments"
keywords = ["grafana", "fine-grained-access-control", "roles", "permissions", "fine-grained-access-control-usage", "enterprise"]
weight = 210
+++
# Built-in role assignments
To control what your users can access or not, you can assign or unassign [Custom roles]({{< ref "#custom-roles" >}}) or [Fixed roles]({{< ref "#fixed-roles" >}}) to the existing [Organization roles]({{< relref "../../../permissions/organization_roles.md" >}}) or to [Grafana Server Admin]({{< relref "../../../permissions/_index.md#grafana-server-admin-role" >}}) role.
These assignments are called built-in role assignments.
During startup, Grafana will create default assignments for you. When you make any changes to the built-on role assignments, Grafana will take them into account and won’t overwrite during next start.
For more information, refer to [Fine-grained access control references]({{< relref "../fine-grained-access-control-references.md#default-built-in-role-assignments" >}}).
# Manage built-in role assignments
You can create or remove built-in role assignments using [Fine-grained access control API]({{< relref "../../../http_api/access_control.md#create-and-remove-built-in-role-assignments" >}}) or using [Grafana Provisioning]({{< relref "../provisioning.md#manage-default-built-in-role-assignments" >}}).

64
docs/sources/enterprise/access-control/manage-role-assignments/manage-user-role-assignments.md Normal file
View File

@@ -0,0 +1,64 @@
+++
title = "Manage user role assignments"
description = "Manage user role assignments"
keywords = ["grafana", "fine-grained-access-control", "roles", "permissions", "fine-grained-access-control-usage", "enterprise"]
weight = 200
+++
# Manage user role assignments
There are two ways to assign roles directly to users: in the UI using the role picker, and using the API.
## Manage users' roles within a specific Organization using the role picker
In order to assign roles to a user within a specific Organization using the role picker, you must have a user account with one of the following:
- The Admin built-in role.
- The Server Admin role.
- The fixed role `fixed:permissions:writer`, [assigned for the given Organization]({{< relref "../roles/#scope-of-assignments" >}}).
- A custom role with `users.roles:add` and `users.roles:remove` permissions.
You must also have the permissions granted by the roles that you want to assign or revoke.
Steps:
1. Navigate to the Users Configuration page by hovering over **Configuration** (the gear icon) in the left navigation menu and selecting **Users**.
1. Click on the **Role** column in the row for the user whose role you would like to edit.
1. Deselect one or more selected roles that you would like to remove from that user.
1. Select one or more roles that you would like to assign to that user.
1. Click the **Apply** button to apply the selected roles to that user.
![User role picker in Organization](/static/img/docs/enterprise/user_role_picker_global.png)
The user's permissions will update immediately, and the UI will reflect their new permissions the next time they reload their browser or visit a new page.
**Note**: The roles that you select will be assigned only within the given Organization. For example, if you grant the user the "Data source editor" role while you are in the main Organization, then that user will be able to edit data source in the main Organization but not in others.
## Manage users' roles in multiple Organizations using the role picker
In order to assign roles across multiple Organizations to a user using the role picker, you must have a user account with one of the following:
- The Server Admin built-in role
- The fixed role `fixed:permissions:writer`, [assigned globally]({{< relref "../roles/#scope-of-assignments" >}}).
- A custom role with `users.roles:add` and `users.roles:remove` permissions, [assigned globally]({{< relref "../roles/#scope-of-assignments" >}}).
You must also have the permissions granted by the roles that you want to assign or revoke within the Organization in which you're making changes.
Steps:
1. Navigate to the Users Admin page by hovering over **Server Admin** (the shield icon) in the left navigation menu and selecting **Users**.
1. Click on a user row to edit that user's roles.
1. Under the **Organizations** header, you will see a list of roles assigned to that user within each of their Organizations. Click on the roles in an organization to open the role picker.
1. Deselect one or more selected roles that you would like to remove from that user.
1. Select one or more roles that you would like to assign to that user.
1. Click the **Apply** button to apply the selected roles to that user.
![User role picker in Organization](/static/img/docs/enterprise/user_role_picker_in_org.png)
The user's permissions will update immediately, and the UI will reflect their new permissions the next time they reload their browser or visit a new page.
**Note**: The roles that you select will be assigned only within one Organization. For example, if you grant the user the "Data source editor" role in the row for the main Organization, then that user will be able to edit data source in the main Organization but not in others.
## Manage users' roles via API
To manage user role assignment via API, refer to the [fine-grained access control HTTP API docs]({{< relref "../../../http_api/access_control.md#create-and-remove-user-role-assignments" >}}).

6
docs/sources/enterprise/access-control/permissions.md
View File

@@ -2,7 +2,7 @@
title = "Permissions"
description = "Understand fine-grained access control permissions"
keywords = ["grafana", "fine-grained access-control", "roles", "permissions", "enterprise"]
weight = 115
weight = 110
+++
# Permissions
@@ -54,6 +54,10 @@ The following list contains fine-grained access control actions.
| `users:logout` | `global:users:*` <br> `global:users:id:*` | Sign out a user. |
| `users.quotas:list` | `global:users:*` <br> `global:users:id:*` | List a user’s quotas. |
| `users.quotas:update` | `global:users:*` <br> `global:users:id:*` | Update a user’s quotas. |
| `users.roles:list` | `users:*` | List roles assigned directly to a user. |
| `users.roles:add` | `permissions:delegate` | Assign a role to a user. |
| `users.roles:remove` | `permissions:delegate` | Unassign a role from a auser. |
| `users.permissions:list` | `users:*` | List permissions of a user. |
| `org.users:read` | `users:*` <br> `users:id:*` | Get user profiles within an organization. |
| `org.users:add` | `users:*` | Add a user to an organization. |
| `org.users:remove` | `users:*` <br> `users:id:*` | Remove a user from an organization. |

2
docs/sources/enterprise/access-control/provisioning.md
View File

@@ -25,7 +25,7 @@ You can create, update, and delete custom roles, as well as create and remove bu
To create or update custom roles, you can add a list of `roles` in the configuration.
Every role has a [version]({{< relref "./roles.md#custom-roles" >}}) number. For each role you update, you must remember to increment it, otherwise changes won't be accounted for.
Every role has a [version]({{< relref "./roles.md#custom-roles" >}}) number. For each role you update, you must remember to increment it, otherwise changes won't be applied.
When you update a role, the existing role inside Grafana is altered to be exactly what is specified in the YAML file, including permissions.

23
docs/sources/enterprise/access-control/roles.md
View File

@@ -44,6 +44,14 @@ Role names must be unique within an organization.
Roles with names prefixed by `fixed:` are fixed roles created by Grafana and cannot be created or modified by users.
### Display name
A role's display name is intended as a human friendly identifier for the role, helping users understand the purpose of a role. The display name of the role is displayed in the role picker in the UI.
### Group
A role's group is used to organize roles in the role picker in the UI.
### Role version
The version of a role is a positive integer which defines the current version of the role. When updating a role, you can either omit the version field to increment the previous value by 1 or set a new version which must be strictly larger than the previous version for the update to succeed.
@@ -67,20 +75,13 @@ If a Grafana Server Admin wants to delegate that privilege to other users, they
Note that you won't be able to create, update or delete a custom role with permissions which you yourself do not have. For example, if the only permission you have is a `users:create`, you won't be able to create a role with other permissions.
## Built-in role assignments
## Assign roles
To control what your users can access or not, you can assign or unassign [Custom roles]({{< ref "#custom-roles" >}}) or [Fixed roles]({{< ref "#fixed-roles" >}}) to the existing [Organization roles]({{< relref "../../permissions/organization_roles.md" >}}) or to [Grafana Server Admin]({{< relref "../../permissions/_index.md#grafana-server-admin-role" >}}) role.
These assignments are called built-in role assignments.
[Custom roles]({{< ref "#custom-roles" >}}) and [Fixed roles]({{< ref "#fixed-roles" >}}) can be assigned to users, the existing [Organization roles]({{< relref "../../permissions/organization_roles.md" >}}) and to [Grafana Server Admin]({{< relref "../../permissions/_index.md#grafana-server-admin-role" >}}) role.
During startup, Grafana will create default assignments for you. When you make any changes to the built-on role assignments, Grafana will take them into account and won’t overwrite during next start.
For more information, refer to [Fine-grained access control references]({{< relref "./fine-grained-access-control-references.md#default-built-in-role-assignments" >}}).
## Create and remove built-in role assignments
You can create or remove built-in role assignments using [Fine-grained access control API]({{< relref "../../http_api/access_control.md" >}}) or using [Grafana Provisioning]({{< relref "./provisioning" >}}).
Visit [Manage role assignments]({{< relref "manage-role-assignments/_index.md" >}}) page for more details.
### Scope of assignments
A built-in role assignment can be either _global_ or _organization local_. _Global_ assignments are not mapped to any specific organization and will be applied to all organizations, whereas _organization local_ assignments are only applied for that specific organization.
A role assignment can be either _global_ or _organization local_. _Global_ assignments are not mapped to any specific organization and will be applied to all organizations, whereas _organization local_ assignments are only applied for that specific organization.
You can only create _organization local_ assignments for _organization local_ roles.

4
docs/sources/enterprise/access-control/usage-scenarios.md
View File

@@ -132,6 +132,10 @@ Example response:
}
```
## Manage roles granted directly to users
To learn about granting roles to users, refer to [Manage user role assignments]({{< relref "manage-role-assignments/manage-user-role-assignments.md" >}}) page.
## Create your first custom role
You can create your custom role by either using an [HTTP API]({{< relref "../../http_api/access_control.md#create-a-new-custom-role" >}}) or by using [Grafana provisioning]({{< relref "./provisioning.md" >}}).

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

@@ -86,23 +86,27 @@ Content-Type: application/json; charset=UTF-8
#### Status codes
| Code | Description |
| ---- | -------------------------------------------------------------------- |
| 200 | Global and organization local roles are returned. |
| 403 | Access denied |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
### Get a role
| ---- | -------------------------------------------------------------------- |
| 200 | Global and organization local roles are returned. |
| 403 | Access denied |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
### Get a role
`GET /api/access-control/roles/:uid`
Get a role for the given UID.
Get a role for the given UID.
#### Required permissions
| Action | Scope |
| ---------- | -------- |
| roles:read | roles:\* |
#### Required permissions
| Action | Scope |
| ---------- | -------- |
| roles:read | roles:\* |
#### Example request
```http
GET /api/access-control/roles/PYnDO3rMk
Accept: application/json
Content-Type: application/json
```
@@ -141,27 +145,59 @@ HTTP/1.1 200 OK
#### Example request
```http
#### Example request
```http
POST /api/access-control/roles
POST /api/access-control/roles
Accept: application/json
Content-Type: application/json
{
"version": 1,
"uid": "jZrmlLCGka",
"name": "custom:delete:roles",
{
"version": 1,
"uid": "jZrmlLCGka",
"description": "My custom role which gives users permissions to delete roles",
"group":"My Group",
"displayName": "My Custom Role",
"global": false,
"permissions": [
{
"global": true,
"permissions": [
{
"action": "roles:delete",
"action": "roles:delete",
"scope": "permissions:delegate"
}
]
}
```
#### JSON body schema
| Field Name | Date Type | Required | Description |
| ----------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| uid | string | No | UID of the role. If not present, the UID will be automatically created for you and returned in response. Refer to the [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information. |
| 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 [Role scopes]({{< relref "../enterprise/access-control/roles.md#role-scopes" >}}) for more information. |
| version | number | No | Version of the role. If not present, version 0 will be assigned to the role and returned in the response. Refer to the [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information. |
| name | string | Yes | Name of the role. Refer to [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information. |
| 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. |
| permissions | Permission | No | If not present, the role will be created without any permissions. |
**Permission**
| Field Name | Data Type | Required | Description |
| ---------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| action | string | Yes | Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md" >}}) for full list of available actions. |
| scope | string | No | If not present, no scope will be mapped to the permission. Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md#scope-definitions" >}}) for full list of available scopes. |
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
```
#### Status codes
]
}
| Code | Description |
| ---- | ---------------------------------------------------------------------------------- |
| 200 | Role is updated. |
| 400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.). |
| 403 | Access denied |
@@ -170,7 +206,7 @@ Content-Type: application/json; charset=UTF-8
### Update a custom role
`PUT /api/access-control/roles/:uid`
| version | number | No | Version of the role. If not present, version 0 will be assigned to the role and returned in the response. Refer to the [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information. |
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.
#### Required permissions
@@ -200,7 +236,9 @@ Content-Type: application/json
{
"action": "roles:delete",
"scope": "permissions:delegate"
},
{
"action": "roles:write",
"scope": "permissions:delegate"
}
]
@@ -219,6 +257,8 @@ Content-Type: application/json
| permissions | List of Permissions | No | The full list of permissions the role should have after the update. |
**Permission**
| Field Name | Data Type | Required | Description |
| ---------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| action | string | Yes | Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md" >}}) for full list of available actions. |
| scope | string | No | If not present, no scope will be mapped to the permission. Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md#scope-definitions" >}}) for full list of available scopes. |
@@ -239,7 +279,9 @@ Content-Type: application/json; charset=UTF-8
| 400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.). |
| 403 | Access denied |
| 404 | Role was not found to update. |
#### JSON body schema
| 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`
@@ -288,7 +330,9 @@ Content-Type: application/json
### List roles assigned to a user
#### Example request
`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.
#### Required permissions
@@ -309,6 +353,8 @@ Content-Type: application/json
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
```
#### Status codes
| Code | Description |
@@ -329,6 +375,8 @@ Content-Type: application/json; charset=UTF-8
| ---------------------- | -------------------- |
| users.permissions:list | users:id:`<user ID>` |
#### Example request
```http
GET /api/access-control/users/1/permissions
Accept: application/json
@@ -345,7 +393,7 @@ Content-Type: application/json; charset=UTF-8
#### Status codes
| Code | Description |
HTTP/1.1 200 OK
| ---- | -------------------------------------------------------------------- |
| 200 | Set of assigned permissions is returned. |
| 403 | Access denied. |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
@@ -377,7 +425,7 @@ For example, if a user does not have required permissions for creating users, th
{
"global": false,
Accept: application/json
"roleUid": "XvHQJq57z"
}
```
@@ -407,6 +455,275 @@ Content-Type: application/json; charset=UTF-8
## Remove a user role assignment
`DELETE /api/access-control/users/:userId/roles/:roleUID`
Revoke a role from a user.
For bulk updates consider
[Set user role assignments]({{< ref "#set-user-role-assignments" >}}).
#### Required permissions
`permission:delegate` scope ensures that users can only unassign 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 unassign a role which will allow to do that. This is done to prevent escalation of privileges.
| Action | Scope |
| ------------------ | -------------------- |
| users.roles:remove | permissions:delegate |
#### 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 request
```http
DELETE /api/access-control/users/1/roles/AFUXBHKnk
Accept: application/json
```
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
```
#### Status codes
| Code | Description |
| ---- | -------------------------------------------------------------------- |
| 200 | Role is unassigned. |
| 403 | Access denied. |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
### Set user role assignments
`PUT /api/access-control/users/:userId/roles`
Update the user's role assignments to match the provided set of UIDs.
This will remove any assigned roles that aren't in the request and add
roles that are in the set but are not already assigned to the user.
If you want to add or remove a single role, consider using
[Add a user role assignment]({{< ref "#add-a-user-role-assignment" >}}) or
[Remove a user role assignment]({{< ref "#remove-a-user-role-assignment" >}})
instead.
#### Required permissions
`permission:delegate` scope ensures that users can only assign or unassign 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 assign or unassign a role which will allow to do that. This is done to prevent escalation of privileges.
| Action | Scope |
| ------------------ | -------------------- |
| users.roles:add | permissions:delegate |
| users.roles:remove | permissions:delegate |
#### Example request
```http
PUT /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json
{
"global": false,
"roleUids": [
"ZiHQJq5nk",
"GzNQ1357k"
]
}
```
#### JSON body schema
| Field Name | Date 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. |
| roleUids | list | Yes | List of role UIDs. |
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
```
#### 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
```
#### 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
```
#### 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
```
#### 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. |
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "User 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.
@@ -444,7 +761,7 @@ Content-Type: application/json; charset=UTF-8
"uid": "qQui_LCMk",
"name": "fixed:users:org:edit",
"description": "",
HTTP/1.1 200 OK
"global": false,
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
},
@@ -453,7 +770,7 @@ Content-Type: application/json; charset=UTF-8
"uid": "PeXmlYjMk",
"name": "fixed:users:org:read",
"description": "",
| 200 | Role was unassigned from built-in role. |
"global": false,
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
}
@@ -464,7 +781,7 @@ Content-Type: application/json; charset=UTF-8
"uid": "qQui_LCMk",
"name": "fixed:users:org:edit",
"description": "",
"global": true,
"global": false,
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
}