Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Developers

Enterprise Open source

RBAC docs

Glossary

action - describes what user is allowed to do; examples: dashboards:read, teams:create, datasources:write.

scope - describes which resources user is allowed to apply the action to; examples dashboards:uid:test_dashboard, teams:id:1, datasources:*

permission - action + scope;

role - a set of permissions; examples: fixed:dashboards:reader, basic:viewer, custom:test_role;

fixed role - role that is automatically created by Grafana server and contains the default set of permissions necessary for a common task; examples: fixed:dashboards:reader, fixed:teams:reader [TODO link to all roles]

basic role - role that corresponds to one of legacy Grafana roles (Viewer, Editor, Admin and Grafana Admin); examples: basic:viewer, basic:grafana_admin

builtin role (deprecated) - RBAC alternative to legacy Grafana roles, has now been deprecated and replaced by basic roles;

custom role - role that has been created by a user; examples: custom:team_and_dashboard_admin;

managed permission - permissions that are created by resource permission service;

resource permission service (aka managed permission service) - service that allows assigning a set of permissions on a particular resource; examples: dashboard, team and data source resource permission services;

scope resolution -

RBAC filtering - filtering a set of resources based on user’s permissions, and only giving the user information about resources that he has access to;

RBAC metadata - a list of permissions that a user has on a resource that can be returned by the API when listing the resource, it is used by frontend;

RBAC middleware - authorisation middleware that checks whether the user has the required permissions before calling a function handler;

Access control provisioning -

Style guide

Scope naming

Action naming

Role naming

Architecture overview

Building blocks

Permissions

Most permissions are defined by an action and a scope. Action defines what the user is allowed to do (ie, read dashboards, create data sources or delete teams). Most actions correspond to creating, reading, writing or deleting a specific resource, but some of them are funkier, and allow enabling or disabling things, querying etc. Scope specifies a resource or set of resources that the permission applies to. Most of the scopes look like resource:id or resource:uid. For example, dashboards:uid:my_dash or teams:id:1. We also support wildcard scopes - dashboards:uid:* and dashboards:* both apply to all dashboards. Some permissions don’t have a scope. For instance, users:create does not require a scope.

[TODO screenshot of the DB table?]

Roles

Role is a set of permissions.

Confusingly, Grafana’s legacy access control also has roles - Viewer, Editor, Admin and Server Admin. They are still used in some parts of code and documentation. They are implemented in a different way than RBAC roles, and should not be confused for RBAC roles.

We have several different types of roles:

fixed roles - hardcoded roles that contain permissions required for common tasks, and that we thought users would find handy. Users are not able to change or delete fixed roles. You can see a full list of them in our public documentation [TODO].
custom roles - roles created by users. Users have a full control over these roles. Custom roles can be created through API or provisioning.
basic roles - RBAC roles corresponding to Grafana’s legacy access control roles. They provide a default set of permissions granted to viewers, editors, admins and server admins, and are required for an easy transition from legacy access control to RBAC. Note that basic roles can be edited by users (but cannot be deleted). Currently each user needs to have exactly one basic role assigned to them. [TODO check if it’s true]

where to check for permissions