mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Access control: Rename predefined roles to fixed roles (docs) (#34472)
This commit is contained in:
Emil Tullstedt
GitHub
parent
3064209cd5
commit
96da84ca49
@ -41,15 +41,15 @@ Note that it is only possibly to provision [organization local]({{< relref "./ro
|
||||
|
||||
## Manage default built-in role assignments
|
||||
|
||||
During the startup, Grafana creates [default built-in role assignments]({{< relref "./roles#default-built-in-role-assignments" >}}) with [predefined roles]({{< relref "./roles#predefined-roles" >}}). You can remove and add back later those assignments by using provisioning.
|
||||
During the startup, Grafana creates [default built-in role assignments]({{< relref "./roles#default-built-in-role-assignments" >}}) with [fixed roles]({{< relref "./roles#fixed-roles" >}}). You can remove and add back later those assignments by using provisioning.
|
||||
|
||||
### Remove default assignment
|
||||
|
||||
To remove default built-in role assignment, you can use `removeDefaultAssignments` element in the configuration file. You would need to provide built-in role name and predefined role name.
|
||||
To remove default built-in role assignment, you can use `removeDefaultAssignments` element in the configuration file. You would need to provide built-in role name and fixed role name.
|
||||
|
||||
### Add back default assignment
|
||||
|
||||
To add back default built-in role assignment, you can use `addDefaultAssignments` element in the configuration file. You would need to provide built-in role name and predefined role name.
|
||||
To add back default built-in role assignment, you can use `addDefaultAssignments` element in the configuration file. You would need to provide built-in role name and fixed role name.
|
||||
|
||||
## Example of a role configuration file
|
||||
|
||||
@ -61,15 +61,15 @@ apiVersion: 1
|
||||
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 predefined roles
|
||||
predefinedRole: "grafana:roles:permissions: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 predefined roles
|
||||
predefinedRole: "grafana:roles:reporting:admin:read"
|
||||
# <string>, must be one of the existing fixed roles
|
||||
fixedRole: "fixed:reporting:admin:read"
|
||||
|
||||
# list of roles that should be deleted
|
||||
deleteRoles:
|
||||
@ -127,7 +127,7 @@ A basic set of validation rules are applied to the input `yaml` files.
|
||||
### Roles
|
||||
|
||||
- `name` must not be empty
|
||||
- `name` must not have `grafana:roles:` prefix.
|
||||
- `name` must not have `fixed:` prefix.
|
||||
|
||||
### Built-in role assignments
|
||||
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
+++
|
||||
title = "Roles"
|
||||
description = "Understand roles in fine-grained access control"
|
||||
keywords = ["grafana", "fine-grained-access-control", "roles", "predefined-roles", "built-in-role-assignments", "permissions", "enterprise"]
|
||||
keywords = ["grafana", "fine-grained-access-control", "roles", "fixed-roles", "built-in-role-assignments", "permissions", "enterprise"]
|
||||
weight = 105
|
||||
+++
|
||||
|
||||
@ -10,7 +10,7 @@ weight = 105
|
||||
A role represents set of permissions that allow you to perform specific actions on Grafana resources. Refer to [Permissions]({{< relref "./permissions.md" >}}) to understand how permissions work.
|
||||
|
||||
There are two types of roles:
|
||||
- [Predefined roles]({{< relref "./roles.md#predefined-roles" >}}), which provide granular access for specific resources within Grafana and are managed by the Grafana itself.
|
||||
- [Fixed roles]({{< relref "./roles.md#fixed-roles" >}}), which provide granular access for specific resources within Grafana and are managed by the Grafana itself.
|
||||
- [Custom roles]({{< relref "./roles.md#custom-roles.md" >}}), which provide granular access based on the user specified set of permissions.
|
||||
|
||||
You can use [Fine-grained access control API]({{< relref "../../http_api/access_control.md" >}}) to list available roles and permissions.
|
||||
@ -19,27 +19,27 @@ You can use [Fine-grained access control API]({{< relref "../../http_api/access_
|
||||
|
||||
A role can be either _global_ or _organization local_. _Global_ roles are not mapped to any specific organization and can be reused across multiple organizations, whereas _organization local_ roles are only available for that specific organization.
|
||||
|
||||
## Predefined roles
|
||||
## Fixed roles
|
||||
|
||||
Predefined roles provide convenience and guarantee of consistent behaviour by combining relevant [permissions]({{< relref "./permissions.md" >}}) together. Predefined roles are created and updated by the Grafana, during the startup.
|
||||
There are few basic rules for predefined roles:
|
||||
Fixed roles provide convenience and guarantee of consistent behaviour by combining relevant [permissions]({{< relref "./permissions.md" >}}) together. Fixed roles are created and updated by Grafana during startup.
|
||||
There are few basic rules for fixed roles:
|
||||
|
||||
- All predefined roles are _global_ by default
|
||||
- All predefined roles have a `grafana:roles:` prefix.
|
||||
- You can’t change or delete a predefined role.
|
||||
- All fixed roles are _global_.
|
||||
- All fixed roles have a `fixed:` prefix.
|
||||
- You can’t change or delete a fixed role.
|
||||
|
||||
Role name | Permissions | Description
|
||||
--- | --- | ---
|
||||
grafana:roles:permissions:admin:read | roles:read<br>roles:list<br>roles.builtin:list | Allows to list and get available roles and built-in role assignments.
|
||||
grafana:roles:permissions:admin:edit | All permissions from `grafana:roles:permissions:admin:read` and <br>roles:write<br>roles:delete<br>roles.builtin:add<br>roles.builtin:remove | Allows every read action and in addition allows to create, change and delete custom roles and create or remove built-in role assignments.
|
||||
grafana:roles:reporting:admin:read | reports:read<br>reports:send<br>reports.settings:read | Allows to read reports and report settings.
|
||||
grafana:roles:reporting:admin:edit | All permissions from `grafana:roles:reporting:admin:read` and <br>reports.admin:write<br>reports:delete<br>reports.settings:write | Allows every read action for reports and in addition allows to administer reports.
|
||||
grafana:roles:users:admin:read | users.authtoken:list<br>users.quotas:list<br>users:read<br>users.teams:read | Allows to list and get users and related information.
|
||||
grafana:roles:users:admin:edit | All permissions from `grafana:roles:users:admin:read` and <br>users.password:update<br>users:write<br>users:create<br>users:delete<br>users:enable<br>users:disable<br>users.permissions:update<br>users:logout<br>users.authtoken:update<br>users.quotas:update | Allows every read action for users and in addition allows to administer users.
|
||||
grafana:roles:users:org:read | org.users:read | Allows to get user organizations.
|
||||
grafana:roles:users:org:edit | All permissions from `grafana:roles:users:org:read` and <br>org.users:add<br>org.users:remove<br>org.users.role:update | Allows every read action for user organizations and in addition allows to administer user organizations.
|
||||
grafana:roles:ldap:admin:read | ldap.user:read<br>ldap.status:read | Allows to read LDAP information and status.
|
||||
grafana:roles:ldap:admin:edit | All permissions from `grafana:roles:ldap:admin:read` and <br>ldap.user:sync | Allows every read action for LDAP and in addition allows to administer LDAP.
|
||||
fixed:permissions:admin:read | roles:read<br>roles:list<br>roles.builtin:list | Allows to list and get available roles and built-in role assignments.
|
||||
fixed:permissions:admin:edit | All permissions from `fixed:permissions:admin:read` and <br>roles:write<br>roles:delete<br>roles.builtin:add<br>roles.builtin:remove | Allows every read action and in addition allows to create, change and delete custom roles and create or remove built-in role assignments.
|
||||
fixed:reporting:admin:read | reports:read<br>reports:send<br>reports.settings:read | Allows to read reports and report settings.
|
||||
fixed:reporting:admin:edit | All permissions from `fixed:reporting:admin:read` and <br>reports.admin:write<br>reports:delete<br>reports.settings:write | Allows every read action for reports and in addition allows to administer reports.
|
||||
fixed:users:admin:read | users.authtoken:list<br>users.quotas:list<br>users:read<br>users.teams:read | Allows to list and get users and related information.
|
||||
fixed:users:admin:edit | All permissions from `fixed:users:admin:read` and <br>users.password:update<br>users:write<br>users:create<br>users:delete<br>users:enable<br>users:disable<br>users.permissions:update<br>users:logout<br>users.authtoken:update<br>users.quotas:update | Allows every read action for users and in addition allows to administer users.
|
||||
fixed:users:org:read | org.users:read | Allows to get user organizations.
|
||||
fixed:users:org:edit | All permissions from `fixed:users:org:read` and <br>org.users:add<br>org.users:remove<br>org.users.role:update | Allows every read action for user organizations and in addition allows to administer user organizations.
|
||||
fixed:ldap:admin:read | ldap.user:read<br>ldap.status:read | Allows to read LDAP information and status.
|
||||
fixed:ldap:admin:edit | All permissions from `fixed:ldap:admin:read` and <br>ldap.user:sync | Allows every read action for LDAP and in addition allows to administer LDAP.
|
||||
|
||||
## Custom roles
|
||||
|
||||
@ -52,7 +52,7 @@ To create, update or delete a custom role, you can use the [Fine-grained access
|
||||
A role's name is intended as a human friendly identifier for the role, helping administrators understand the purpose of a role. The name cannot be longer than 190 characters, and we recommend using ASCII characters.
|
||||
Role names must be unique within an organization.
|
||||
|
||||
Roles with names prefixed by `grafana:roles:` are predefined roles created by Grafana and cannot be created or modified by users.
|
||||
Roles with names prefixed by `fixed:` are fixed roles created by Grafana and cannot be created or modified by users.
|
||||
|
||||
##### Role version
|
||||
|
||||
@ -79,7 +79,7 @@ Note that you won't be able to create, update or delete a custom role with permi
|
||||
|
||||
## Built-in role assignments
|
||||
|
||||
To control what your users can access or not, you can assign or unassign [Custom roles]({{< ref "#custom-roles" >}}) or [Predefined roles]({{< ref "#predefined-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.
|
||||
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.
|
||||
@ -97,5 +97,5 @@ You can only create _organization local_ assignments for _organization local_ ro
|
||||
|
||||
Built-in role | Associated role | Description
|
||||
--- | --- | ---
|
||||
Grafana Admin | grafana:roles:permissions:admin:edit<br>grafana:roles:permissions:admin:read<br>grafana:roles:reporting:admin:edit<br>grafana:roles:reporting:admin:read<br>grafana:roles:users:admin:edit<br>grafana:roles:users:admin:read<br>grafana:roles:users:org:edit<br>grafana:roles:users:org:read<br>grafana:roles:ldap:admin:edit<br>grafana:roles:ldap:admin:read | Allows access to resources which [Grafana Server Admin]({{< relref "../../permissions/_index.md#grafana-server-admin-role" >}}) has permissions by default.
|
||||
Admin | grafana:roles:users:org:edit<br>grafana:roles:users:org:read<br>grafana:roles:reporting:admin:edit<br>grafana:roles:reporting:admin:read | Allows access to resource which [Admin]({{< relref "../../permissions/organization_roles.md" >}}) has permissions by default.
|
||||
Grafana Admin | fixed:permissions:admin:edit<br>fixed:permissions:admin:read<br>fixed:reporting:admin:edit<br>fixed:reporting:admin:read<br>fixed:users:admin:edit<br>fixed:users:admin:read<br>fixed:users:org:edit<br>fixed:users:org:read<br>fixed:ldap:admin:edit<br>fixed:ldap:admin:read | Allows access to resources which [Grafana Server Admin]({{< relref "../../permissions/_index.md#grafana-server-admin-role" >}}) has permissions by default.
|
||||
Admin | fixed:users:org:edit<br>fixed:users:org:read<br>fixed:reporting:admin:edit<br>fixed:reporting:admin:read | Allows access to resource which [Admin]({{< relref "../../permissions/organization_roles.md" >}}) has permissions by default.
|
||||
|
||||
@ -14,7 +14,7 @@ Before you get started, make sure to [enable fine-grained access control]({{< re
|
||||
## Check all built-in role assignments
|
||||
|
||||
You can use the [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control.md#get-all-built-in-role-assignments" >}}) to see all available built-in role assignments.
|
||||
The response contains a mapping between one of the organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin` to the custom or predefined roles.
|
||||
The response contains a mapping between one of the organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin` to the custom or fixed roles.
|
||||
|
||||
Example request:
|
||||
```
|
||||
@ -29,7 +29,7 @@ Example response:
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "qQui_LCMk",
|
||||
"name": "grafana:roles:users:org:edit",
|
||||
"name": "fixed:users:org:edit",
|
||||
"description": "Allows every read action for user organizations and in addition allows to administer user organizations.",
|
||||
"global": true,
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
@ -38,7 +38,7 @@ Example response:
|
||||
{
|
||||
"version": 1,
|
||||
"uid": "Kz9m_YjGz",
|
||||
"name": "grafana:roles:reporting:admin:edit",
|
||||
"name": "fixed:reporting:admin:edit",
|
||||
"description": "Gives access to edit any report or the organization's general reporting settings.",
|
||||
"global": true,
|
||||
"updated": "2021-05-13T16:24:26+02:00",
|
||||
@ -51,7 +51,7 @@ Example response:
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "qQui_LCMk",
|
||||
"name": "grafana:roles:users:org:edit",
|
||||
"name": "fixed:users:org:edit",
|
||||
"description": "Allows every read action for user organizations and in addition allows to administer user organizations.",
|
||||
"global": true,
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
@ -60,7 +60,7 @@ Example response:
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "ajum_YjGk",
|
||||
"name": "grafana:roles:users:admin:read",
|
||||
"name": "fixed:users:admin:read",
|
||||
"description": "Allows to list and get users and related information.",
|
||||
"global": true,
|
||||
"updated": "2021-05-17T20:49:17+02:00",
|
||||
@ -69,7 +69,7 @@ Example response:
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "K3um_LCMk",
|
||||
"name": "grafana:roles:users:admin:edit",
|
||||
"name": "fixed:users:admin:edit",
|
||||
"description": "Allows every read action for users and in addition allows to administer users.",
|
||||
"global": true,
|
||||
"updated": "2021-05-17T20:49:17+02:00",
|
||||
@ -94,7 +94,7 @@ Example response:
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "qQui_LCMk",
|
||||
"name": "grafana:roles:users:org:edit",
|
||||
"name": "fixed:users:org:edit",
|
||||
"description": "Allows every read action for user organizations and in addition allows to administer user organizations.",
|
||||
"global": true,
|
||||
"permissions": [
|
||||
@ -203,7 +203,7 @@ In order to create reports, you would need to have `reports.admin:write` permiss
|
||||
|
||||
If you want your users who have `Viewer` organization role to create reports, you have two options:
|
||||
|
||||
1. First option is to create a built-in role assignment and map `grafana:roles:reporting:admin:edit` predefined role to the `Viewer` built-in role. Note that `grafana:roles:reporting:admin:edit` predefined role allows doing more than creating reports. Refer to [predefined roles]({{< relref "./roles.md#predefined-roles" >}}) for full list of permission assignments.
|
||||
1. First option is to create a built-in role assignment and map `fixed:reporting:admin:edit` fixed role to the `Viewer` built-in role. Note that `fixed:reporting:admin:edit` fixed role allows doing more than creating reports. Refer to [fixed roles]({{< relref "./roles.md#fixed-roles" >}}) for full list of permission assignments.
|
||||
1. Second option is to [create a custom role]({{< ref "#create-your-custom-role" >}}) with `reports.admin:write` permission, and create a built-in role assignment for `Viewer` organization role.
|
||||
|
||||
## Prevent Grafana Admin from creating and inviting users
|
||||
@ -213,14 +213,14 @@ In order to create users, you would need to have `users:create` permission. By d
|
||||
If you want to prevent Grafana Admin from creating users, you can do the following:
|
||||
|
||||
1. [Check all built-in role assignments]({{< ref "#check-all-built-in-role-assignments" >}}) to see what built-in role assignments are available.
|
||||
1. From built-in role assignments, find the role which gives `users:create` permission. Refer to [predefined roles]({{< relref "./roles.md#predefined-roles" >}}) for full list of permission assignments.
|
||||
1. From built-in role assignments, find the role which gives `users:create` permission. Refer to [fixed roles]({{< relref "./roles.md#fixed-roles" >}}) for full list of permission assignments.
|
||||
1. Remove the built-in role assignment by using an [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control.md" >}}) or by using [Grafana provisioning]({{< relref "./provisioning" >}}).
|
||||
|
||||
## Allow Editors to create new custom roles
|
||||
|
||||
By default, 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:
|
||||
|
||||
1. First option is to create a built-in role assignment and map `grafana:roles:permissions:admin:edit` and `grafana:roles:permissions:admin:read` predefined roles to the `Editor` built-in role.
|
||||
1. First option is to create a built-in role assignment and map `fixed:permissions:admin:edit` and `fixed:permissions:admin:read` fixed roles to the `Editor` built-in role.
|
||||
1. Second option is to [create a custom role]({{< ref "#create-your-custom-role" >}}) with `roles.builtin:add` and `roles:write` permissions, and create a built-in role assignment for `Editor` organization role.
|
||||
|
||||
Note that in any scenario, your `Editor` would be able to create and manage roles only with the permissions they have, or with a subset of them.
|
||||
|
||||
@ -87,7 +87,7 @@ Content-Type: application/json; charset=UTF-8
|
||||
{
|
||||
"version": 1,
|
||||
"uid": "Kz9m_YjGz",
|
||||
"name": "grafana:roles:reporting:admin:edit",
|
||||
"name": "fixed:reporting:admin:edit",
|
||||
"description": "Gives access to edit any report or the organization's general reporting settings.",
|
||||
"global": true,
|
||||
"updated": "2021-05-13T16:24:26+02:00",
|
||||
@ -96,7 +96,7 @@ Content-Type: application/json; charset=UTF-8
|
||||
{
|
||||
"version": 5,
|
||||
"uid": "vi9mlLjGz",
|
||||
"name": "grafana:roles:permissions:admin:read",
|
||||
"name": "fixed:permissions:admin:read",
|
||||
"description": "Gives access to read and list roles and permissions, as well as built-in role assignments.",
|
||||
"global": true,
|
||||
"updated": "2021-05-13T22:41:49+02:00",
|
||||
@ -142,7 +142,7 @@ Content-Type: application/json; charset=UTF-8
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "jZrmlLCGk",
|
||||
"name": "grafana:roles:permissions:admin:edit",
|
||||
"name": "fixed:permissions:admin:edit",
|
||||
"description": "Gives access to create, update and delete roles, as well as manage built-in role assignments.",
|
||||
"global": true,
|
||||
"permissions": [
|
||||
@ -176,7 +176,7 @@ Code | Description
|
||||
|
||||
`POST /api/access-control/roles`
|
||||
|
||||
Creates a new custom role and maps given permissions to that role. Note that roles with the same prefix as [Predefined Roles]({{< relref "../enterprise/access-control/roles.md" >}}) can't be created.
|
||||
Creates a new custom role and maps given permissions to that role. Note that roles with the same prefix as [Fixed Roles]({{< relref "../enterprise/access-control/roles.md" >}}) can't be created.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
@ -438,7 +438,7 @@ Content-Type: application/json; charset=UTF-8
|
||||
{
|
||||
"version": 1,
|
||||
"uid": "qQui_LCMk",
|
||||
"name": "grafana:roles:users:org:edit",
|
||||
"name": "fixed:users:org:edit",
|
||||
"description": "",
|
||||
"global": true,
|
||||
"updated": "2021-05-13T16:24:26+02:00",
|
||||
@ -447,7 +447,7 @@ Content-Type: application/json; charset=UTF-8
|
||||
{
|
||||
"version": 1,
|
||||
"uid": "PeXmlYjMk",
|
||||
"name": "grafana:roles:users:org:read",
|
||||
"name": "fixed:users:org:read",
|
||||
"description": "",
|
||||
"global": true,
|
||||
"updated": "2021-05-13T16:24:26+02:00",
|
||||
@ -458,7 +458,7 @@ Content-Type: application/json; charset=UTF-8
|
||||
{
|
||||
"version": 1,
|
||||
"uid": "qQui_LCMk",
|
||||
"name": "grafana:roles:users:org:edit",
|
||||
"name": "fixed:users:org:edit",
|
||||
"description": "",
|
||||
"global": true,
|
||||
"updated": "2021-05-13T16:24:26+02:00",
|
||||
|
||||
Loading…
Reference in New Issue
Block a user