From 96da84ca497fc6cac0a1e3d40544861752cdb53c Mon Sep 17 00:00:00 2001 From: Emil Tullstedt Date: Wed, 26 May 2021 14:59:24 +0200 Subject: [PATCH] Access control: Rename predefined roles to fixed roles (docs) (#34472) --- .../enterprise/access-control/provisioning.md | 16 +++---- .../enterprise/access-control/roles.md | 44 +++++++++---------- .../access-control/usage-scenarios.md | 20 ++++----- docs/sources/http_api/access_control.md | 14 +++--- 4 files changed, 47 insertions(+), 47 deletions(-) diff --git a/docs/sources/enterprise/access-control/provisioning.md b/docs/sources/enterprise/access-control/provisioning.md index eeaef9f2b63..27a1cd5e298 100644 --- a/docs/sources/enterprise/access-control/provisioning.md +++ b/docs/sources/enterprise/access-control/provisioning.md @@ -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: # , must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin` - builtInRole: "Grafana Admin" - # , must be one of the existing predefined roles - predefinedRole: "grafana:roles:permissions:admin" + # , 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: # , must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin` - builtInRole: "Admin" - # , must be one of the existing predefined roles - predefinedRole: "grafana:roles:reporting:admin:read" + # , 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 diff --git a/docs/sources/enterprise/access-control/roles.md b/docs/sources/enterprise/access-control/roles.md index 31595e54ef9..3bf274a8dfe 100644 --- a/docs/sources/enterprise/access-control/roles.md +++ b/docs/sources/enterprise/access-control/roles.md @@ -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
roles:list
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
roles:write
roles:delete
roles.builtin:add
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
reports:send
reports.settings:read | Allows to read reports and report settings. -grafana:roles:reporting:admin:edit | All permissions from `grafana:roles:reporting:admin:read` and
reports.admin:write
reports:delete
reports.settings:write | Allows every read action for reports and in addition allows to administer reports. -grafana:roles:users:admin:read | users.authtoken:list
users.quotas:list
users:read
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
users.password:update
users:write
users:create
users:delete
users:enable
users:disable
users.permissions:update
users:logout
users.authtoken:update
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
org.users:add
org.users:remove
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
ldap.status:read | Allows to read LDAP information and status. -grafana:roles:ldap:admin:edit | All permissions from `grafana:roles:ldap:admin:read` and
ldap.user:sync | Allows every read action for LDAP and in addition allows to administer LDAP. +fixed:permissions:admin:read | roles:read
roles:list
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
roles:write
roles:delete
roles.builtin:add
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
reports:send
reports.settings:read | Allows to read reports and report settings. +fixed:reporting:admin:edit | All permissions from `fixed:reporting:admin:read` and
reports.admin:write
reports:delete
reports.settings:write | Allows every read action for reports and in addition allows to administer reports. +fixed:users:admin:read | users.authtoken:list
users.quotas:list
users:read
users.teams:read | Allows to list and get users and related information. +fixed:users:admin:edit | All permissions from `fixed:users:admin:read` and
users.password:update
users:write
users:create
users:delete
users:enable
users:disable
users.permissions:update
users:logout
users.authtoken:update
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
org.users:add
org.users:remove
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
ldap.status:read | Allows to read LDAP information and status. +fixed:ldap:admin:edit | All permissions from `fixed:ldap:admin:read` and
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
grafana:roles:permissions:admin:read
grafana:roles:reporting:admin:edit
grafana:roles:reporting:admin:read
grafana:roles:users:admin:edit
grafana:roles:users:admin:read
grafana:roles:users:org:edit
grafana:roles:users:org:read
grafana:roles:ldap:admin:edit
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
grafana:roles:users:org:read
grafana:roles:reporting:admin:edit
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
fixed:permissions:admin:read
fixed:reporting:admin:edit
fixed:reporting:admin:read
fixed:users:admin:edit
fixed:users:admin:read
fixed:users:org:edit
fixed:users:org:read
fixed:ldap:admin:edit
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
fixed:users:org:read
fixed:reporting:admin:edit
fixed:reporting:admin:read | Allows access to resource which [Admin]({{< relref "../../permissions/organization_roles.md" >}}) has permissions by default. diff --git a/docs/sources/enterprise/access-control/usage-scenarios.md b/docs/sources/enterprise/access-control/usage-scenarios.md index 57a516cccf6..b375f6a75a5 100644 --- a/docs/sources/enterprise/access-control/usage-scenarios.md +++ b/docs/sources/enterprise/access-control/usage-scenarios.md @@ -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. diff --git a/docs/sources/http_api/access_control.md b/docs/sources/http_api/access_control.md index 5a092382f71..acc819e512b 100644 --- a/docs/sources/http_api/access_control.md +++ b/docs/sources/http_api/access_control.md @@ -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",