Docs: Document fine-grained access control (#33563)
This commit is contained in:
Vardan Torosyan
@@ -0,0 +1,60 @@
|
||||
+++
|
||||
title = "Fine-grained access control"
|
||||
description = "Grant, change, or revoke access to Grafana resources"
|
||||
keywords = ["grafana", "fine-grained-access-control", "roles", "permissions", "enterprise"]
|
||||
weight = 100
|
||||
+++
|
||||
|
||||
# Fine-grained access control
|
||||
|
||||
> **Note:** Fine-grained access control is in beta, and you can expect changes in future releases.
|
||||
|
||||
Fine-grained access control provides a standardized way of granting, changing, and revoking access when it comes to viewing and modifying Grafana resources, such as users and reports.
|
||||
Fine-grained access control works alongside the current [Grafana permissions]({{< relref "../../permissions/_index.md" >}}), and it allows you granular control of users’ actions.
|
||||
|
||||
To learn more about how fine-grained access control works, refer to [Roles]({{< relref "./roles.md" >}}) and [Permissions]({{< relref "./permissions.md" >}}).
|
||||
To use the fine-grained access control system, refer to [Fine-grained access control usage scenarios]({{< relref "./usage-scenarios.md" >}}).
|
||||
|
||||
## Access management
|
||||
|
||||
Fine-grained access control considers a) _who_ has an access (`identity`), and b) _what they can do_ and on which _Grafana resource_ (`role`).
|
||||
|
||||
You can grant, change, or revoke access to _users_ (`identity`). When an authenticated user tries to access a Grafana resource, the authorization system checks the required fine-grained permissions for the resource and determines whether or not the action is allowed. Refer to [Fine-grained permissions]({{< relref "./permissions.md" >}}) for a complete list of available permissions.
|
||||
|
||||
To grant or revoke access to your users, create or remove built-in role assignments. For more information, refer to [Built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}).
|
||||
|
||||
## Resources with fine-grained permissions
|
||||
|
||||
Fine-grained access control is currently available for [Reporting]({{< relref "../reporting.md" >}}) and [Managing Users]({{< relref "../../manage-users/_index.md" >}}).
|
||||
To learn more about specific endpoints where you can use access control, refer to [Permissions]({{< relref "./permissions.md" >}}) and to the relevant API guide:
|
||||
|
||||
- [Fine-grained access control API]({{< relref "../../http_api/access_control.md" >}})
|
||||
- [Admin API]({{< relref "../../http_api/admin.md" >}})
|
||||
- [Organization API]({{< relref "../../http_api/org.md" >}})
|
||||
- [Reporting API]({{< relref "../../http_api/reporting.md" >}})
|
||||
- [User API]({{< relref "../../http_api/user.md" >}})
|
||||
|
||||
## Enable fine-grained access control
|
||||
|
||||
Fine-grained access control is available behind the `accesscontrol` feature toggle in Grafana Enterprise 8.0+.
|
||||
You can enable it either in a [config file](({{< relref "../../administration/configuration.md#fconfig-file-locations" >}})) or by [configuring an environment variable](http://localhost:3002/docs/grafana/next/administration/configuration/#configure-with-environment-variables).
|
||||
|
||||
### Enable in config file
|
||||
|
||||
In your [config file](({{< relref "../../administration/configuration.md#config-file-locations" >}})), add `accesscontrol` as a [feature_toggle](({{< relref "../../administration/configuration.md#feature_toggle" >}})).
|
||||
|
||||
```
|
||||
[feature_toggles]
|
||||
# enable features, separated by spaces
|
||||
enable = accesscontrol
|
||||
```
|
||||
|
||||
### Enable with an environment variable
|
||||
|
||||
You can use `GF_FEATURE_TOGGLES_ENABLE = accesscontrol` environment variable to override the config file configuration and enable fine-grained access control.
|
||||
|
||||
Refer to [Configuring with environment variables]({{< relref "../../administration/configuration.md#configure-with-environment-variables" >}}) for more information.
|
||||
|
||||
### Verify if enabled
|
||||
|
||||
You can verify if fine-grained access control is enabled or not by sending an HTTP request to the [Check endpoint]({{< relref "../../http_api/access_control.md#check-if-enabled" >}}).
|
||||
@@ -0,0 +1,75 @@
|
||||
+++
|
||||
title = "Permissions"
|
||||
description = "Understand fine-grained access control permissions"
|
||||
keywords = ["grafana", "fine-grained access-control", "roles", "permissions", "enterprise"]
|
||||
weight = 115
|
||||
+++
|
||||
|
||||
# Permissions
|
||||
|
||||
Each permission is defined by an action and a scope. When evaluating a fine-grained access decision, consider what specific action a user should be allowed to perform, and on what resources (its scope).
|
||||
|
||||
To grant permissions to a user, create built-in role assignments. A built-in role assignment is a *modification* to one of the existing built-in roles in Grafana (Viewer, Editor, Admin) For more information, refer to [Built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}).
|
||||
|
||||
To learn more about which permissions are used for which resources, refer to [Resources with fine-grained permissions]({{< relref "./_index.md#resources-with-fine-grained-permissions" >}}).
|
||||
|
||||
action
|
||||
: The specific action on a resource defines what a user is allowed to perform if they have permission with the relevant action assigned to it.
|
||||
|
||||
scope
|
||||
: The scope describes where an action can be performed, such as reading a specific user profile. In such case, a permission is associated with the scope `users:<userId>` to the relevant role. Also, you can combine multiple scopes by using the `/` delimiter.
|
||||
|
||||
## Action definitions
|
||||
|
||||
Note that below list is not exhaustive yet and more permissions will be available with further releases of fine-grained access control.
|
||||
|
||||
Action | Applicable scopes | Description
|
||||
--- | --- | ---
|
||||
roles:list | roles:* | Allows to list available roles without permissions.
|
||||
roles:read | roles:* | Allows to read a specific role with it's permissions.
|
||||
roles:write | permissions:delegate | Allows to create or update a custom role.
|
||||
roles:delete | permissions:delegate | Allows to delete a custom role.
|
||||
roles.builtin:list | roles:* | Allows to list built-in role assignments.
|
||||
roles.builtin:add | permissions:delegate | Allows to create a built-in role assignment.
|
||||
roles.builtin:remove | permissions:delegate | Allows to delete a built-in role assignment.
|
||||
reports.admin:write | reports:* | Allows to create or update reports.
|
||||
reports:delete | reports:* | Allows to delete reports.
|
||||
reports:read | reports:* | Allows to list all available reports and to get a specific report.
|
||||
reports:send | reports:* | Allows to send report email.
|
||||
reports.settings:write | n/a | Allows to update report settings.
|
||||
reports.settings:read | n/a | Allows to read report settings.
|
||||
provisioning:reload | service:access-control | Allows to reload provisioning files after an update.
|
||||
users:read | global:users:* | Allows to read, search user profiles.
|
||||
users:write | global:users:* | Allows to update user profiles.
|
||||
users.teams:read | global:users:* | Allows to read user teams.
|
||||
users.authtoken:list | global:users:* | Allows to list auth tokens assigned to users.
|
||||
users.authtoken:update | global:users:* | Allows to update auth tokens assigned to users.
|
||||
users.password:update | global:users:* | Allows to update users password.
|
||||
users:delete | global:users:* | Allows to delete users.
|
||||
users:create | n/a | Allows to create users.
|
||||
users:enable | global:users:* | Allows to enable users.
|
||||
users:disable | global:users:* | Allows to disable users.
|
||||
users.permissions:update | global:users:* | Allows to update users org level permissions.
|
||||
users:logout | global:users:* | Allows to enforce logout for users.
|
||||
users.quotas:list | global:users:* | Allows to list user quotas.
|
||||
users.quotas:update | global:users:* | Allows to update user quotas.
|
||||
org.users.read | users:* | Allows to get user profiles within the organization.
|
||||
org.users.add | users:* | Allows to add users to the organization.
|
||||
org.users.remove | users:* | Allows to remove users from the organization.
|
||||
org.users.role:update | users:* | Allows to update users organization role for the assigned organization.
|
||||
ldap.user:read | n/a | Allows to read LDAP users.
|
||||
ldap.user:sync | n/a | Allows to sync LDAP users.
|
||||
ldap.status:read | n/a | Allows to check LDAP status.
|
||||
|
||||
## Scope definitions
|
||||
|
||||
Note that below list is not exhaustive yet and more scopes will be available with further releases of fine-grained access control.
|
||||
|
||||
Scope | Description
|
||||
--- | ---
|
||||
roles:* | Indicates against what roles an action can be performed. For example, `roles:*` assumes any roles, and `roles:randomuid` assumes only a role with UID `randomuid`.
|
||||
permissions: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.
|
||||
reports:* | Indicates against what reports an action can be performed.
|
||||
service:access-control | Only relevant for provisioning and indicates that the action can be performed only for access control provisioning files.
|
||||
global:users:* | Indicates that action can be performed against users globally.
|
||||
users:* | Indicates that an action can be performed against users in organization level.
|
||||
@@ -0,0 +1,140 @@
|
||||
+++
|
||||
title = "Provisioning roles and assignments"
|
||||
description = "Understand how to provision roles and assignments in fine-grained access control"
|
||||
keywords = ["grafana", "fine-grained-access-control", "roles", "provisioning", "assignments", "permissions", "enterprise"]
|
||||
weight = 120
|
||||
+++
|
||||
|
||||
# Provisioning
|
||||
|
||||
You can create, change or remove [Custom roles]({{< relref "./roles.md#custom-roles" >}}) and create or remove [built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}), by adding one or more YAML configuration files in the [`provisioning/access-control/`]({{< relref "../../administration/configuration/#provisioning" >}}) directory.
|
||||
Refer to [Grafana provisioning]({{< relref "../../administration/configuration/#provisioning" >}}) to learn more about provisioning.
|
||||
|
||||
If you want to manage roles and built-in role assignments by API, refer to the [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control/" >}}).
|
||||
|
||||
## Configuration
|
||||
|
||||
The configuration files must be located in the [`provisioning/access-control/`]({{< relref "../../administration/configuration/#provisioning" >}}) directory.
|
||||
Grafana performs provisioning during the startup. Refer to the [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}) to understand how you can reload configuration at runtime.
|
||||
|
||||
## Manage custom roles
|
||||
|
||||
You can create, update and delete custom roles, as well as create and remove built-in role assignments for them.
|
||||
|
||||
### Create or update roles
|
||||
|
||||
To create or update custom roles, you can add a list of `roles` in the configuration.
|
||||
|
||||
Note that in order to update a role, you would need to increment the [version]({{< relref "./roles.md#custom-roles" >}}).
|
||||
|
||||
It is only possibly to provision [organization local]({{< relref "./roles#role-scopes" >}}) roles. For creating or updating _global_ roles, refer to the [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control.md" >}}).
|
||||
|
||||
### Delete roles
|
||||
|
||||
To delete a role, you can add a list of roles under `deleteRoles` section in the configuration file. Note that deletion is performed after role insertion/update.
|
||||
|
||||
### Create and remove built-in role assignments
|
||||
|
||||
To create a built-in role assignment, you can add list of assignments under `builtInRoles` section in the configuration file, as an element of `roles`. To remove a built-in role assignment, leave `builtInRoles` list empty.
|
||||
|
||||
Note that it is only possibly to provision [organization local]({{< relref "./roles#built-in-role-assignments" >}}) assignments. For creating or updating _global_ assignments, refer to the [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control.md" >}}).
|
||||
|
||||
## 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.
|
||||
|
||||
### 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.
|
||||
|
||||
### 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.
|
||||
|
||||
## Example of a role configuration file
|
||||
|
||||
```yaml
|
||||
# config file version
|
||||
apiVersion: 1
|
||||
|
||||
# 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 predefined roles
|
||||
predefinedRole: "grafana:roles: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"
|
||||
|
||||
# list of roles that should be deleted
|
||||
deleteRoles:
|
||||
# <string> name of the role you want to create. Required if no uid is set
|
||||
- name: ReportEditor
|
||||
# <string> uid of the role. Required if no name
|
||||
uid: reporteditor1
|
||||
# <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
|
||||
|
||||
# list of roles to insert/update depending on what is available in the database
|
||||
roles:
|
||||
# <string, required> name of the role you want to create. Required
|
||||
- name: CustomEditor
|
||||
# <string> uid of the role. Has to be unique for all orgs.
|
||||
uid: customeditor1
|
||||
# <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
|
||||
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
|
||||
permissions:
|
||||
# <string, required> action allowed
|
||||
- action: "users:read"
|
||||
#<string, required> 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
|
||||
```
|
||||
|
||||
## Supported settings
|
||||
|
||||
The following sections detail the supported settings for roles and built-in role assignments.
|
||||
|
||||
- Refer to [Permissions]({{< relref "./permissions.md#action-definitions" >}}) for full list of valid permissions.
|
||||
- Check [Custom roles]({{< relref "./roles.md#custom-roles" >}}) to understand attributes for roles.
|
||||
- The [default org ID]({{< relref "../../administration/configuration#auto_assign_org_id" >}}) is used if `orgId` is not specified in any of the configuration blocks.
|
||||
|
||||
## Validation rules
|
||||
|
||||
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.
|
||||
|
||||
### Built-in role assignments
|
||||
|
||||
- `name` must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`.
|
||||
- When `orgId` is not specified, it inherits the `orgId` from `role`.
|
||||
- `orgId` in the `role` and in the assignment must be the same.
|
||||
|
||||
### Role deletion
|
||||
|
||||
- Either the role `name` or `uid` must be provided
|
||||
@@ -0,0 +1,101 @@
|
||||
+++
|
||||
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"]
|
||||
weight = 105
|
||||
+++
|
||||
|
||||
# Roles
|
||||
|
||||
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.
|
||||
- [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.
|
||||
|
||||
## Role scopes
|
||||
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
- All predefined roles are _global_ by default
|
||||
- All predefined roles have a `grafana:roles:` prefix.
|
||||
- You can’t change or delete a predefined 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.
|
||||
|
||||
## Custom roles
|
||||
|
||||
Custom roles allow you to manage access to your users the way you want, by mapping [fine-grained permissions]({{< relref "./permissions.md" >}}) to it and creating [built-in role assignments]({{< ref "#built-in-role-assignments.md" >}}).
|
||||
|
||||
To create, update or delete a custom role, you can use the [Fine-grained access control API]({{< relref "../../http_api/access_control.md" >}}) or [Grafana Provisioning]({{< relref "./provisioning.md" >}}).
|
||||
|
||||
##### Role name
|
||||
|
||||
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.
|
||||
|
||||
##### Role version
|
||||
|
||||
The version of a role is a positive integer which defines the current version of the role. When updating a role, you can either omit the version field to increment the previous value by 1 or set a new version which must be strictly larger than the previous version for the update to succeed.
|
||||
|
||||
##### Permissions
|
||||
|
||||
You manage access to Grafana resources by mapping [permissions]({{< relref "./permissions.md" >}}) to roles. You can create and assign roles without any permissions as placeholders.
|
||||
|
||||
##### Role UID
|
||||
|
||||
Each custom role has a UID defined which is a unique identifier associated with the role allowing you to change or delete the role. You can either generate UID yourself, or let Grafana generate one for you.
|
||||
|
||||
The same UID cannot be used for roles in different organizations within the same Grafana instance.
|
||||
|
||||
### Create, update and delete roles
|
||||
|
||||
You can create, update and delete custom roles by using the [Access Control HTTP API]({{< relref "../../http_api/access_control.md" >}}) or by using [Grafana Provisioning]({{< relref "./provisioning.md" >}}).
|
||||
|
||||
By default, Grafana Server Admin has a [built-in role assignment]({{< ref "#built-in-role-assignments" >}}) which allows a user to create, update or delete custom roles.
|
||||
If a Grafana Server Admin wants to delegate that privilege to other users, they can create a custom role with relevant [permissions]({{< relref "./permissions.md" >}}) and `permissions:delegate` scope will allow those users to manage roles themselves.
|
||||
|
||||
Note that you won't be able to create, update or delete a custom role with permissions which you yourself do not have. For example, if the only permission you have is a `users:create`, you won't be able to create a role with other permissions.
|
||||
|
||||
## Built-in role assignments
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
### Create and remove built-in role assignments
|
||||
|
||||
You can create or remove built-in role assignments using [Fine-grained access control API]({{< relref "../../http_api/access_control.md" >}}) or using [Grafana Provisioning]({{< relref "./provisioning">}}).
|
||||
|
||||
### Scope of assignments
|
||||
|
||||
A built-in role assignment can be either _global_ or _organization local_. _Global_ assignments are not mapped to any specific organization and will be applied to all organizations, whereas _organization local_ assignments are only applied for that specific organization.
|
||||
You can only create _organization local_ assignments for _organization local_ roles.
|
||||
|
||||
### Default built-in role assignments
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,226 @@
|
||||
+++
|
||||
title = "Fine-grained access control usage scenarios"
|
||||
description = "Fine-grained access control usage scenarios"
|
||||
keywords = ["grafana", "fine-grained-access-control", "roles", "permissions", "fine-grained-access-control-usage", "enterprise"]
|
||||
weight = 125
|
||||
+++
|
||||
|
||||
# Fine-grained access control usage scenarios
|
||||
|
||||
This guide contains several examples and usage scenarios of using fine-grained roles and permissions for controlling access to Grafana resources.
|
||||
|
||||
Before you get started, make sure to [enable fine-grained access control]({{< relref "./_index.md#enable-fine-grained-access-control" >}}).
|
||||
|
||||
## 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.
|
||||
|
||||
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": "grafana:roles: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",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
{
|
||||
"version": 1,
|
||||
"uid": "Kz9m_YjGz",
|
||||
"name": "grafana:roles: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",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
}
|
||||
...
|
||||
],
|
||||
"Grafana Admin": [
|
||||
...
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "qQui_LCMk",
|
||||
"name": "grafana:roles: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",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "ajum_YjGk",
|
||||
"name": "grafana:roles:users:admin:read",
|
||||
"description": "Allows to list and get users and related information.",
|
||||
"global": true,
|
||||
"updated": "2021-05-17T20:49:17+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "K3um_LCMk",
|
||||
"name": "grafana:roles: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",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
To see what permissions each of the assigned roles have, you can a [Get a role]({{< relref "../../http_api/access_control.md#get-a-role" >}}) by using an HTTP API.
|
||||
|
||||
Example request:
|
||||
|
||||
```
|
||||
curl --location --request GET '<grafana_url>/api/access-control/roles/qQui_LCMk' --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ='
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```
|
||||
{
|
||||
"version": 2,
|
||||
"uid": "qQui_LCMk",
|
||||
"name": "grafana:roles:users:org:edit",
|
||||
"description": "Allows every read action for user organizations and in addition allows to administer user organizations.",
|
||||
"global": true,
|
||||
"permissions": [
|
||||
{
|
||||
"action": "org.users:add",
|
||||
"scope": "users:*",
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
"created": "2021-05-17T20:49:18+02:00"
|
||||
},
|
||||
{
|
||||
"action": "org.users:read",
|
||||
"scope": "users:*",
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
"created": "2021-05-17T20:49:18+02:00"
|
||||
},
|
||||
{
|
||||
"action": "org.users:remove",
|
||||
"scope": "users:*",
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
"created": "2021-05-17T20:49:18+02:00"
|
||||
},
|
||||
{
|
||||
"action": "org.users.role:update",
|
||||
"scope": "users:*",
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
"created": "2021-05-17T20:49:18+02:00"
|
||||
}
|
||||
],
|
||||
"updated": "2021-05-17T20:49:18+02:00",
|
||||
"created": "2021-05-13T16:24:26+02:00"
|
||||
}
|
||||
```
|
||||
|
||||
## Create your first custom role
|
||||
|
||||
You can create your custom role by either using an [HTTP API]({{< relref "../../http_api/access_control.md#create-a-new-custom-role" >}}) or by using [Grafana provisioning]({{< relref "./provisioning.md" >}}).
|
||||
You can take a look at [actions and scopes]({{< relref "./provisioning.md#action-definitions" >}}) to decide what permissions would you like to map to your role.
|
||||
|
||||
Example HTTP request:
|
||||
```
|
||||
curl --location --request POST '<grafana_url>/api/access-control/roles/' \
|
||||
--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"version": 1,
|
||||
"uid": "jZrmlLCkGksdka",
|
||||
"name": "custom:users:admin",
|
||||
"description": "My custom role which gives users permissions to create users",
|
||||
"global": true,
|
||||
"permissions": [
|
||||
{
|
||||
"action": "users:create"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
Example response:
|
||||
|
||||
```
|
||||
{
|
||||
"version": 1,
|
||||
"uid": "jZrmlLCkGksdka",
|
||||
"name": "custom:users:admin",
|
||||
"description": "My custom role which gives users permissions to create users",
|
||||
"global": true,
|
||||
"permissions": [
|
||||
{
|
||||
"action": "users:create"
|
||||
"updated": "2021-05-17T22:07:31.569936+02:00",
|
||||
"created": "2021-05-17T22:07:31.569935+02:00"
|
||||
}
|
||||
],
|
||||
"updated": "2021-05-17T22:07:31.564403+02:00",
|
||||
"created": "2021-05-17T22:07:31.564403+02:00"
|
||||
}
|
||||
```
|
||||
|
||||
Once the custom role is created, you can create a built-in role assignment by using an [HTTP API]({{< relref "../../http_api/access_control.md#create-a-built-in-role-assignment" >}}).
|
||||
If you created your role using [Grafana provisioning]({{< relref "./provisioning.md" >}}), you can also create the assignment with it.
|
||||
|
||||
Example HTTP 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"
|
||||
}
|
||||
```
|
||||
|
||||
## Allow Viewers to create reports
|
||||
|
||||
In order to create reports, you would need to have `reports.admin:write` permission. By default, Grafana Admin's or organization Admin can create reports as there is a [built-in role assignment]({{< relref "./roles#built-in-role-assignments" >}}) which comes with `reports.admin:write` permission.
|
||||
|
||||
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. 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
|
||||
|
||||
In order to create users, you would need to have `users:create` permission. By default, user with Grafana Admin role can create users as there is a [built-in role assignment]({{< relref "./roles#built-in-role-assignments" >}}) which comes with `users:create` permission.
|
||||
|
||||
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. 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. 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.
|
||||
Reference in New Issue
Block a user