Manage RBAC roles

{{< admonition type="note" >}} Available in Grafana Enterprise and Grafana Cloud. {{< /admonition >}}

This section includes instructions for how to view permissions associated with roles, create custom roles, and update and delete roles.

View basic role definitions

You can retrieve the full definition of a basic role, including all associated permissions, using the API or by navigating directly to the endpoint URL in your browser while logged in as an Admin.

Using the API

To get the definition of a basic role:

GET /api/access-control/roles/basic_<role>

Where <role> is one of: viewer, editor, admin, or grafana_admin.

For example, to get the Viewer role definition:

curl --location 'https://<your-stack-name>.grafana.net/api/access-control/roles/basic_viewer' \
  --header 'Authorization: Bearer <service-account-token>'

Using the browser

You can also view the role definition directly in your browser by navigating to:

https://<your-stack-name>.grafana.net/api/access-control/roles/basic_viewer

This works when logged in as an Admin user.

For more information, refer to Get a role.

For a reference of basic and fixed role assignments, refer to RBAC role definitions.

Update role permissions

If the default basic role permissions don't meet your requirements you can change them.

You can change basic roles' permissions via the configuration file or using the RBAC API.

Update basic role permissions in the configuration file

Before you begin, determine the permissions you want to add or remove from a basic role. For more information about the permissions associated with basic roles, refer to RBAC role definitions.

{{< admonition type="note" >}} You cannot modify the None permissions. {{< /admonition >}}

To change permissions for a basic role:

1. Open the YAML configuration file and locate the roles section.

2. Refer to the following table to add attributes and values.

   Attribute	Description
   name	The name of the basic role you want to update. You can specify a uid instead of a role name. The role name or the uid are required.
   orgId	Identifies the organization to which the role belongs. global can be used instead to specify it's a global role.
   version	Identifies the version of the role, which prevents overwriting newer changes.
   overrideRole	If set to true, role will be updated regardless of its version in the database. There is no need to specify version if overrideRole is set to true.
   from	List of roles from which to copy permissions.
   permissions > state	The state of the permission. You can set it to absent to ensure it exclusion from the copy list.

3. Reload the provisioning configuration file. For more information about reloading the provisioning configuration at runtime, refer to Reload provisioning configurations.

Example: Modify the Grafana Admin role

The following example modifies the Grafana Admin basic role permissions.

In the new configuration:

• Permissions to list, grant, and revoke roles to teams are removed.
• Permission to read and write Grafana folders is added.

# config file version
apiVersion: 2

roles:
  - name: 'basic:grafana_admin'
    global: true
    version: 3
    from:
      - name: 'basic:grafana_admin'
        global: true
    permissions:
      # Permissions to remove
      - action: 'teams.roles:read'
        scope: 'teams:*'
        state: 'absent'
      - action: 'teams.roles:remove'
        scope: 'permissions:type:delegate'
        state: 'absent'
      - action: 'teams.roles:add'
        scope: 'permissions:type:delegate'
        state: 'absent'
      # Permissions to add
      - action: 'folders:read'
        scope: 'folder:*'
      - action: 'folders:write'
        scope: 'folder:*'

{{< admonition type="note" >}} You can add multiple fixed, basic or custom roles to the from section. Their permissions will be copied and added to the basic role. Make sure to increment the role version for the changes to be accounted for. {{< /admonition >}}

Update basic role permissions using the RBAC API

Refer to the RBAC HTTP API for more details.

Reset basic roles to their default

You have two options to reset the basic roles permissions to their default.

Use the configuration option

Note: Available as of Grafana Enterprise 9.4.

Warning: If this option is left to true, permissions will be reset on every boot.

Use the reset_basic_roles option to reset basic roles permissions to their default on Grafana instance boot up.

1. Open you configuration file and update the rbac section as follow:

[rbac]
reset_basic_roles = true

Use the HTTP endpoint

An alternative to the configuration option is to use the HTTP endpoint.

1. Open the YAML configuration file and locate the roles section.

2. Grant the action: "roles:write", scope: "permissions:type:escalate permission to Grafana Admin. Note that this permission has not been granted to any basic roles by default, because users could acquire more permissions than they previously had through the basic role permissions reset.

   yamlCopy

   apiVersion: 2
   roles:
     - name: 'basic:grafana_admin'
       global: true
       version: 3
       from:
         - name: 'basic:grafana_admin'
           global: true
       permissions:
         # Permission allowing to reset basic roles
         - action: 'roles:write'
           scope: 'permissions:type:escalate'
   

3. As a Grafana Admin, call the API endpoint to reset the basic roles to their default. Refer to the RBAC HTTP API for more details.