IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-11 08:05:43 -06:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Document fine-grained access control (#33563)

Browse Source
This commit is contained in:
Vardan Torosyan 2021-05-20 18:53:34 +02:00 committed by GitHub
parent 292789ba2d
commit 676ddac088
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
31 changed files with 1436 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/sources/administration/provisioning.md
View File

@ -575,3 +575,9 @@ The following sections detail the supported settings and secure settings for eac
| Name |
| ---- |
| url |
## Grafana Enterprise
Grafana Enterprise supports provisioning for the following resources:
- [Access Control Provisioning]({{< relref "../enterprise/access-control/provisioning.md" >}})

1
docs/sources/enterprise/_index.md
View File

@ -43,6 +43,7 @@ With Grafana Enterprise [enhanced LDAP]({{< relref "enhanced_ldap.md" >}}), you
With Grafana Enterprise, you get access to new features, including:
- [Fine-grained access control]({{< relref "access-control/_index.md" >}}) to control access with fine-grained roles and permissions.
- [Data source permissions]({{< relref "datasource_permissions.md" >}}) to restrict query access to specific teams and users.
- [Reporting]({{< relref "reporting.md" >}}) to generate a PDF report from any dashboard and set up a schedule to have it emailed to whoever you choose.
- [Export dashboard as PDF]({{< relref "export-pdf.md" >}})

60
docs/sources/enterprise/access-control/_index.md Normal file
View File

@ -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" >}}).

75
docs/sources/enterprise/access-control/permissions.md Normal file
View File

@ -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.

140
docs/sources/enterprise/access-control/provisioning.md Normal file
View File

@ -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

101
docs/sources/enterprise/access-control/roles.md Normal file
View File

@ -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.

226
docs/sources/enterprise/access-control/usage-scenarios.md Normal file
View File

@ -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.

2
docs/sources/enterprise/auditing.md
View File

@ -2,7 +2,7 @@
title = "Auditing"
description = "Auditing"
keywords = ["grafana", "auditing", "audit", "logs"]
weight = 700
weight = 1100
+++
# Auditing

2
docs/sources/enterprise/datasource_permissions.md
View File

@ -2,7 +2,7 @@
title = "Data source permissions"
description = "Grafana Datasource Permissions Guide "
keywords = ["grafana", "configuration", "documentation", "datasource", "permissions", "users", "teams", "enterprise"]
weight = 200
weight = 500
+++
# Data source permissions

2
docs/sources/enterprise/enhanced_ldap.md
View File

@ -2,7 +2,7 @@
title = "Enhanced LDAP Integration"
description = "Grafana Enhanced LDAP Integration Guide "
keywords = ["grafana", "configuration", "documentation", "ldap", "active directory", "enterprise"]
weight = 300
weight = 600
+++
# Enhanced LDAP integration

2
docs/sources/enterprise/enterprise-configuration.md
View File

@ -2,7 +2,7 @@
title = "Enterprise configuration"
description = "Enterprise configuration documentation"
keywords = ["grafana", "configuration", "documentation", "enterprise"]
weight = 300
weight = 700
+++
# Grafana Enterprise configuration

2
docs/sources/enterprise/export-pdf.md
View File

@ -2,7 +2,7 @@
title = "Export dashboard as PDF"
description = ""
keywords = ["grafana", "export", "pdf", "share"]
weight = 900
weight = 1400
+++
# Export dashboard as PDF

2
docs/sources/enterprise/license/_index.md
View File

@ -2,7 +2,7 @@
title = "Grafana Enterprise license"
description = "Enterprise license"
keywords = ["grafana", "licensing", "enterprise"]
weight = 100
weight = 10
+++
# Grafana Enterprise license

2
docs/sources/enterprise/query-caching.md
View File

@ -2,7 +2,7 @@
title = "Query caching"
description = "Grafana Enterprise data source query caching"
keywords = ["grafana", "plugins", "query", "caching"]
weight = 110
weight = 300
+++
# Query caching

11
docs/sources/enterprise/reporting.md
View File

@ -3,7 +3,7 @@ title = "Reporting"
description = ""
keywords = ["grafana", "reporting"]
aliases = ["/docs/grafana/latest/administration/reports"]
weight = 400
weight = 800
+++
# Reporting
@ -12,6 +12,9 @@ Reporting allows you to automatically generate PDFs from any of your dashboards
> Only available in Grafana Enterprise v6.4+.
> If you have [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some actions you would need to have relevant permissions.
Refer to specific guides to understand what permissions are required.
{{< docs-imagebox img="/img/docs/enterprise/reports_list.png" max-width="500px" class="docs-image--no-shadow" >}}
Any changes you make to a dashboard used in a report are reflected the next time the report is sent. For example, if you change the time range in the dashboard, then the time range in the report changes as well.
@ -21,9 +24,13 @@ Any changes you make to a dashboard used in a report are reflected the next time
- SMTP must be configured for reports to be sent. Refer to [SMTP]({{< relref "../administration/configuration.md#smtp" >}}) in [Configuration]({{< relref "../administration/configuration.md" >}}) for more information.
- The Image Renderer plugin must be installed or the remote rendering service must be set up. Refer to [Image rendering]({{< relref "../administration/image_rendering.md" >}}) for more information.
## Access control
When [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) is enabled, you need to have the relevant [Permissions]({{< relref "../enterprise/access-control/permissions.md" >}}) to create and manage reports.
## Create or update a report
Currently only Organization Admins can create reports.
Only organization admins can create reports by default. You can customize who can create reports with [fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}).
1. Click on the reports icon in the side menu. The Reports tab allows you to view, create, and update your reports.
1. Enter report information. All fields are required unless otherwise indicated.

2
docs/sources/enterprise/request-security.md
View File

@ -2,7 +2,7 @@
title = "Request security"
description = "Grafana Enterprise request security"
keywords = ["grafana", "security", "enterprise"]
weight = 110
weight = 400
+++
# Request security

2
docs/sources/enterprise/saml.md
View File

@ -3,7 +3,7 @@ title = "SAML Authentication"
description = "Grafana SAML Authentication"
keywords = ["grafana", "saml", "documentation", "saml-auth"]
aliases = ["/docs/grafana/latest/auth/saml/"]
weight = 500
weight = 900
+++
# SAML authentication

2
docs/sources/enterprise/team-sync.md
View File

@ -3,7 +3,7 @@ title = "Team sync"
description = "Grafana Team Sync"
keywords = ["grafana", "auth", "documentation"]
aliases = ["/docs/grafana/latest/auth/saml/"]
weight = 600
weight = 1000
+++
# Team sync

2
docs/sources/enterprise/usage-insights/_index.md
View File

@ -3,7 +3,7 @@ title = "Usage insights"
description = "Understand how your Grafana instance is used"
keywords = ["grafana", "usage-insights", "enterprise"]
aliases = ["/docs/grafana/latest/enterprise/usage-insights/"]
weight = 100
weight = 200
+++
# Usage insights

2
docs/sources/enterprise/vault.md
View File

@ -2,7 +2,7 @@
title = "Vault"
description = ""
keywords = ["grafana", "vault", "configuration"]
weight = 700
weight = 1200
+++
# Vault integration

2
docs/sources/enterprise/white-labeling.md
View File

@ -3,7 +3,7 @@ title = "White labeling"
description = "Change the look of Grafana to match your corporate brand"
keywords = ["grafana", "white-labeling", "enterprise"]
aliases = ["/docs/grafana/latest/enterprise/white-labeling/"]
weight = 700
weight = 1300
+++
# White labeling

1
docs/sources/http_api/_index.md
View File

@ -37,6 +37,7 @@ dashboards, creating users and updating data sources.
Grafana Enterprise includes all of the Grafana OSS APIs as well as those that follow:
- [Fine-Grained Access Control API]({{< relref "access_control.md" >}})
- [Data Source Permissions API]({{< relref "datasource_permissions.md" >}})
- [External Group Sync API]({{< relref "external_group_sync.md" >}})
- [License API]({{< relref "licensing.md" >}})

584
docs/sources/http_api/access_control.md Normal file
View File

@ -0,0 +1,584 @@
+++
title = "Fine-grained access control HTTP API "
description = "Fine-grained access control API"
keywords = ["grafana", "http", "documentation", "api", "fine-grained-access-control", "acl", "enterprise"]
aliases = ["/docs/grafana/latest/http_api/accesscontrol/"]
+++
# Fine-grained access control API
> Fine-grained 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.
To use the API, you would need to [enable fine-grained access control]({{< relref "../enterprise/access-control/_index.md#enable-fine-grained-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" >}}).
## Get status
`GET /api/access-control/status`
Returns an indicator to check if fine-grained access control is enabled or not.
### Required permissions
Action | Scope
--- | --- |
status:accesscontrol | services:accesscontrol
#### Example request
```http
GET /api/access-control/check
Accept: application/json
Content-Type: application/json
```
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"enabled": true
}
```
#### Status codes
Code | Description
--- | --- |
200 | Returned a flag indicating if the fine-grained access control is enabled or no.
403 | Access denied
404 | Not found, an indication that fine-grained access control is not available at all.
500 | Unexpected error. Refer to body and/or server logs for more details.
## Create and manage custom roles
### Get all roles
`GET /api/access-control/roles`
Gets all existing roles. The response contains all global and organization local roles, for the organization which user is signed in.
Refer to the [Role scopes]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information.
#### Required permissions
Action | Scope
--- | --- |
roles:list | roles:*
#### Example request
```http
GET /api/access-control/roles
Accept: application/json
Content-Type: application/json
```
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"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"
},
{
"version": 5,
"uid": "vi9mlLjGz",
"name": "grafana:roles: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",
"created": "2021-05-13T16:24:26+02:00"
}
]
```
#### Status codes
Code | Description
--- | --- |
200 | Global and organization local roles are returned.
403 | Access denied
500 | Unexpected error. Refer to body and/or server logs for more details.
### Get a role
`GET /api/access-control/roles/:uid`
Get a role for the given UID.
#### Required permissions
Action | Scope
--- | --- |
roles:read | roles:*
#### Example request
```http
GET /api/access-control/roles/PYnDO3rMk
Accept: application/json
Content-Type: application/json
```
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"version": 2,
"uid": "jZrmlLCGk",
"name": "grafana:roles:permissions:admin:edit",
"description": "Gives access to create, update and delete roles, as well as manage built-in role assignments.",
"global": true,
"permissions": [
{
"action": "roles:delete",
"scope": "permissions:delegate",
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
},
{
"action": "roles:list",
"scope": "roles:*",
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
}
],
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
}
```
#### Status codes
Code | Description
--- | --- |
200 | Role is returned.
403 | Access denied
500 | Unexpected error. Refer to body and/or server logs for more details.
### Create a new custom role
`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.
#### Required permissions
`permission:delegate` scope ensures that users can only create custom roles with the 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 custom role which allows to do that. This is done to prevent escalation of privileges.
Action | Scope
--- | --- |
roles:write | permissions:delegate
#### Example request
```http
POST /api/access-control/roles
Accept: application/json
Content-Type: application/json
{
"version": 1,
"uid": "jZrmlLCGka",
"name": "custom:delete:roles",
"description": "My custom role which gives users permissions to delete roles",
"global": true,
"permissions": [
{
"action": "roles:delete",
"scope": "permissions:delegate"
}
]
}
```
#### JSON body schema
Field Name | Date Type | Required | Description
--- | --- | --- | ---
uid | string | No | UID of the role. If not present, the UID will be automatically created for you and returned in response. Refer to the [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information.
global | boolean | No | A flag indicating if the role is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request. Refer to the [Role scopes]({{< relref "../enterprise/access-control/roles.md#role-scopes" >}}) for more information.
version | number | No | Version of the role. If not present, version 0 will be assigned to the role and returned in the response. Refer to the [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information.
name | string | Yes | Name of the role. Refer to [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information.
description | string | No | Description of the role.
permissions | Permission | No | If not present, the role will be created without any permissions.
**Permission**
Field Name | Data Type | Required | Description
--- | --- | --- | ---
action | string | Yes | Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md" >}}) for full list of available actions.
scope | string | No | If not present, no scope will be mapped to the permission. Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md#scope-definitions" >}}) for full list of available scopes.
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"version": 2,
"uid": "jZrmlLCGka",
"name": "custom:delete:create:roles",
"description": "My custom role which gives users permissions to delete and create roles",
"global": true,
"permissions": [
{
"action": "roles:delete",
"scope": "permissions:delegate",
"updated": "2021-05-13T23:19:46+02:00",
"created": "2021-05-13T23:19:46+02:00"
}
],
"updated": "2021-05-13T23:20:51.416518+02:00",
"created": "2021-05-13T23:19:46+02:00"
}
```
#### Status codes
Code | Description
--- | --- |
200 | Role is updated.
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403 | Access denied
500 | Unexpected error. Refer to body and/or server logs for more details.
### Update a custom 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.
#### Required permissions
`permission:delegate` scope ensures that users can only update custom roles with the 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 update a custom role which allows to do that. This is done to prevent escalation of privileges.
Action | Scope
--- | --- |
roles:write | permissions:delegate
#### Example request
```http
PUT /api/access-control/roles/jZrmlLCGka
Accept: application/json
Content-Type: application/json
{
"version": 2,
"name": "custom:delete:create:roles",
"description": "My custom role which gives users permissions to delete and create roles",
"permissions": [
{
"action": "roles:delete",
"scope": "permissions:delegate"
},
{
"action": "roles:create",
"scope": "permissions:delegate"
}
]
}
```
#### JSON body schema
Field Name | Data Type | Required | Description
--- | --- | --- | ---
version | number | Yes | Version of the role. Must be incremented for update to work.
name | string | Yes | Name of the role.
description | string | No | Description of the role.
permissions | List of Permissions | No | The full list of permissions the role should have after the update.
**Permission**
Field Name | Data Type | Required | Description
--- | --- | --- | ---
action | string | Yes | Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md" >}}) for full list of available actions.
scope | string | No | If not present, no scope will be mapped to the permission. Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md#scope-definitions" >}}) for full list of available scopes.
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"version": 3,
"name": "custom:delete:create:roles",
"description": "My custom role which gives users permissions to delete and create roles",
"permissions": [
{
"action": "roles:delete",
"scope": "permissions:delegate",
"updated": "2021-05-13T23:19:46.546146+02:00",
"created": "2021-05-13T23:19:46.546146+02:00"
},
{
"action": "roles:create",
"scope": "permissions:delegate",
"updated": "2021-05-13T23:19:46.546146+02:00",
"created": "2021-05-13T23:19:46.546146+02:00"
}
],
"updated": "2021-05-13T23:19:46.540987+02:00",
"created": "2021-05-13T23:19:46.540986+02:00"
}
```
#### Status codes
Code | Description
--- | --- |
200 | Role is updated.
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403 | Access denied
404 | Role was not found to update.
500 | Unexpected error. Refer to body and/or server logs for more details.
### Delete a custom role
`DELETE /api/access-control/roles/:uid?force=false`
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.
#### Required permissions
`permission:delegate` scope ensures that users can only delete a custom role with the 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 delete a custom role which allows to do that.
Action | Scope
--- | --- |
roles:delete | permissions:delegate
#### Example request
```http
DELETE /api/access-control/roles/jZrmlLCGka?force=true
Accept: application/json
```
#### Query parameters
Param | Type | Required | Description
--- | --- | --- | ---
force | boolean | No | When set to `true`, the role will be deleted with all it's assignments.
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Role deleted"
}
```
#### Status codes
Code | Description
--- | --- |
200 | Role is deleted.
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403 | Access denied
500 | Unexpected error. Refer to body and/or server logs for more details.
## Create and remove built-in role assignments
API set allows to create or remove [built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) and list current assignments.
### Get all built-in role assignments
`GET /api/access-control/builtin-roles`
Gets all built-in role assignments.
#### Required permissions
Action | Scope
--- | --- |
roles.builtin:list | roles:*
#### Example request
```http
GET /api/access-control/builtin-roles
Accept: application/json
Content-Type: application/json
```
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"Admin": [
{
"version": 1,
"uid": "qQui_LCMk",
"name": "grafana:roles:users:org:edit",
"description": "",
"global": true,
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
},
{
"version": 1,
"uid": "PeXmlYjMk",
"name": "grafana:roles:users:org:read",
"description": "",
"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": "grafana:roles:users:org:edit",
"description": "",
"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
`permission:delegate` scope ensures that users can only create built-in role assignments with the roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won't be able to create a built-in role assignment which will allow to do that. This is done to prevent escalation of privileges.
Action | Scope
--- | --- |
roles.builtin:add | permissions:delegate
#### Example request
```http
POST /api/access-control/builtin-roles
Accept: application/json
Content-Type: application/json
{
"roleUid": "LPMGN99Mk",
"builtinRole": "Grafana Admin",
"global": false
}
```
#### JSON body schema
Field Name | Date Type | Required | Description
--- | --- | --- | ---
roleUid | string | Yes | UID of the role.
builtinRole | boolean | Yes | Can be one of `Viewer`, `Editor`, `Admin` or `Grafana Admin`.
global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to create organization local assignment. Refer to the [Built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information.
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Built-in role grant added"
}
```
#### Status codes
Code | Description
--- | --- |
200 | Role was assigned to built-in role.
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403 | Access denied
404 | Role not found
500 | Unexpected error. Refer to body and/or server logs for more details.
### Remove a built-in role assignment
`DELETE /api/access-control/builtin-roles/:builtinRole/roles/:roleUID`
Deletes a built-in role assignment (for one of _Viewer_, _Editor_, _Admin_, or _Grafana Admin_) to the role with the provided UID.
#### Required permissions
`permission:delegate` scope ensures that users can only remove built-in role assignments with the roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won't be able to remove a built-in role assignment which allows to do that.
Action | Scope
--- | --- |
roles.builtin:remove | permissions:delegate
#### Example request
```http
DELETE /api/access-control/builtin-roles/Grafana%20Admin/roles/LPMGN99Mk?global=false
Accept: application/json
```
#### Query parameters
Param | Type | Required | Description
--- | --- | --- | ---
global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to remove assignment. Refer to the [Built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information.
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"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.

69
docs/sources/http_api/admin.md
View File

@ -11,6 +11,9 @@ The Admin HTTP API does not currently work with an API Token. API Tokens are cur
the permission of server admin, only users can be given that permission. So in order to use these API calls you will have to use Basic Auth and the Grafana user
must have the Grafana Admin permission. (The default admin user is called `admin` and has permission to use this API.)
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
Refer to specific resources to understand what permissions are required.
## Settings
`GET /api/admin/settings`
@ -209,6 +212,14 @@ Content-Type: application/json
Create new user. Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:create | n/a
**Example Request**:
```http
@ -243,6 +254,14 @@ Content-Type: application/json
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
Change password for a specific user.
#### Required permissions
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
users.password:update | global:users:*
**Example Request**:
```http
@ -268,6 +287,14 @@ Content-Type: application/json
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
users.permissions:update | global:users:*
**Example Request**:
```http
@ -293,6 +320,14 @@ Content-Type: application/json
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:delete | global:users:*
**Example Request**:
```http
@ -353,6 +388,14 @@ Return a list of all auth tokens (devices) that the user currently have logged i
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
users.authtoken:list | global:users:*
**Example Request**:
```http
@ -404,6 +447,14 @@ and will be required to authenticate again upon next activity.
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
users.authtoken:update | global:users:*
**Example Request**:
```http
@ -436,6 +487,14 @@ and will be required to authenticate again upon next activity.
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
users.logout | global:users:*
**Example Request**:
```http
@ -465,12 +524,22 @@ Content-Type: application/json
`POST /api/admin/provisioning/notifications/reload`
`POST /api/admin/provisioning/accesscontrol/reload`
Reloads the provisioning config files for specified type and provision entities again. It won't return
until the new provisioned entities are already stored in the database. In case of dashboards, it will stop
polling for changes in dashboard files and then restart it with new configurations after returning.
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope | Provision entity
--- | --- | ---
provisioning:reload | service:accesscontrol | accesscontrol
**Example Request**:
```http

68
docs/sources/http_api/org.md
View File

@ -5,13 +5,15 @@ keywords = ["grafana", "http", "documentation", "api", "organization"]
aliases = ["/docs/grafana/latest/http_api/organization/"]
+++
# Organization API
The Organization HTTP API is divided in two resources, `/api/org` (current organization)
and `/api/orgs` (admin organizations). One big difference between these are that
the admin of all organizations API only works with basic authentication, see [Admin Organizations API](#admin-organizations-api) for more information.
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
Refer to specific resources to understand what permissions are required.
## Current Organization API
### Get current Organization
@ -46,6 +48,14 @@ Content-Type: application/json
Returns all org users within the current organization.
Accessible to users with org admin role.
#### Required permissions
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
Action | Scope
--- | --- |
org.users:read | users:*
**Example Request**:
```http
@ -112,6 +122,14 @@ Content-Type: application/json
`PATCH /api/org/users/:userId`
#### Required permissions
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
Action | Scope
--- | --- |
org.users.role:update | users:*
**Example Request**:
```http
@ -138,6 +156,14 @@ Content-Type: application/json
`DELETE /api/org/users/:userId`
#### Required permissions
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
Action | Scope
--- | --- |
org.users:remove | users:*
**Example Request**:
```http
@ -188,6 +214,14 @@ Content-Type: application/json
Adds a global user to the current organization.
#### Required permissions
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
Action | Scope
--- | --- |
org.users:add | users:*
**Example Request**:
```http
@ -407,6 +441,14 @@ Content-Type: application/json
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
#### Required permissions
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
Action | Scope
--- | --- |
org.users:read | users:*
**Example Request**:
```http
@ -440,6 +482,14 @@ Content-Type: application/json
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
#### Required permissions
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
Action | Scope
--- | --- |
org.users:add | users:*
**Example Request**:
```http
@ -468,6 +518,14 @@ Content-Type: application/json
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
#### Required permissions
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
Action | Scope
--- | --- |
org.users.role:update | users:*
**Example Request**:
```http
@ -495,6 +553,14 @@ Content-Type: application/json
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
#### Required permissions
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
Action | Scope
--- | --- |
org.users:remove | users:*
**Example Request**:
```http

12
docs/sources/http_api/reporting.md
View File

@ -11,6 +11,8 @@ This API allows you to interact programmatically with the [Reporting]({{< relref
> Reporting is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../enterprise" >}}).
> If you have [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
Refer to specific resources to understand what permissions are required.
## Send a report
@ -22,6 +24,14 @@ This API allows you to interact programmatically with the [Reporting]({{< relref
Generate and send a report. This API waits for the report to be generated before returning. We recommend that you set the client's timeout to at least 60 seconds.
#### Required permissions
See note in the [introduction]({{< ref "#reporting-api" >}}) for an explanation.
Action | Scope
--- | --- |
reports:send | n/a
### Example request
```http
@ -63,4 +73,4 @@ Code | Description
401 | Authentication failed, refer to [Authentication API]({{< relref "../http_api/auth.md" >}}).
403 | User is authenticated but is not authorized to generate the report.
404 | Report not found.
500 | Unexpected error or server misconfiguration. Refer to body and/or server logs for more details.
500 | Unexpected error or server misconfiguration. Refer to server logs for more details.

61
docs/sources/http_api/user.md
View File

@ -5,12 +5,23 @@ keywords = ["grafana", "http", "documentation", "api", "user"]
aliases = ["/docs/grafana/latest/http_api/user/"]
+++
# User HTTP resources / actions
# User API
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
Refer to specific resources to understand what permissions are required.
## Search Users
`GET /api/users?perpage=10&page=1`
#### Required permissions
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:read | global:users:*
**Example Request**:
```http
@ -58,6 +69,14 @@ Content-Type: application/json
`GET /api/users/search?perpage=10&page=1&query=mygraf`
#### Required permissions
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:read | global:users:*
**Example Request**:
```http
@ -111,6 +130,14 @@ Content-Type: application/json
`GET /api/users/:id`
#### Required permissions
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:read | users:*
**Example Request**:
```http
@ -148,6 +175,14 @@ Content-Type: application/json
`GET /api/users/lookup?loginOrEmail=user@mygraf.com`
#### Required permissions
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:read | global:users:*
**Example Request using the email as option**:
```http
@ -195,6 +230,14 @@ Content-Type: application/json
`PUT /api/users/:id`
#### Required permissions
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:write | users:*
**Example Request**:
```http
@ -226,6 +269,14 @@ Content-Type: application/json
`GET /api/users/:id/orgs`
#### Required permissions
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:read | users:*
**Example Request**:
```http
@ -256,6 +307,14 @@ Content-Type: application/json
`GET /api/users/:id/teams`
#### Required permissions
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
Action | Scope
--- | --- |
users.teams:read | users:*
**Example Request**:
```http

2
docs/sources/manage-users/_index.md
View File

@ -9,6 +9,8 @@ Grafana offers several options for grouping users. Each level has different tool
One of the most important user management tasks is assigning roles, which govern what [permissions]({{< relref "../permissions/_index.md" >}}) a user has. The correct permissions ensure that users have access to only the resources they need.
> Refer to [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how you can manage users with fine-grained permissions.
## Server
The highest and broadest level of user group in Grafana is the server. Every user with an account in a Grafana instance is a member of the server group.

4
docs/sources/permissions/_index.md
View File

@ -8,6 +8,8 @@ weight = 50
# Permissions
> Refer to [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) in Grafana Enterprise for managing access with fine-grained permissions.
What you can do in Grafana is defined by the _permissions_ associated with your user account.
There are three types of permissions:
@ -23,6 +25,8 @@ You can be granted permissions based on:
- (Grafana Enterprise) Data source permissions. For more information, refer to [Data source permissions]({{< relref "../enterprise/datasource_permissions.md" >}}) in [Grafana Enterprise]({{< relref "../enterprise" >}}).
- (Grafana Cloud) Grafana Cloud has additional roles. For more information, refer to [Grafana Cloud roles and permissions](/docs/grafana-cloud/cloud-portal/cloud-roles/).
If you are running Grafana Enterprise, you can grant access by using fine-grained roles and permissions, refer to [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) for more information.
## Grafana Server Admin role
Grafana server administrators have the **Grafana Admin** flag enabled on their account. They can access the **Server Admin** menu and perform the following tasks:

4
docs/sources/permissions/organization_roles.md
View File

@ -7,6 +7,8 @@ weight = 100
# Organization roles
> Refer to [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) in Grafana Enterprise for managing Organization roles with fine-grained permissions.
Users can belong to one or more organizations. A user's organization membership is tied to a role that defines what the user is allowed to do in that organization. Grafana supports multiple _organizations_ in order to support a wide variety of deployment models, including using a single Grafana instance to provide service to multiple potentially untrusted organizations.
In most cases, Grafana is deployed with a single organization.
@ -36,6 +38,8 @@ The table below compares what each role can do. Read the sections below for more
| Change team settings | x | | |
| Configure app plugins | x | | |
If you are running Grafana Enterprise, you can grant and revoke access by using fine-grained roles and permissions, refer to [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) for more information.
## Organization admin role
Can do everything scoped to the organization. For example:

2
docs/sources/permissions/restricting-access.md
View File

@ -5,6 +5,8 @@ weight = 500
# Restricting access
> Refer to [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how to use fine-grained permissions to restrict access.
The highest permission always wins so if you for example want to hide a folder or dashboard from others you need to remove the **Organization Role** based permission from the Access Control List (ACL).
- You cannot override permissions for users with the Organization Admin role. Admins always have access to everything.