Manage RBAC roles

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

    The following example includes the base64 username:password Basic Authorization. You cannot use authorization tokens in the request.

    Use a command to see the actions and scopes associated with a role. For more information about seeing a list of permissions for each role, refer to .

    To see the permissions associated with basic roles, refer to the following basic role UIDs:

    Example request

    Example response

    1. {
    2.     "version": 2,
    3.     "uid": "qQui_LCMk",
    4.     "name": "fixed:users:writer",
    5.     "displayName": "User writer",
    6.     "description": "Read and update all attributes and settings for all users in Grafana: update user information, read user information, create or enable or disable a user, make a user a Grafana administrator, sign out a user, update a user’s authentication token, or update quotas for all users.",
    7.     "global": true,
    8.     "permissions": [
    9.         {
    10.             "action": "org.users:add",
    11.             "scope": "users:*",
    12.             "updated": "2021-05-17T20:49:18+02:00",
    13.             "created": "2021-05-17T20:49:18+02:00"
    14.         },
    15.         {
    16.             "action": "org.users:read",
    17.             "scope": "users:*",
    18.             "updated": "2021-05-17T20:49:18+02:00",
    19.             "created": "2021-05-17T20:49:18+02:00"
    20.         },
    21.         {
    22.             "action": "org.users:remove",
    23.             "scope": "users:*",
    24.             "updated": "2021-05-17T20:49:18+02:00",
    25.             "created": "2021-05-17T20:49:18+02:00"
    26.         },
    27.         {
    28.             "action": "org.users:write",
    29.             "scope": "users:*",
    30.             "updated": "2021-05-17T20:49:18+02:00",
    31.             "created": "2021-05-17T20:49:18+02:00"
    32.         }
    33.     ],
    34.     "updated": "2021-05-17T20:49:18+02:00",
    35.     "created": "2021-05-13T16:24:26+02:00"
    36. }

    Refer to the RBAC HTTP API for more details.

    This section shows you how to create a custom RBAC role using Grafana provisioning and the HTTP API.

    Create a custom role when basic roles and fixed roles do not meet your permissions requirements.

    Before you begin:

    • Plan your RBAC rollout strategy.
    • Determine which permissions you want to add to the custom role. To see a list of actions and scope, refer to .
    • Enable role provisioning.
    • Ensure that you have permissions to create a custom role.
      • By default, the Grafana Admin role has permission to create custom roles.
      • A Grafana Admin can delegate the custom role privilege to another user by creating a custom role with the relevant permissions and adding the permissions:type:delegate scope.

    File-based provisioning is one method you can use to create custom roles.

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

    1. Reload the provisioning configuration file.

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

    1. # config file version
    2. apiVersion: 2
    4. roles:
    5.   - name: custom:users:writer
    6.     description: 'List, create, or update other users.'
    7.     version: 1
    8.     orgId: 1
    9.     permissions:
    10.       - action: 'users:read'
    11.         scope: 'global.users:*'
    12.       - action: 'users:write'
    13.         scope: 'global.users:*'
    14.       - action: 'users:create'

    The following example creates a hidden global role. The global: true option creates a global role, and the hidden: true option hides the role from the role picker.

    The following example creates a global role based on other fixed roles. The from option contains the roles from which we want to copy permissions. The permission state: absent option can be used to specify permissions to exclude from the copy.

    1. # config file version
    2. apiVersion: 2
    4. roles:
    5.   - name: custom:org.users:writer
    6.     description: 'List and remove other users from the organization.'
    7.     version: 1
    8.     global: true
    9.     from:
    10.       - name: 'fixed:org.users:reader'
    11.         global: true
    12.       - name: 'fixed:org.users:writer'
    13.         global: true
    14.     permissions:
    15.       - action: 'org.users:write'
    16.         scope: 'users:*'
    17.         state: 'absent'
    18.       - action: 'org.users:add'
    19.         scope: 'users:*'
    20.         state: 'absent'

    Create custom roles using the HTTP API

    The following examples show you how to create a custom role using the Grafana HTTP API. For more information about the HTTP API, refer to Create a new custom role.

    The following example creates a custom:users:admin role and assigns the users:create action to it.

    Example request

    1. curl --location --request POST '<grafana_url>/api/access-control/roles/' \
    2. --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
    3. --header 'Content-Type: application/json' \
    4. --data-raw '{
    5.     "version": 1,
    6.     "uid": "jZrmlLCkGksdka",
    7.     "name": "custom:users:admin",
    8.     "displayName": "custom users admin",
    9.     "description": "My custom role which gives users permissions to create users",
    10.     "global": true,
    11.     "permissions": [
    12.         {
    13.             "action": "users:create"
    14.         }
    15.     ]

    Example response

    Refer to the for more details.

    If the default basic role definitions do not meet your requirements, you can change their permissions.

    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 .

    To change permissions from 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.

    3. Reload the provisioning configuration file.

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

    • Permissions to list, grant, and revoke roles to teams are removed.
    • Permission to read and write Grafana folders is added.
    1. # config file version
    2. apiVersion: 2
    4. roles:
    5.   - name: 'basic:grafana_admin'
    6.     global: true
    7.     version: 3
    8.     from:
    9.       - name: 'basic:grafana_admin'
    10.         global: true
    11.     permissions:
    12.       # Permissions to remove
    13.       - action: 'teams.roles:read'
    14.         scope: 'teams:*'
    15.         state: 'absent'
    16.       - action: 'teams.roles:remove'
    17.         scope: 'permissions:type:delegate'
    18.         state: 'absent'
    19.       - action: 'teams.roles:add'
    20.         scope: 'permissions:type:delegate'
    21.         state: 'absent'
    22.       # Permissions to add
    23.       - action: 'folders:read'
    24.         scope: 'folder:*'
    25.       - action: 'folders:write'
    26.         scope: 'folder:*'

    You can also change basic roles’ permissions using the API. Refer to the for more details.

    This section describes how to reset the basic roles to their default:

    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.

      1. apiVersion: 2
      2. roles:
      3.   - name: 'basic:grafana_admin'
      4.     global: true
      5.     version: 3
      6.     from:
      7.       - name: 'basic:grafana_admin'
      8.         global: true
      9.     permissions:
      10.       # Permission allowing to reset basic roles
      11.       - action: 'roles:write'
      12.        scope: 'permissions:type:escalate'

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

    Delete a custom role when you no longer need it. When you delete a custom role, the custom role is removed from users and teams to which it is assigned.

    Before you begin:

    • Identify the role or roles that you want to delete.
    • Ensure that you have access to the YAML configuration file.

    To delete a custom role:

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

    2. Reload the provisioning configuration file.

      For more information about reloading the provisioning configuration at runtime, refer to .

    The following example deletes a custom role:

    You can also delete a custom role using the API. Refer to the RBAC HTTP API for more details.