Create custom RBAC roles

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

Create a custom RBAC role when basic roles and fixed roles do not meet your permissions requirements. For a list of the actions and scopes you can customize a role with, refer to Grafana RBAC permission actions and scopes.

{{< admonition type="caution" >}} Before creating custom roles, consider whether you can meet your access requirements using:

• Folder permissions: Control access to dashboards, alert rules, and other resources by folder
• Fixed roles: Pre-built roles for common access patterns

Use custom roles only when you need fine-grained control that these options don't provide. {{< /admonition >}}

Creating and editing custom roles is not currently possible in the Grafana UI. Instead, use one of the following methods:

• The RBAC HTTP API
• Terraform
• Grafana provisioning using a YAML file

Before you begin

Before you begin, keep in mind the following:

• 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 RBAC permissions, actions, and scopes.
• 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.

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.

{{< admonition type="note" >}} When you create a custom role you can only give it the same permissions you already have. For example, if you only have users:create permissions, then you can't create a role that includes other permissions. {{< /admonition >}}

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

Example 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",
    "displayName": "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",
    "displayName": "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"
}

Refer to the RBAC HTTP API for more details.

Create custom roles using Terraform

You can use the Grafana Terraform provider to manage custom roles and their assignments. This is the recommended method for Grafana Cloud users who want to manage RBAC as code. For more information, refer to Provisioning RBAC with Terraform.

The following example creates a custom role and assigns it to a team:

resource "grafana_role" "custom_folder_manager" {
  name        = "custom:folders:manager"
  description = "Custom role for reading and creating folders"
  uid         = "custom-folders-manager"
  version     = 1
  global      = true

  permissions {
    action = "folders:read"
    scope  = "folders:*"
  }

  permissions {
    action = "folders:create"
    scope  = "folders:uid:general" # Allows creating folders at the root level
  }
}

resource "grafana_role_assignment" "custom_folder_manager_assignment" {
  role_uid = grafana_role.custom_folder_manager.uid
  teams    = ["<TEAM_UID>"]
}

For more information, refer to the grafana_role and grafana_role_assignment documentation in the Terraform Registry.

Create custom roles using file-based provisioning

You can use file-based provisioning to create custom roles for self-managed instances.

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

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

1. Reload the provisioning configuration file.

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

The following example creates a local role:

# config file version
apiVersion: 2

roles:
  - name: custom:users:writer
    description: 'List, create, or update other users.'
    version: 1
    orgId: 1
    permissions:
      - action: 'users:read'
        scope: 'global.users:*'
      - action: 'users:write'
        scope: 'global.users:*'
      - 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.

# config file version
apiVersion: 2

roles:
  - name: custom:users:writer
    description: 'List, create, or update other users.'
    version: 1
    global: true
    hidden: true
    permissions:
      - action: 'users:read'
        scope: 'global.users:*'
      - action: 'users:write'
        scope: 'global.users:*'
      - action: 'users:create'

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.

# config file version
apiVersion: 2

roles:
  - name: custom:org.users:writer
    description: 'List and remove other users from the organization.'
    version: 1
    global: true
    from:
      - name: 'fixed:org.users:reader'
        global: true
      - name: 'fixed:org.users:writer'
        global: true
    permissions:
      - action: 'org.users:write'
        scope: 'users:*'
        state: 'absent'
      - action: 'org.users:add'
        scope: 'users:*'
        state: 'absent'

Delete a custom role using Grafana provisioning

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. Refer to the following table to add attributes and values.

   Attribute	Description
   name	The name of the custom role you want to delete. 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.
   state	The state of the role set to absent to trigger its removal.
   force	When set to true, the roles are removed even if there are existing assignments.

3. Reload the provisioning configuration file.

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

The following example deletes a custom role:

# config file version
apiVersion: 2

roles:
  - name: 'custom:reports:editor'
    orgId: 1
    state: 'absent'
    force: true

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