mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
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
GitHub
parent
e3c1faad56
commit
83e234d4f6
@ -1,76 +1,68 @@
|
||||
# ---
|
||||
# # config file version
|
||||
# apiVersion: 1
|
||||
# apiVersion: 2
|
||||
|
||||
# # list of default built-in role assignments that should be removed
|
||||
# removeDefaultAssignments:
|
||||
# # <string>, must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
|
||||
# - builtInRole: "Grafana Admin"
|
||||
# # <string>, must be one of the existing fixed roles
|
||||
# fixedRole: "fixed:permissions:admin"
|
||||
|
||||
# # list of default built-in role assignments that should be added back
|
||||
# addDefaultAssignments:
|
||||
# # <string>, must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
|
||||
# - builtInRole: "Admin"
|
||||
# # <string>, must be one of the existing fixed roles
|
||||
# fixedRole: "fixed:reporting:admin:read"
|
||||
|
||||
# # list of roles that should be deleted
|
||||
# deleteRoles:
|
||||
# # <string> name of the role you want to create. Required if no uid is set
|
||||
# - name: "custom:reports:editor"
|
||||
# # <string> uid of the role. Required if no name
|
||||
# uid: "customreportseditor1"
|
||||
# # <int> org id. will default to Grafana's default if not specified
|
||||
# orgId: 1
|
||||
# # <bool> force deletion revoking all grants of the role
|
||||
# force: true
|
||||
# - name: "custom:global:reports:reader"
|
||||
# uid: "customglobalreportsreader1"
|
||||
# # <bool> overwrite org id and removes a global role
|
||||
# global: true
|
||||
# force: true
|
||||
|
||||
# # list of roles to insert/update depending on what is available in the database
|
||||
# # <list> list of roles to insert/update/delete
|
||||
# roles:
|
||||
# # <string, required> name of the role you want to create. Required
|
||||
# - name: "custom:users:editor"
|
||||
# # <string, required> name of the role you want to create or update. Required.
|
||||
# - name: 'custom:users:writer'
|
||||
# # <string> uid of the role. Has to be unique for all orgs.
|
||||
# uid: customuserseditor1
|
||||
# uid: customuserswriter1
|
||||
# # <string> description of the role, informative purpose only.
|
||||
# description: "Role for our custom user editors"
|
||||
# # <int> version of the role, Grafana will update the role when increased
|
||||
# description: 'Create, read, write users'
|
||||
# # <int> version of the role, Grafana will update the role when increased.
|
||||
# version: 2
|
||||
# # <int> org id. will default to Grafana's default if not specified
|
||||
# orgId: 1
|
||||
# # <list> list of the permissions granted by this role
|
||||
# # <int> org id. Defaults to Grafana's default if not specified.
|
||||
# orgId: 1
|
||||
# # <list> list of the permissions granted by this role.
|
||||
# permissions:
|
||||
# # <string, required> action allowed
|
||||
# - action: "users:read"
|
||||
# #<string> scope it applies to
|
||||
# scope: "users:*"
|
||||
# - action: "users:write"
|
||||
# scope: "users:*"
|
||||
# - action: "users:create"
|
||||
# scope: "users:*"
|
||||
# # <list> list of builtIn roles the role should be assigned to
|
||||
# builtInRoles:
|
||||
# # <string, required> name of the builtin role you want to assign the role to
|
||||
# - name: "Editor"
|
||||
# # <int> org id. will default to the role org id
|
||||
# orgId: 1
|
||||
# - name: "custom:global:users:reader"
|
||||
# uid: "customglobalusersreader1"
|
||||
# description: "Global Role for custom user readers"
|
||||
# version: 1
|
||||
# # <bool> overwrite org id and creates a global role
|
||||
# # <string, required> action allowed.
|
||||
# - action: 'users:read'
|
||||
# #<string> scope it applies to.
|
||||
# scope: 'users:*'
|
||||
# - action: 'users:write'
|
||||
# scope: 'users:*'
|
||||
# - action: 'users:create'
|
||||
# - name: 'custom:global:users:reader'
|
||||
# # <bool> overwrite org id and creates a global role.
|
||||
# global: true
|
||||
# permissions:
|
||||
# - action: "users:read"
|
||||
# scope: "users:*"
|
||||
# builtInRoles:
|
||||
# - name: "Viewer"
|
||||
# orgId: 1
|
||||
# - name: "Editor"
|
||||
# # <bool> overwrite org id and assign role globally
|
||||
# # <string> state of the role. Defaults to 'present'. If 'absent', role will be deleted.
|
||||
# state: 'absent'
|
||||
# # <bool> force deletion revoking all grants of the role.
|
||||
# force: true
|
||||
# - uid: 'basic_editor'
|
||||
# version: 2
|
||||
# global: true
|
||||
# # <list> list of roles to copy permissions from.
|
||||
# from:
|
||||
# - uid: 'basic_editor'
|
||||
# global: true
|
||||
# - name: 'fixed:users:writer'
|
||||
# global: true
|
||||
# # <list> list of the permissions to add/remove on top of the copied ones.
|
||||
# permissions:
|
||||
# - action: 'users:read'
|
||||
# scope: 'users:*'
|
||||
# - action: 'users:write'
|
||||
# scope: 'users:*'
|
||||
# # <string> state of the permission. Defaults to 'present'. If 'absent', the permission will be removed.
|
||||
# state: absent
|
||||
|
||||
# # <list> list role assignments to teams to create or remove.
|
||||
# teams:
|
||||
# # <string, required> name of the team you want to assign roles to. Required.
|
||||
# - name: 'Users writers'
|
||||
# # <int> org id. Will default to Grafana's default if not specified.
|
||||
# orgId: 1
|
||||
# # <list> list of roles to assign to the team
|
||||
# roles:
|
||||
# # <string> uid of the role you want to assign to the team.
|
||||
# - uid: 'customuserswriter1'
|
||||
# # <int> org id. Will default to Grafana's default if not specified.
|
||||
# orgId: 1
|
||||
# # <string> name of the role you want to assign to the team.
|
||||
# - name: 'fixed:users:writer'
|
||||
# # <bool> overwrite org id to specify the role is global.
|
||||
# global: true
|
||||
# # <string> state of the assignment. Defaults to 'present'. If 'absent', the assignment will be revoked.
|
||||
# state: absent
|
||||
|
||||
@ -19,13 +19,12 @@ By using RBAC you can provide users with permissions that extend the permissions
|
||||
- Assign fixed roles to users and teams: for example, grant an engineering team the ability to create data sources
|
||||
- Create custom roles: for example, a role that allows users to create and edit dashboards, but not delete them
|
||||
|
||||
Basic roles contain multiple fixed roles. Fixed roles in turn contain multiple permissions, each of which has an action and a scope. Here is an example of the hierarchy of Basic roles, fixed roles, permissions, actions, and scopes.
|
||||
RBAC roles contain multiple permissions, each of which has an action and a scope:
|
||||
|
||||
- **Basic role:** `Viewer`
|
||||
- **Fixed role:** `fixed:datasources:reader`
|
||||
- **Permission:**
|
||||
- **Action:** `datasources:read`
|
||||
- **Scope:** `datasources:*`
|
||||
- **Role:** `fixed:datasources:reader`
|
||||
- **Permission:**
|
||||
- **Action:** `datasources:read`
|
||||
- **Scope:** `datasources:*`
|
||||
|
||||
## Basic roles
|
||||
|
||||
@ -38,17 +37,22 @@ Grafana includes the following basic roles:
|
||||
- Editor
|
||||
- Viewer
|
||||
|
||||
Each basic role is comprised of a number of _fixed roles_ that control the permissions a basic role grants. For example, the viewer basic role contains the following fixed roles among others:
|
||||
Each basic role is comprised of a number of _permissions_. For example, the viewer basic role contains the following permissions among others:
|
||||
|
||||
- `fixed:datasources:id:reader`: Enables the viewer to see the ID of a data source.
|
||||
- `fixed:organization:reader`: Enables the viewer to see a list of organizations.
|
||||
- `fixed:annotations:reader`: Enables the viewer to see annotations that other users have added to a dashboard.
|
||||
- `fixed:annotations.dashboard:writer`: Enables the viewer to add annotations to a dashboard.
|
||||
- `Action: datasources.id:read, Scope: datasources:*`: Enables the viewer to see the ID of a data source.
|
||||
- `Action: orgs:read`: Enables the viewer to see their organization details
|
||||
- `Action: annotations:read, Scope: annotations:*`: Enables the viewer to see annotations that other users have added to a dashboard.
|
||||
- `Action: annotations:create, Scope: annotations:type:dashboard`: Enables the viewer to add annotations to a dashboard.
|
||||
- `Action: annotations:write, Scope: annotations:type:dashboard`: Enables the viewer to modify annotations of a dashboard.
|
||||
- `Action: annotations:delete, Scope: annotations:type:dashboard`: Enables the viewer to remove annotations from a dashboard.
|
||||
|
||||
You can use RBAC to modify the fixed roles associated with any basic role, to modify what viewers, editors, or admins can do. For more information about the fixed roles associated with each basic role, refer to [Basic role definitions]({{< relref "./rbac-fixed-basic-role-definitions#basic-role-assignments" >}}).
|
||||
You can use RBAC to modify the permissions associated with any basic role, which changes what viewers, editors, or admins can do. For more information about the permissions associated with each basic role, refer to [Basic role definitions]({{< relref "./rbac-fixed-basic-role-definitions#basic-role-assignments" >}}).
|
||||
You cannot delete basic roles.
|
||||
|
||||
> **Note:** You must assign each Grafana user a basic role.
|
||||
|
||||
To interact with the API and view or modify basic roles permissions, refer to [the table]({{< relref "./manage-rbac-roles#basic-role-uid-mapping" >}}) that maps basic role names to the associated UID.
|
||||
|
||||
## Fixed roles
|
||||
|
||||
Grafana Enterprise includes the ability for you to assign discrete fixed roles to users and teams. This gives you finer-grained control over user permissions than you would have with basic roles alone. These roles are called "fixed" because you cannot change or delete fixed roles. You can also create _custom_ roles of your own; see more information in the [custom roles section]({{< relref "#custom-roles" >}}) below.
|
||||
@ -81,7 +85,7 @@ If you are a Grafana Enterprise customer, you can create custom roles to manage
|
||||
|
||||
Custom roles contain unique combinations of permissions _actions_ and _scopes_. An action defines the action a use can perform on a Grafana resource. For example, the `teams.roles:list` action allows a user to see a list of roles associated with each team.
|
||||
|
||||
A scope describes where an action can be performed. For example, the `teams:1` scope restricts the user's action to the team with ID `1`. When paired with the `teams.roles:list` action, this permission prohibits the user from viewing the roles for teams other than team `1`.
|
||||
A scope describes where an action can be performed. For example, the `teams:id:1` scope restricts the user's action to the team with ID `1`. When paired with the `teams.roles:list` action, this permission prohibits the user from viewing the roles for teams other than team `1`.
|
||||
|
||||
Consider creating a custom role when fixed roles do not meet your permissions requirements.
|
||||
|
||||
|
||||
@ -79,70 +79,46 @@ Instead of using the Grafana role picker, you can use file-based provisioning to
|
||||
|
||||
</br>
|
||||
|
||||
**To assign a fixed role to a team:**
|
||||
**To assign a role to a team:**
|
||||
|
||||
1. Open the YAML configuration file.
|
||||
|
||||
1. Refer to the following table to add attributes and values.
|
||||
|
||||
| Attribute | Description |
|
||||
| --------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `name` | Enter the name of the fixed role. |
|
||||
| `global` | Enter `true`. Because fixed roles are global, you must specify the global attribute. You cannot change fixed role definitions. |
|
||||
| `teams` | Enter the team or teams to which you are adding the fixed role. |
|
||||
| `orgId` | Because teams belong to organizations, you must add the `orgId` value. |
|
||||
| Attribute | Description |
|
||||
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `roles` | Enter the custom role or custom roles you want to create/update. |
|
||||
| `roles > name` | Enter the name of the custom role. |
|
||||
| `roles > version` | Enter the custom role version number. Role assignments are independent of the role version number. |
|
||||
| `roles > global` | Enter `true`. You can specify the `orgId` otherwise. |
|
||||
| `roles > permissions` | Enter the permissions `action` and `scope` values. For more information about permissions actions and scopes, refer to [RBAC permissions, actions, and scopes]({{< relref "./custom-role-actions-scopes.md">}}) |
|
||||
| `teams` | Enter the team or teams to which you are adding the custom role. |
|
||||
| `teams > orgId` | Because teams belong to organizations, you must add the `orgId` value. |
|
||||
| `teams > name` | Enter the name of the team. |
|
||||
| `teams > roles` | Enter the custom or fixed role or roles that you want to grant to the team. |
|
||||
| `teams > roles > name` | Enter the name of the role. |
|
||||
| `teams > roles > global` | Enter `true`, or specify `orgId` of the role you want to assign to the team. Fixed roles are global. |
|
||||
|
||||
For more information about managing custom roles, refer to [Create custom roles using provisioning]({{< relref "./manage-rbac-roles/#create-custom-roles-using-provisioning" >}}).
|
||||
|
||||
1. Reload the provisioning configuration file.
|
||||
|
||||
For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}).
|
||||
|
||||
The following example assigns the `users:writer` fixed role to the `user editors` and `user admins` teams:
|
||||
The following example creates the `custom:users:writer` role and assigns it to the `user writers` and `user admins` teams along with the `fixed:users:writer` role:
|
||||
|
||||
The following example:
|
||||
|
||||
- Creates the `custom:users:writer` role.
|
||||
- Assigns the `custom:users:writer` role and the `fixed:users:writer` role to the `user admins` and `user writers` teams.
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
apiVersion: 2
|
||||
|
||||
# Roles to insert/update in the database
|
||||
roles:
|
||||
- name: fixed:users:writer
|
||||
global: true
|
||||
teams:
|
||||
- name: 'user editors'
|
||||
orgId: 1
|
||||
- name: 'user admins'
|
||||
orgId: 1
|
||||
```
|
||||
|
||||
</br>
|
||||
|
||||
**To assign a custom role to a team:**
|
||||
|
||||
1. Open the YAML configuration file.
|
||||
|
||||
1. Refer to the following table to add attributes and values.
|
||||
|
||||
| Attribute | Description |
|
||||
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `name` | Enter the name of the custom role. |
|
||||
| `version` | Enter the custom role version number. Assignments are updated if the version of the role is greater then or equal to the version number stored internally. If you are updating a role assignment, you are not required to increment the role version number. |
|
||||
| `global` | Enter `true` or `false` |
|
||||
| `permissions` | Enter the permissions `action` and `scope` values. For more information about permissions actions and scopes, refer to [LINK] |
|
||||
| `teams` | Enter the team or teams to which you are adding the custom role. |
|
||||
| `orgId` | Because teams belong to organizations, you must add the `orgId` value. |
|
||||
|
||||
1. Reload the provisioning configuration file.
|
||||
|
||||
For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}).
|
||||
|
||||
The following example assigns the `custom:users:writer` role to the `user editors` and `user admins` teams:
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# Roles to insert/update in the database
|
||||
roles:
|
||||
- name: custom:users:writer
|
||||
- name: 'custom:users:writer'
|
||||
description: 'List/update other users in the organization'
|
||||
version: 1
|
||||
global: true
|
||||
@ -151,139 +127,73 @@ roles:
|
||||
scope: 'users:*'
|
||||
- action: 'org.users:write'
|
||||
scope: 'users:*'
|
||||
teams:
|
||||
- name: 'user editors'
|
||||
orgId: 1
|
||||
- name: 'user admins'
|
||||
orgId: 1
|
||||
|
||||
# Assignments to teams
|
||||
teams:
|
||||
- name: 'user writers'
|
||||
orgId: 1
|
||||
roles:
|
||||
# Custom role assignment
|
||||
- name: 'custom:users:writer'
|
||||
global: true
|
||||
# Fixed role assignment
|
||||
- name: 'fixed:users:writer'
|
||||
global: true
|
||||
- name: 'user admins'
|
||||
orgId: 1
|
||||
roles:
|
||||
- name: 'custom:users:writer'
|
||||
global: true
|
||||
- name: 'fixed:users:writer'
|
||||
global: true
|
||||
```
|
||||
|
||||
> **Note:** If you want to remove a fixed role assignment from a team, remove it from the YAML file, save your changes, and reload the configuration file.
|
||||
> **Note**: The roles don't have to be defined in the provisioning configuration files to be assigned. If roles exist in the database, they can be assigned.
|
||||
|
||||
## Assign a fixed or custom role to a basic role
|
||||
**Remove a role assignment from a team:**
|
||||
|
||||
If you want to extend the permissions of a basic role, you can modify it by adding a fixed role or a basic role to it.
|
||||
If you want to remove an assignment from a team, add `state: absent` to the `teams > roles` section, and reload the configuration file.
|
||||
|
||||
You can also remove fixed or custom roles from basic roles. For example, you can remove the `fixed:users:writer` fixed role from the Administrator basic role if you would prefer that administrators not manage users. Learn more in the topic [remove a fixed role from a basic role]({{< relref "manage-rbac-roles.md#remove-a-fixed-role-from-a-basic-role" >}}).
|
||||
The following example:
|
||||
|
||||
### Assign a fixed role to a basic role using provisioning
|
||||
|
||||
If you want to extend the permissions of a basic role, and you identify a fixed role that meets your permission requirements, you can assign a fixed role to a basic role.
|
||||
|
||||
</br>
|
||||
|
||||
**Before you begin:**
|
||||
|
||||
- [Enable role provisioning]({{< relref "./enable-rbac-and-provisioning#enable-role-provisioning" >}})
|
||||
- Determine which fixed role you want to add to a basic role
|
||||
|
||||
</br>
|
||||
|
||||
**To add a fixed role to a basic role:**
|
||||
|
||||
1. Open the YAML configuration file and locate the `addDefaultAssignments` section.
|
||||
|
||||
1. Refer to the following table to add attributes and values.
|
||||
|
||||
| Attribute | Description |
|
||||
| ------------- | --------------------------------- |
|
||||
| `builtInRole` | Enter the name of the basic role. |
|
||||
| `fixedRole` | Enter the name of the fixed role. |
|
||||
|
||||
1. Reload the provisioning configuration file.
|
||||
|
||||
For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}).
|
||||
|
||||
The following example restores a default basic and fixed role assignment.
|
||||
- Creates the `custom:users:writer` role
|
||||
- Assigns the `custom:users:writer` role and the `fixed:users:writer` role to the `user admins` team
|
||||
- Removes the `custom:users:writer` and the `fixed:users:writer` assignments from the `user writers` team, if those assignments exist.
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# list of default basic role assignments that should be added back
|
||||
addDefaultAssignments:
|
||||
- builtInRole: 'Admin'
|
||||
fixedRole: 'fixed:reporting:admin:read'
|
||||
```
|
||||
|
||||
### Assign a custom role to a basic role using provisioning
|
||||
|
||||
If you want to extend the permissions of a basic role, and assigning fixed roles to the basic role does not meet your permission requirements, you can create a custom role and assign that role to a basic role.
|
||||
|
||||
</br>
|
||||
|
||||
**Before you begin:**
|
||||
|
||||
- [Enable role provisioning]({{< relref "./enable-rbac-and-provisioning#enable-role-provisioning" >}})
|
||||
- [Add a custom role]({{< relref "./manage-rbac-roles#create-custom-role" >}})
|
||||
|
||||
</br>
|
||||
|
||||
**To assign a custom role to a basic role:**
|
||||
|
||||
1. Open the YAML configuration file and locate the `builtInRoles` section.
|
||||
|
||||
1. Refer to the following table to add attributes and values.
|
||||
|
||||
| Attribute | Description |
|
||||
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `name` | Enter the name of the custom role. |
|
||||
| `version` | Enter the custom role version number. Assignments are updated if the version of the role is greater than or equal to the version number stored internally. If you are updating a role assignment, you are not required to increment the role version number. |
|
||||
| `orgId` | If you do not enter an `orgId`, it inherits the `orgId` from `role`. For global roles the default `orgId` is used. `orgId` in the `role` and in the assignment must be the same for non-global roles. |
|
||||
| `permissions` | Enter the permissions `action` and `scope` values. For more information about permissions actions and scopes, refer to [LINK] |
|
||||
| `builtInRoles` | Enter the `name` of an organization role, for example `Viewer`, `Editor`, or `Admin`, or enter `Grafana Admin`. |
|
||||
|
||||
1. Reload the provisioning configuration file.
|
||||
|
||||
For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}).
|
||||
|
||||
The following example assigns the `users:editor` custom role to the basic editor and admin roles.
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
apiVersion: 2
|
||||
|
||||
# Roles to insert/update in the database
|
||||
roles:
|
||||
- name: custom:users:editor
|
||||
description: 'This role allows users to list/create/update other users in the organization'
|
||||
- name: 'custom:users:writer'
|
||||
description: 'List/update other users in the organization'
|
||||
version: 1
|
||||
orgId: 1
|
||||
global: true
|
||||
permissions:
|
||||
- action: 'users:read'
|
||||
- action: 'org.users:read'
|
||||
scope: 'users:*'
|
||||
- action: 'users:write'
|
||||
- action: 'org.users:write'
|
||||
scope: 'users:*'
|
||||
- action: 'users:create'
|
||||
scope: 'users:*'
|
||||
builtInRoles:
|
||||
- name: 'Editor'
|
||||
- name: 'Admin'
|
||||
|
||||
# Assignments to teams
|
||||
teams:
|
||||
- name: 'user writers'
|
||||
orgId: 1
|
||||
roles:
|
||||
- name: 'fixed:users:writer'
|
||||
global: true
|
||||
state: 'absent' # Remove assignment
|
||||
- name: 'custom:users:writer'
|
||||
global: true
|
||||
state: 'absent' # Remove assignment
|
||||
- name: 'user admins'
|
||||
orgId: 1
|
||||
roles:
|
||||
- name: 'fixed:users:writer'
|
||||
global: true
|
||||
- name: 'custom:users:writer'
|
||||
global: true
|
||||
```
|
||||
|
||||
## Assign a custom role to a basic role using the HTTP API
|
||||
|
||||
As an alternative to assigning roles using the role picker or provisioning, you can use the Grafana HTTP API to assign fixed and custom roles to users and teams. For more information about the HTTP API, refer to the [RBAC HTTP API documentation]({{< relref "../../http_api/access_control.md#create-a-basic-role-assignment" >}}).
|
||||
|
||||
The following example shows you how to assign a custom role to a basic role using the HTTP API.
|
||||
|
||||
**Example request**
|
||||
|
||||
```
|
||||
curl --location --request POST '<grafana_url>/api/access-control/builtin-roles' \
|
||||
--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"roleUid": "jZrmlLCkGksdka",
|
||||
"builtinRole": "Viewer",
|
||||
"global": true
|
||||
}'
|
||||
```
|
||||
|
||||
**Example response**
|
||||
|
||||
```
|
||||
{
|
||||
"message": "Built-in role grant added"
|
||||
}
|
||||
```
|
||||
> **Note**: The roles don't have to be defined in the provisioning configuration files to be revoked. If roles exist in the database, they can be revoked.
|
||||
|
||||
@ -60,7 +60,7 @@ The following list contains role-based access control actions.
|
||||
| `datasources:query` | `datasources:*`<br>`datasources:uid:*` | Query data sources. |
|
||||
| `datasources:read` | `datasources:*`<br>`datasources:uid:*` | List data sources. |
|
||||
| `datasources:write` | `datasources:*`<br>`datasources:uid:*` | Update data sources. |
|
||||
| `folers.permissions:read` | `folders:*`<br>`folders:uid:*` | Read permissions for one or more folders. |
|
||||
| `folders.permissions:read` | `folders:*`<br>`folders:uid:*` | Read permissions for one or more folders. |
|
||||
| `folders.permissions:write` | `folders:*`<br>`folders:uid:*` | Update permissions for one or more folders. |
|
||||
| `folders:create` | n/a | Create folders. |
|
||||
| `folders:delete` | `folders:*`<br>`folders:uid:*` | Delete one or more folders. |
|
||||
@ -94,13 +94,11 @@ The following list contains role-based access control actions.
|
||||
| `reports:delete` | `reports:*` <br> `reports:id:*` | Delete reports. |
|
||||
| `reports:read` | `reports:*` | List all available reports or get a specific report. |
|
||||
| `reports:send` | `reports:*` | Send a report email. |
|
||||
| `roles.builtin:add` | `permissions:type:delegate` | Create a built-in role assignment. |
|
||||
| `roles.builtin:list` | `roles:*` | List built-in role assignments. |
|
||||
| `roles.builtin:remove` | `permissions:type:delegate` | Delete a built-in role assignment. |
|
||||
| `roles:delete` | `permissions:type:delegate` | Delete a custom role. |
|
||||
| `roles:list` | `roles:*` | List available roles without permissions. |
|
||||
| `roles:read` | `roles:*` <br> `roles:uid:*` | Read a specific role with its permissions. |
|
||||
| `roles:write` | `permissions:type:delegate` | Create or update a custom role. |
|
||||
| `roles:write` | `permissions:type:escalate` | Reset basic roles to their default permissions. |
|
||||
| `server.stats:read` | n/a | Read Grafana instance statistics. |
|
||||
| `settings:read` | `settings:*`<br>`settings:auth.saml:*`<br>`settings:auth.saml:enabled` (property level) | Read the [Grafana configuration settings]({{< relref "../../administration/configuration/_index.md" >}}) |
|
||||
| `settings:write` | `settings:*`<br>`settings:auth.saml:*`<br>`settings:auth.saml:enabled` (property level) | Update any Grafana configuration settings that can be [updated at runtime]({{< relref "../../enterprise/settings-updates/_index.md" >}}). |
|
||||
@ -147,6 +145,7 @@ The following list contains role-based access control scopes.
|
||||
| `global.users:*` <br> `global.users:id:*` | Restrict an action to a set of global users. For example, `global.users:*` matches any user and `global.users:id:1` matches the user whose ID is `1`. |
|
||||
| `orgs:*` <br> `orgs:id:*` | Restrict an action to a set of organizations. For example, `orgs:*` matches any organization and `orgs:id:1` matches the organization whose ID is `1`. |
|
||||
| `permissions:type:delegate` | The scope is only applicable for roles associated with the Access Control itself and indicates that you can delegate your permissions only, or a subset of it, by creating a new role or making an assignment. |
|
||||
| `permissions:type:escalate` | The scope is required to trigger the reset of basic roles permissions. It indicates that users might acquire additional permissions they did not previously have. |
|
||||
| `provisioners:*` | Restrict an action to a set of provisioners. For example, `provisioners:*` matches any provisioner, and `provisioners:accesscontrol` matches the role-based access control [provisioner]({{< relref "./custom-role-actions-scopes" >}}). |
|
||||
| `reports:*` <br> `reports:id:*` | Restrict an action to a set of reports. For example, `reports:*` matches any report and `reports:id:1` matches the report whose ID is `1`. |
|
||||
| `roles:*` <br> `roles:uid:*` | Restrict an action to a set of roles. For example, `roles:*` matches any role and `roles:uid:randomuid` matches only the role whose UID is `randomuid`. |
|
||||
|
||||
@ -63,7 +63,7 @@ This section describes how to enable RBAC by setting a feature flag or adding an
|
||||
|
||||
## Enable role provisioning
|
||||
|
||||
You can create, change or remove [Custom roles]({{< relref "./manage-rbac-roles.md#create-custom-roles-using-provisioning" >}}) and create or remove [basic role assignments]({{< relref "./assign-rbac-roles.md#assign-a-fixed-role-to-a-basic-role-using-provisioning" >}}), by adding one or more YAML configuration files in the `provisioning/access-control/` directory.
|
||||
You can create, change, or remove [custom roles]({{< relref "./manage-rbac-roles.md#create-custom-roles-using-provisioning" >}}) and update [basic roles]({{< relref "./manage-rbac-roles.md#update-basic-role-permissions" >}}), by adding one or more YAML configuration files in the `provisioning/access-control/` directory.
|
||||
|
||||
If you choose to use provisioning to assign and manage role, you must first enable it.
|
||||
|
||||
|
||||
@ -14,82 +14,25 @@ weight: 50
|
||||
|
||||
This section includes instructions for how to view permissions associated with roles, create custom roles, and update and delete roles.
|
||||
|
||||
## View basic role assignments using the HTTP API
|
||||
|
||||
You can use the [RBAC HTTP API]({{< relref "../../http_api/access_control.md#get-all-built-in-role-assignments" >}}) to see all available basic role assignments.
|
||||
The response contains a mapping between one of the organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin` to the custom or fixed roles.
|
||||
|
||||
**Before you begin:**
|
||||
|
||||
- [Enable role-based access control]({{< relref "./enable-rbac-and-provisioning#enable-rback" >}}).
|
||||
|
||||
The following example includes the base64 username:password Basic Authorization. You cannot use authorization tokens in the request.
|
||||
|
||||
**Example request**
|
||||
|
||||
```
|
||||
curl --location --request GET '<grafana_url>/api/access-control/builtin-roles' --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ='
|
||||
```
|
||||
|
||||
**Example response**
|
||||
|
||||
```
|
||||
{
|
||||
"Admin": [
|
||||
...
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "qQui_LCMk",
|
||||
"name": "fixed:users:org:writer",
|
||||
"displayName": "Users Organization writer",
|
||||
"description": "Within a single organization, add a user, invite a user, read information about a user and their role, remove a user from that organization, or change the role of a user.",
|
||||
"global": true,
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
{
|
||||
"version": 1,
|
||||
"uid": "Kz9m_YjGz",
|
||||
"name": "fixed:reports:writer",
|
||||
"displayName": "Report writer",
|
||||
"description": "Create, read, update, or delete all reports and shared report settings.",
|
||||
"global": true,
|
||||
"updated": "2021-05-13T16:24:26+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
}
|
||||
...
|
||||
],
|
||||
"Grafana Admin": [
|
||||
...
|
||||
{
|
||||
"version": 2,
|
||||
"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-17T20:49:18+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "ajum_YjGk",
|
||||
"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-17T20:49:17+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### List permissions associated with roles
|
||||
|
||||
Use a `GET` command to see the actions and scopes associated with a role. For more information about seeing a list of permissions for each role, refer to [Get a role]({{< relref "../../http_api/access_control.md#get-a-role" >}}).
|
||||
|
||||
<span id="basic-role-uid-mapping">To see the permissions associated with basic roles, refer to the following basic role UIDs</span>:
|
||||
|
||||
| Basic role | UID |
|
||||
| --------------- | --------------------- |
|
||||
| `Viewer` | `basic_viewer` |
|
||||
| `Editor` | `basic_editor` |
|
||||
| `Admin` | `basic_admin` |
|
||||
| `Grafana Admin` | `basic_grafana_admin` |
|
||||
|
||||
**Example request**
|
||||
|
||||
```
|
||||
@ -162,18 +105,21 @@ File-based provisioning is one method you can use to create custom roles.
|
||||
|
||||
1. Refer to the following table to add attributes and values.
|
||||
|
||||
| Attribute | Description |
|
||||
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `name` | A human-friendly identifier for the role that helps administrators understand the purpose of a role. `name` is required and cannot be longer than 190 characters. We recommend that you use ASCII characters. Role names must be unique within an organization. |
|
||||
| `Role display name` | Human-friendly text that is displayed in the UI. Role display name cannot be longer than 190 ASCII-based characters. For fixed roles, the display name is shown as specified. If you do not set a display name the display name replaces a `:` (a colon) with ` ` (a space). |
|
||||
| `Display name` | A human-friendly identifier that appears in the role picker UI. `Display name` helps the user to understand the purpose of the role. |
|
||||
| `Group` | Organizes roles in the role picker. |
|
||||
| `version` | A positive integer that defines the current version of the role. When you update a role, you can either omit the version field to increment the previous value by 1, or set a new version which must be larger than the previous version. |
|
||||
| `permissions` | Provides users access to Grafana resources. For a list of permissions, refer to [RBAC permissions actions and scopes]({{< relref "./rbac-fixed-basic-role-definitions.md" >}}). If you do not know which permissions to assign, you can create and assign roles without any permissions as a placeholder. |
|
||||
| `Role UID` | A unique identifier associated with the role. The UID enables you to change or delete the role. You can either generate a UID yourself, or let Grafana generate one for you. You cannot use the same UID within the same Grafana instance. |
|
||||
| `orgId` | Identifies the organization to which the role belongs. If you do not specify `orgId`, the `orgId` is inherited from `role`. For global roles, the default `orgId` is used. `orgId` in the `role` and in the assignment must be the same for non-global roles. The [default org ID]({{< relref "../../administration/configuration#auto_assign_org_id" >}}) is used if you do not specify `orgId`. |
|
||||
| `global` | Global roles are not associated with any specific organization, which means that you can reuse them across all organizations. This setting overrides `orgId`. |
|
||||
| `hidden` | Hidden roles do not appear in the role picker. |
|
||||
| Attribute | Description |
|
||||
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `name` | A human-friendly identifier for the role that helps administrators understand the purpose of a role. `name` is required and cannot be longer than 190 characters. We recommend that you use ASCII characters. Role names must be unique within an organization. |
|
||||
| `uid` | A unique identifier associated with the role. The UID enables you to change or delete the role. You can either generate a UID yourself, or let Grafana generate one for you. You cannot use the same UID within the same Grafana instance. |
|
||||
| `orgId` | Identifies the organization to which the role belongs. The [default org ID]({{< relref "../../administration/configuration#auto_assign_org_id" >}}) is used if you do not specify `orgId`. |
|
||||
| `global` | Global roles are not associated with any specific organization, which means that you can reuse them across all organizations. This setting overrides `orgId`. |
|
||||
| `displayName` | Human-friendly text that is displayed in the UI. Role display name cannot be longer than 190 ASCII-based characters. For fixed roles, the display name is shown as specified. If you do not set a display name the display name replaces `':'` (a colon) with `' '` (a space). |
|
||||
| `description` | Human-friendly text that describes the permissions a role provides. |
|
||||
| `group` | Organizes roles in the role picker. |
|
||||
| `version` | A positive integer that defines the current version of the role, which prevents overwriting newer changes. |
|
||||
| `hidden` | Hidden roles do not appear in the role picker. |
|
||||
| `state` | State of the role. Defaults to `present`, but if set to `absent` the role will be removed. |
|
||||
| `force` | Can be used in addition to state `absent`, to force the removal of a role and all its assignments. |
|
||||
| `from` | An optional list of roles from which you want to copy permissions. |
|
||||
| `permissions` | Provides users access to Grafana resources. For a list of permissions, refer to [RBAC permissions actions and scopes]({{< relref "./rbac-fixed-basic-role-definitions.md" >}}). If you do not know which permissions to assign, you can create and assign roles without any permissions as a placeholder. Using the `from` attribute, you can specify additional permissions or permissions to remove by adding a `state` to your permission list. |
|
||||
|
||||
1. Reload the provisioning configuration file.
|
||||
|
||||
@ -183,43 +129,65 @@ The following example creates a local role:
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
apiVersion: 2
|
||||
|
||||
# Roles to insert into the database, or roles to update in the database
|
||||
roles:
|
||||
- name: custom:users:editor
|
||||
description: 'This role allows users to list, create, or update other users within the organization.'
|
||||
- name: custom:users:writer
|
||||
description: 'List, create, or update other users.'
|
||||
version: 1
|
||||
orgId: 1
|
||||
permissions:
|
||||
- action: 'users:read'
|
||||
scope: 'users:*'
|
||||
scope: 'global.users:*'
|
||||
- action: 'users:write'
|
||||
scope: 'users:*'
|
||||
scope: 'global.users:*'
|
||||
- action: 'users:create'
|
||||
scope: 'users:*'
|
||||
```
|
||||
|
||||
The following example creates a hidden global role. The `global:true` option creates a global role, and the `hidden:true` option hides the role from the role picker.
|
||||
The following example creates a hidden global role. The `global: true` option creates a global role, and the `hidden: true` option hides the role from the role picker.
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
apiVersion: 2
|
||||
|
||||
# Roles to insert into the database, or roles to update in the database
|
||||
roles:
|
||||
- name: custom:users:editor
|
||||
description: 'This role allows users to list, create, or update other users within the organization.'
|
||||
- name: custom:users:writer
|
||||
description: 'List, create, or update other users.'
|
||||
version: 1
|
||||
global: true
|
||||
hidden: true
|
||||
permissions:
|
||||
- action: 'users:read'
|
||||
scope: 'users:*'
|
||||
scope: 'global.users:*'
|
||||
- action: 'users:write'
|
||||
scope: 'users:*'
|
||||
scope: 'global.users:*'
|
||||
- action: 'users:create'
|
||||
```
|
||||
|
||||
The following example creates a global role based on other fixed roles. The `from` option contains the roles from which we want to
|
||||
copy permissions. The permission `state: absent` option can be used to specify permissions to exclude from the copy.
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 2
|
||||
|
||||
roles:
|
||||
- name: custom:org.users:writer
|
||||
description: 'List and remove other users from the organization.'
|
||||
version: 1
|
||||
global: true
|
||||
from:
|
||||
- name: 'fixed:org.users:reader'
|
||||
global: true
|
||||
- name: 'fixed:org.users:writer'
|
||||
global: true
|
||||
permissions:
|
||||
- action: 'org.users.role:update'
|
||||
scope: 'users:*'
|
||||
state: 'absent'
|
||||
- action: 'org.users:add'
|
||||
scope: 'users:*'
|
||||
state: 'absent'
|
||||
```
|
||||
|
||||
### Create custom roles using the HTTP API
|
||||
@ -277,46 +245,101 @@ curl --location --request POST '<grafana_url>/api/access-control/roles/' \
|
||||
|
||||
Refer to the [RBAC HTTP API]({{< relref "../../http_api/access_control.md#create-a-new-custom-role" >}}) for more details.
|
||||
|
||||
## Remove a fixed role from a basic role
|
||||
## Update basic role permissions
|
||||
|
||||
If the basic role definitions that are available by default do not meet your requirements, you can change them by removing fixed role permissions from basic roles.
|
||||
If the default basic role definitions do not meet your requirements, you can change their permissions.
|
||||
|
||||
</br>
|
||||
|
||||
**Before you begin:**
|
||||
|
||||
- Determine the fixed roles you want to remove from a basic role. For more information about the fixed roles associated with basic roles, refer to [RBAC role definitions]({{< relref "./rbac-fixed-basic-role-definitions#basic-role-assignments" >}}).
|
||||
- Determine the permissions you want to add or remove from a basic role. For more information about the permissions associated with basic roles, refer to [RBAC role definitions]({{< relref "./rbac-fixed-basic-role-definitions#basic-role-assignments" >}}).
|
||||
|
||||
</br>
|
||||
|
||||
**To remove a fixed role from a basic role:**
|
||||
**To change permissions from a basic role:**
|
||||
|
||||
1. Open the YAML configuration file and locate the `removeDefaultAssignments` section.
|
||||
1. Open the YAML configuration file and locate the `roles` section.
|
||||
|
||||
1. Refer to the following table to add attributes and values.
|
||||
|
||||
| Attribute | Description |
|
||||
| ------------- | --------------------------------- |
|
||||
| `builtInRole` | Enter the name of the basic role. |
|
||||
| `fixedRole` | Enter the name of the fixed role. |
|
||||
| Attribute | Description |
|
||||
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `name` | The name of the basic role you want to update. You can specify a `uid` instead of a role name. The role `name` or the `uid` are required. |
|
||||
| `orgId` | Identifies the organization to which the role belongs. `global` can be used instead to specify it's a global role. |
|
||||
| `version` | Identifies the version of the role, which prevents overwriting newer changes. |
|
||||
| `from` | List of roles from which to copy permissions. |
|
||||
| `permissions > state` | The state of the permission. You can set it to `absent` to ensure it exclusion from the copy list. |
|
||||
|
||||
1. Reload the provisioning configuration file.
|
||||
|
||||
For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}).
|
||||
|
||||
The following example removes the `fixed:permissions:admin` from the `Grafana Admin` basic role.
|
||||
The following example modifies the `Grafana Admin` basic role permissions.
|
||||
|
||||
- Permissions to list, grant, and revoke roles to teams are removed.
|
||||
- Permission to read and write Grafana folders is added.
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
apiVersion: 2
|
||||
|
||||
# list of default basic role assignments that should be removed
|
||||
removeDefaultAssignments:
|
||||
- builtInRole: 'Grafana Admin'
|
||||
fixedRole: 'fixed:permissions:admin'
|
||||
roles:
|
||||
- name: 'basic:grafana_admin'
|
||||
global: true
|
||||
version: 3
|
||||
from:
|
||||
- name: 'basic:grafana_admin'
|
||||
global: true
|
||||
permissions:
|
||||
# Permissions to remove
|
||||
- action: 'teams.roles:list'
|
||||
scope: 'teams:*'
|
||||
state: 'absent'
|
||||
- action: 'teams.roles:remove'
|
||||
scope: 'permissions:type:delegate'
|
||||
state: 'absent'
|
||||
- action: 'teams.roles:add'
|
||||
scope: 'permissions:type:delegate'
|
||||
state: 'absent'
|
||||
# Permissions to add
|
||||
- action: 'folders:read'
|
||||
scope: 'folder:*'
|
||||
- action: 'folders:write'
|
||||
scope: 'folder:*'
|
||||
```
|
||||
|
||||
You can also remove fixed roles from basic roles using the API. Refer to the [RBAC HTTP API]({{< relref "../../http_api/access_control.md#remove-a-built-in-role-assignment" >}}) for more details.
|
||||
> **Note**: You can add multiple `fixed`, `basic` or `custom` roles to the `from` section. Their permissions will be copied and added to the basic role.
|
||||
> <br/> **Note**: Make sure to **increment** the role version for the changes to be accounted for.
|
||||
|
||||
You can also change basic roles' permissions using the API. Refer to the [RBAC HTTP API]({{< relref "../../http_api/access_control.md#update-a-role" >}}) for more details.
|
||||
|
||||
## Reset basic roles to their default
|
||||
|
||||
This section describes how to reset the basic roles to their default:
|
||||
|
||||
1. Open the YAML configuration file and locate the `roles` section.
|
||||
|
||||
1. Grant the `action: "roles:write", scope: "permissions:type:escalate` permission to `Grafana Admin`.
|
||||
|
||||
```yaml
|
||||
apiVersion: 2
|
||||
roles:
|
||||
- name: 'basic:grafana_admin'
|
||||
global: true
|
||||
version: 3
|
||||
from:
|
||||
- name: 'basic:grafana_admin'
|
||||
global: true
|
||||
permissions:
|
||||
# Permission allowing to reset basic roles
|
||||
- action: 'roles:write'
|
||||
scope: 'permissions:type:escalate'
|
||||
```
|
||||
|
||||
> **Note**: This permission has not been granted to any basic roles by default, because users could acquire more permissions than they previously had through the basic role permissions reset.
|
||||
|
||||
1. As a `Grafana Admin`, call the API endpoint to reset the basic roles to their default. Refer to the [RBAC HTTP API]({{< relref "../../http_api/access_control.md#reset-basic-roles-to-their-default" >}}) for more details.
|
||||
|
||||
## Delete a custom role using Grafana provisioning
|
||||
|
||||
@ -335,15 +358,16 @@ Delete a custom role when you no longer need it. When you delete a custom role,
|
||||
|
||||
**To delete a custom role:**
|
||||
|
||||
1. Open the YAML configuration file and locate the `deleteRoles` section.
|
||||
1. Open the YAML configuration file and locate the `roles` section.
|
||||
|
||||
1. Refer to the following table to add attributes and values.
|
||||
|
||||
| Attribute | Description |
|
||||
| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `name` | The name of the custom role you want to delete. You can add a `uid` instead of a role name. The role `name` or the `uid` are required. |
|
||||
| `orgId` | Identifies the organization to which the role belongs. |
|
||||
| `force` | Sets the force parameter. |
|
||||
| Attribute | Description |
|
||||
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `name` | The name of the custom role you want to delete. You can specify a `uid` instead of a role name. The role `name` or the `uid` are required. |
|
||||
| `orgId` | Identifies the organization to which the role belongs. |
|
||||
| `state` | The state of the role set to `absent` to trigger its removal. |
|
||||
| `force` | Sets the force parameter. |
|
||||
|
||||
1. Reload the provisioning configuration file.
|
||||
|
||||
@ -353,12 +377,12 @@ The following example deletes a custom role:
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
apiVersion: 2
|
||||
|
||||
# list of roles that should be deleted
|
||||
deleteRoles:
|
||||
- name: custom:reports:editor
|
||||
roles:
|
||||
- name: 'custom:reports:editor'
|
||||
orgId: 1
|
||||
state: 'absent'
|
||||
force: true
|
||||
```
|
||||
|
||||
|
||||
@ -14,13 +14,13 @@ Your rollout strategy should help you answer the following questions:
|
||||
|
||||
- Should I assign basic roles to users, or should I assign fixed roles or custom roles to users?
|
||||
- When should I create custom roles?
|
||||
- To which entities should I apply fixed and custom roles? Should I apply them to users, teams, or to basic roles?
|
||||
- To which entities should I apply fixed and custom roles? Should I apply them to users, teams? Should I modify the basic roles permissions instead?
|
||||
- How do I roll out permissions in a way that makes them easy to manage?
|
||||
- Which approach should I use when assigning roles? Should I use the Grafana UI, provisioning, or the API?
|
||||
|
||||
## Review basic role and fixed role definitions
|
||||
|
||||
As a first step in determining your permissions rollout strategy, we recommend that you become familiar with basic role and fixed role definitions. In addition to assigning fixed roles to any user and team, you can also assign fixed roles to basic roles, which changes what a Viewer, Editor, or Admin can do. This flexibility means that there are many combinations of role assignments for you to consider. If you have a large number of Grafana users and teams, we recommend that you make a list of which fixed roles you might want to use.
|
||||
As a first step in determining your permissions rollout strategy, we recommend that you become familiar with basic role and fixed role definitions. In addition to assigning fixed roles to any user and team, you can also modify basic roles permissions, which changes what a Viewer, Editor, or Admin can do. This flexibility means that there are many combinations of role assignments for you to consider. If you have a large number of Grafana users and teams, we recommend that you make a list of which fixed roles you might want to use.
|
||||
|
||||
To learn more about basic roles and fixed roles, refer to the following documentation:
|
||||
|
||||
@ -51,15 +51,15 @@ For example:
|
||||
|
||||
For more information about team sync, refer to [Team sync]({{< relref "../team-sync.md" >}}).
|
||||
|
||||
3. Within Grafana, assign RBAC permissions to roles and teams.
|
||||
3. Within Grafana, assign RBAC permissions to users and teams.
|
||||
|
||||
## When to modify basic roles or create custom roles
|
||||
|
||||
Consider the following guidelines when you determine if you should modify basic roles or create custom roles.
|
||||
|
||||
- **Modify basic roles** when Grafana's definitions of what viewers, editors, and admins can do does not match your definition of these roles. You can add or remove fixed roles from any basic role.
|
||||
- **Modify basic roles** when Grafana's definitions of what viewers, editors, and admins can do does not match your definition of these roles. You can add or remove permissions from any basic role.
|
||||
|
||||
> **Note:** Changes that you make to basic roles impact the role definition for all [organizations]({{< relref "../../administration/manage-organizations/_index.md" >}}) in the Grafana instance. For example, when you assign the `fixed:users:writer` role to the viewer basic role, all viewers in any org in the Grafana instance can create users within that org.
|
||||
> **Note:** Changes that you make to basic roles impact the role definition for all [organizations]({{< relref "../../administration/manage-organizations/_index.md" >}}) in the Grafana instance. For example, when you add the `fixed:users:writer` role's permissions to the viewer basic role, all viewers in any org in the Grafana instance can create users within that org.
|
||||
|
||||
- **Create custom roles** when fixed role definitions don't meet you permissions requirements. For example, the `fixed:dashboards:writer` role allows users to delete dashboards. If you want some users or teams to be able to create and update but not delete dashboards, you can create a custom role with a name like `custom:dashboards:creator` that lacks the `dashboards:delete` permission.
|
||||
|
||||
@ -87,14 +87,14 @@ We've compiled the following permissions rollout scenarios based on current Graf
|
||||
|
||||
### Limit viewer, editor, or admin permissions
|
||||
|
||||
1. Review the list of fixed roles associated with the basic role.
|
||||
1. [Remove the fixed roles from the basic role]({{< relref "manage-rbac-roles.md#remove-a-fixed-role-from-a-basic-role" >}}).
|
||||
1. Review the list of permissions associated with the basic role.
|
||||
1. [Change the permissions of the basic role]({{< relref "manage-rbac-roles.md#update-basic-role-permissions" >}}).
|
||||
|
||||
### Allow only members of one team to manage Alerts
|
||||
|
||||
1. Remove all fixed roles starting with `fixed:alerts` from the Viewer, Editor, and Admin basic roles.
|
||||
2. Create an `Alert Managers` team, and assign that team all applicable Alerting fixed roles.
|
||||
3. Add users to the `Alert Managers` team.
|
||||
1. Create an `Alert Managers` team, and assign that team all applicable Alerting fixed roles.
|
||||
1. Add users to the `Alert Managers` team.
|
||||
1. Remove all permissions with actions prefixed with `alert.` from the Viewer, Editor, and Admin basic roles.
|
||||
|
||||
### Provide dashboards to users in two or more geographies
|
||||
|
||||
@ -148,28 +148,96 @@ curl --location --request POST '<grafana_url>/api/access-control/roles/' \
|
||||
|
||||
### Enable an editor to create custom roles
|
||||
|
||||
By default, the Grafana Server Admin is the only user who can create and manage custom roles. If you want your users to do the same, you have two options:
|
||||
By default, only a Grafana Server Admin can create and manage custom roles. If you want your `Editors` to do the same, [update the `Editor` basic role permissions]({{< ref "./manage-rbac-roles.md#update-basic-role-permissions" >}}). There are two ways to achieve this:
|
||||
|
||||
1. Create a basic role assignment and map `fixed:permissions:admin:edit` and `fixed:permissions:admin:read` fixed roles to the `Editor` basic role.
|
||||
1. [Create a custom role]({{< ref "./manage-rbac-roles#create-custom-roles" >}}) with `roles.builtin:add` and `roles:write` permissions, then create a basic role assignment for `Editor` organization role.
|
||||
- Add the `fixed:roles:writer` role permissions to the `basic:editor` role using the `role > from` list of your provisioning file:
|
||||
|
||||
> **Note:** any user or service account with the ability to modify roles can only create, update or delete roles with permissions they themselves have been granted. For example, a user with the `Editor` role would be able to create and manage roles only with the permissions they have, or with a subset of them.
|
||||
```yaml
|
||||
apiVersion: 2
|
||||
|
||||
roles:
|
||||
- name: 'basic:editor'
|
||||
global: true
|
||||
version: 3
|
||||
from:
|
||||
- name: 'basic:editor'
|
||||
global: true
|
||||
- name: 'fixed:roles:writer'
|
||||
global: true
|
||||
```
|
||||
|
||||
- Or add the following permissions to the `basic:editor` role, using provisioning or the [RBAC HTTP API]({{< relref "../../http_api/access_control.md#update-a-role" >}}):
|
||||
|
||||
| action | scope |
|
||||
| -------------- | --------------------------- |
|
||||
| `roles:list` | `roles:*` |
|
||||
| `roles:read` | `roles:*` |
|
||||
| `roles:write` | `permissions:type:delegate` |
|
||||
| `roles:delete` | `permissions:type:delegate` |
|
||||
|
||||
> **Note:** Any user or service account with the ability to modify roles can only create, update, or delete roles with permissions they have been granted. For example, a user with the `Editor` role would be able to create and manage roles only with the permissions they have or with a subset of them.
|
||||
|
||||
### Enable viewers to create reports
|
||||
|
||||
This section describes two ways that you can enable viewers to create reports.
|
||||
If you want your `Viewers` to create reports, [update the `Viewer` basic role permissions]({{< ref "./manage-rbac-roles.md#update-basic-role-permissions" >}}). There are two ways to achieve this:
|
||||
|
||||
- Assign the `fixed:reporting:admin:edit` role to the `Viewer` basic role. For more information about assigning a fixed role to a basic role, refer to [Assign a fixed role to a basic role using provisioning]({{< relref "./assign-rbac-roles#assign-a-fixed-role-to-a-basic-role-using-provisioning" >}}).
|
||||
- Add the `fixed:reports:writer` role permissions to the `basic:viewer` role using the `role > from` list of your provisioning file:
|
||||
|
||||
> **Note:** The `fixed:reporting:admin:edit` role assigns more permissions than just creating reports. For more information about fixed role permission assignments, refer to [Fixed role definitions]({{< relref "./rbac-fixed-basic-role-definitions#fixed-role-definitions" >}}).
|
||||
```yaml
|
||||
apiVersion: 2
|
||||
|
||||
- [Create a custom role]({{< ref "./manage-rbac-roles#create-custom-roles" >}}) that includes the `reports.admin:write` permission, and add the custom role to the `Viewer` basic role.
|
||||
- For more information about assigning a custom role to a basic role, refer to [Assign a custom role to a basic role using provisioning]({{< relref "./assign-rbac-roles#assign-a-custom-role-to-a-basic-role-using-provisioning" >}}) or [Assign a custom role to a basic role using the HTTP API]({{< relref "./assign-rbac-roles#assign-a-custom-role-to-a-basic-role-using-the-http-api" >}}).
|
||||
roles:
|
||||
- name: 'basic:viewer'
|
||||
global: true
|
||||
version: 3
|
||||
from:
|
||||
- name: 'basic:viewer'
|
||||
global: true
|
||||
- name: 'fixed:reports:writer'
|
||||
global: true
|
||||
```
|
||||
|
||||
> **Note:** The `fixed:reports:writer` role assigns more permissions than just creating reports. For more information about fixed role permission assignments, refer to [Fixed role definitions]({{< relref "./rbac-fixed-basic-role-definitions#fixed-role-definitions" >}}).
|
||||
|
||||
- Add the following permissions to the `basic:viewer` role, using provisioning or the [RBAC HTTP API]({{< relref "../../http_api/access_control.md#update-a-role" >}}):
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------------- | ------------------------------- |
|
||||
| `reports.admin:create` | n/a |
|
||||
| `reports.admin:write` | `reports:*` <br> `reports:id:*` |
|
||||
| `reports:read` | `reports:*` |
|
||||
| `reports:send` | `reports:*` |
|
||||
|
||||
### Prevent a Grafana Admin from creating and inviting users
|
||||
|
||||
This topic describes how to remove the `users:create` permissions from the Grafana Admin role, which prevents the Grafana Admin from creating users and inviting them to join an organization.
|
||||
To prevent a Grafana Admin from creating users and inviting them to join an organization, you must [update a basic role permissions]({{< ref "./manage-rbac-roles.md#update-basic-role-permissions" >}}).
|
||||
The permissions to remove are:
|
||||
|
||||
1. [View basic role assignments]({{< relref "./rbac-fixed-basic-role-definitions#basic-role-assignments" >}}) to determine which basic role assignments are available.
|
||||
1. To determine which role provides `users:create` permission, refer to [Fixed role definitions]({{< relref "./rbac-fixed-basic-role-definitions#fixed-role-definitions" >}}).
|
||||
1. Use the [Role-based access control HTTP API]({{< relref "../../http_api/access_control.md" >}}) or Grafana provisioning to [Remove a fixed role from a basic role]({{< relref "./manage-rbac-roles#remove-a-fixed-role-from-a-basic-role" >}}).
|
||||
| Action | Scope |
|
||||
| --------------- | --------- |
|
||||
| `users:create` | |
|
||||
| `org.users:add` | `users:*` |
|
||||
|
||||
There are two ways to achieve this:
|
||||
|
||||
- Use the `role > from` list and `permission > state` option of your provisioning file:
|
||||
|
||||
```yaml
|
||||
apiVersion: 2
|
||||
|
||||
roles:
|
||||
- name: 'basic:editor'
|
||||
global: true
|
||||
version: 3
|
||||
from:
|
||||
- name: 'basic:editor'
|
||||
global: true
|
||||
permissions:
|
||||
- action: 'users:create'
|
||||
state: 'absent'
|
||||
- action: 'org.users:add'
|
||||
scope: 'users:*'
|
||||
state: 'absent'
|
||||
```
|
||||
|
||||
- Or use [RBAC HTTP API]({{< relref "../../http_api/access_control.md#update-a-role" >}}).
|
||||
|
||||
@ -10,95 +10,81 @@ weight: 60
|
||||
|
||||
The following example shows a complete YAML configuration file that:
|
||||
|
||||
- Removes a default role assignment
|
||||
- Adds a default role assignment
|
||||
- Deletes custom roles
|
||||
- Adds custom roles to basic roles
|
||||
- Adds a custom role to a fixed role
|
||||
- Create custom roles
|
||||
- Delete custom roles
|
||||
- Update basic roles permissions
|
||||
- Assign roles to teams
|
||||
- Revoke assignments of roles to teams
|
||||
|
||||
## Example
|
||||
|
||||
```yaml
|
||||
---
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
apiVersion: 2
|
||||
|
||||
# list of default basic role assignments that should be removed
|
||||
removeDefaultAssignments:
|
||||
# <string>, must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
|
||||
- builtInRole: 'Grafana Admin'
|
||||
# <string>, must be one of the existing fixed roles
|
||||
fixedRole: 'fixed:permissions:admin'
|
||||
|
||||
# list of default basic role assignments that should be added back
|
||||
addDefaultAssignments:
|
||||
# <string>, must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
|
||||
- builtInRole: 'Admin'
|
||||
# <string>, must be one of the existing fixed roles
|
||||
fixedRole: 'fixed:reporting:admin:read'
|
||||
|
||||
# list of roles that should be deleted
|
||||
deleteRoles:
|
||||
# <string> name of the role you want to create. Required if no uid is set
|
||||
- name: 'custom:reports:editor'
|
||||
# <string> uid of the role. Required if no name
|
||||
uid: 'customreportseditor1'
|
||||
# <int> org id. will default to Grafana's default if not specified
|
||||
orgId: 1
|
||||
# <bool> force deletion revoking all grants of the role
|
||||
force: true
|
||||
- name: 'custom:global:reports:reader'
|
||||
uid: 'customglobalreportsreader1'
|
||||
# <bool> overwrite org id and removes a global role
|
||||
global: true
|
||||
force: true
|
||||
|
||||
# list of roles to insert/update depending on what is available in the database
|
||||
# <list> list of roles to insert/update/delete
|
||||
roles:
|
||||
# <string, required> name of the role you want to create. Required
|
||||
- name: 'custom:users:editor'
|
||||
# <string, required> name of the role you want to create or update. Required.
|
||||
- name: 'custom:users:writer'
|
||||
# <string> uid of the role. Has to be unique for all orgs.
|
||||
uid: customuserseditor1
|
||||
uid: customuserswriter1
|
||||
# <string> description of the role, informative purpose only.
|
||||
description: 'Role for our custom user editors'
|
||||
# <int> version of the role, Grafana will update the role when increased
|
||||
description: 'Create, read, write users'
|
||||
# <int> version of the role, Grafana will update the role when increased.
|
||||
version: 2
|
||||
# <int> org id. will default to Grafana's default if not specified
|
||||
# <int> org id. Defaults to Grafana's default if not specified.
|
||||
orgId: 1
|
||||
# <list> list of the permissions granted by this role
|
||||
# <list> list of the permissions granted by this role.
|
||||
permissions:
|
||||
# <string, required> action allowed
|
||||
# <string, required> action allowed.
|
||||
- action: 'users:read'
|
||||
#<string> scope it applies to
|
||||
#<string> scope it applies to.
|
||||
scope: 'users:*'
|
||||
- action: 'users:write'
|
||||
scope: 'users:*'
|
||||
- action: 'users:create'
|
||||
scope: 'users:*'
|
||||
# <list> list of basic roles the role should be assigned to
|
||||
builtInRoles:
|
||||
# <string, required> name of the basic role you want to assign the role to
|
||||
- name: 'Editor'
|
||||
# <int> org id. will default to the role org id
|
||||
orgId: 1
|
||||
- name: 'custom:global:users:reader'
|
||||
uid: 'customglobalusersreader1'
|
||||
description: 'Global Role for custom user readers'
|
||||
version: 1
|
||||
# <bool> overwrite org id and creates a global role
|
||||
# <bool> overwrite org id and creates a global role.
|
||||
global: true
|
||||
# <string> state of the role. Defaults to 'present'. If 'absent', role will be deleted.
|
||||
state: 'absent'
|
||||
# <bool> force deletion revoking all grants of the role.
|
||||
force: true
|
||||
- uid: 'basic_editor'
|
||||
version: 2
|
||||
global: true
|
||||
# <list> list of roles to copy permissions from.
|
||||
from:
|
||||
- uid: 'basic_editor'
|
||||
global: true
|
||||
- name: 'fixed:users:writer'
|
||||
global: true
|
||||
# <list> list of the permissions to add/remove on top of the copied ones.
|
||||
permissions:
|
||||
- action: 'users:read'
|
||||
scope: 'users:*'
|
||||
builtInRoles:
|
||||
- name: 'Viewer'
|
||||
- action: 'users:write'
|
||||
scope: 'users:*'
|
||||
# <string> state of the permission. Defaults to 'present'. If 'absent', the permission will be removed.
|
||||
state: absent
|
||||
|
||||
# <list> list role assignments to teams to create or remove.
|
||||
teams:
|
||||
# <string, required> name of the team you want to assign roles to. Required.
|
||||
- name: 'Users writers'
|
||||
# <int> org id. Will default to Grafana's default if not specified.
|
||||
orgId: 1
|
||||
# <list> list of roles to assign to the team
|
||||
roles:
|
||||
# <string> uid of the role you want to assign to the team.
|
||||
- uid: 'customuserswriter1'
|
||||
# <int> org id. Will default to Grafana's default if not specified.
|
||||
orgId: 1
|
||||
- name: 'Editor'
|
||||
# <bool> overwrite org id and assign role globally
|
||||
# <string> name of the role you want to assign to the team.
|
||||
- name: 'fixed:users:writer'
|
||||
# <bool> overwrite org id to specify the role is global.
|
||||
global: true
|
||||
- name: fixed:users:writer
|
||||
global: true
|
||||
# <list> list of teams the role should be assigned to
|
||||
teams:
|
||||
- name: 'user editors'
|
||||
orgId: 1
|
||||
# <string> state of the assignment. Defaults to 'present'. If 'absent', the assignment will be revoked.
|
||||
state: absent
|
||||
```
|
||||
|
||||
@ -64,8 +64,9 @@ The following tables list permissions associated with basic and fixed roles.
|
||||
| `fixed:provisioning:writer` | `provisioning:reload` | Reload provisioning. |
|
||||
| `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:roles:reader` | `roles:read`<br>`roles:list`<br>`teams.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, teams and built-in role assignments. |
|
||||
| `fixed:roles:writer` | All permissions from `fixed:roles:reader` and <br>`roles:write`<br>`roles:delete`<br>`teams.roles:add`<br>`teams.roles:remove`<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, teams and built-in role assignments. |
|
||||
| `fixed:roles:reader` | `roles:read`<br>`roles:list`<br>`teams.roles:list`<br>`users.roles:list`<br>`users.permissions:list` | Read all access control roles, roles and permissions assigned to users, teams. |
|
||||
| `fixed:roles:writer` | All permissions from `fixed:roles:reader` and <br>`roles:write`<br>`roles:delete`<br>`teams.roles:add`<br>`teams.roles:remove`<br>`users.roles:add`<br>`users.roles:remove` | Create, read, update, or delete all roles, assign or unassign roles to users, teams. |
|
||||
| `fixed:roles:resetter` | `roles:write` with scope `permissions:type:escalate` | Reset basic roles to their default. |
|
||||
| `fixed:settings:reader` | `settings:read` | Read Grafana instance settings. |
|
||||
| `fixed:settings:writer` | All permissions from `fixed:settings:reader` and<br>`settings:write` | Read and update Grafana instance settings. |
|
||||
| `fixed:stats:reader` | `server.stats:read` | Read Grafana instance statistics. |
|
||||
|
||||
@ -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 |
|
||||
|
||||
Loading…
Reference in New Issue
Block a user