Assign RBAC roles

Note: Available in Grafana Enterprise and Grafana Cloud Advanced.

In this topic you’ll learn how to use the role picker, provisioning, and the HTTP API to assign fixed and custom roles to users and teams.

Assign fixed roles in the UI using the role picker

This section describes how to:

  • Assign a fixed role to a user, team or service account as an organization administrator.
  • Assign a fixed role to a user as a server administrator. This approach enables you to assign a fixed role to a user in multiple organizations, without needing to switch organizations.

In both cases, the assignment applies only to the user, team or service account within the affected organization, and no other organizations. For example, if you grant the user the Data source editor role in the Main organization, then the user can edit data sources in the Main organization, but not in other organizations.

Before you begin:

  • Plan your RBAC rollout strategy.

  • Identify the fixed roles that you want to assign to the user, team or service account.

    For more information about available fixed roles, refer to RBAC role definitions.

  • Ensure that your own user account has the correct permissions:

    • If you are assigning permissions to a user, team or service account within an organization, you must have organization administrator or server administrator permissions.
    • If you are assigning permissions to a user who belongs to multiple organizations, you must have server administrator permissions.
    • Your Grafana user can also assign fixed role if it has either the fixed:roles:writer fixed role assigned to the same organization to which you are assigning RBAC to a user, or a custom role with users.roles:add and users.roles:remove permissions.
    • Your own user account must have the roles you are granting. For example, if you would like to grant the fixed:users:writer role to a team, you must have that role yourself.

To assign a fixed role to a user, team or service account:

  1. Sign in to Grafana.

  2. Switch to the organization that contains the user, team or service account.

    For more information about switching organizations, refer to Switch organizations.

  3. Hover your cursor over Configuration (the gear icon) in the left navigation menu, and click Users or Teams or Service Accounts.

  4. In the Role column, select the fixed role that you want to assign to the user, team or service account.

  5. Click Update.

To assign a fixed role as a server administrator:

  1. Sign in to Grafana, hover your cursor over Server Admin (the shield icon) in the left navigation menu, and click Users.
  2. Click a user.
  3. In the Organizations section, select a role within an organization that you want to assign to the user.
  4. Click Update.

Assign fixed or custom roles to a team using provisioning

Instead of using the Grafana role picker, you can use file-based provisioning to assign fixed roles to teams. If you have a large number of teams, provisioning can provide an easier approach to assigning and managing role assignments.

Before you begin:

  • Refer to Role provisioning
  • Ensure that the team to which you are adding the fixed role exists. For more information about creating teams, refer to Manage teams

To assign a role to a team:

  1. Open the YAML configuration file.

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

    AttributeDescription
    rolesEnter the custom role or custom roles you want to create/update.
    roles > nameEnter the name of the custom role.
    roles > versionEnter the custom role version number. Role assignments are independent of the role version number.
    roles > globalEnter true. You can specify the orgId otherwise.
    roles > permissionsEnter the permissions action and scope values. For more information about permissions actions and scopes, refer to RBAC permissions, actions, and scopes
    teamsEnter the team or teams to which you are adding the custom role.
    teams > orgIdBecause teams belong to organizations, you must add the orgId value.
    teams > nameEnter the name of the team.
    teams > rolesEnter the custom or fixed role or roles that you want to grant to the team.
    teams > roles > nameEnter the name of the role.
    teams > roles > globalEnter true, or specify orgId of the role you want to assign to the team. Fixed roles are global.

    For more information about managing custom roles, refer to Create custom roles using provisioning.

  3. Reload the provisioning configuration file.

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

The following example creates the custom:users:writer role and assigns it to the user writers and user admins teams along with the fixed:users:writer role:

The following example:

  • Creates the custom:users:writer role.
  • Assigns the custom:users:writer role and the fixed:users:writer role to the user admins and user writers teams.
  1. # config file version
  2. apiVersion: 2
  4. # Roles to insert/update in the database
  5. roles:
  6.   - name: 'custom:users:writer'
  7.     description: 'List/update other users in the organization'
  8.     version: 1
  9.     global: true
  10.     permissions:
  11.       - action: 'org.users:read'
  12.         scope: 'users:*'
  13.       - action: 'org.users:write'
  14.         scope: 'users:*'
  16. # Assignments to teams
  17. teams:
  18.   - name: 'user writers'
  19.     orgId: 1
  20.     roles:
  21.       # Custom role assignment
  22.       - name: 'custom:users:writer'
  23.         global: true
  24.       # Fixed role assignment
  25.       - name: 'fixed:users:writer'
  26.         global: true
  27.   - name: 'user admins'
  28.     orgId: 1
  29.     roles:
  30.       - name: 'custom:users:writer'
  31.         global: true
  32.       - name: 'fixed:users:writer'
  33.         global: true

Note: The roles don’t have to be defined in the provisioning configuration files to be assigned. If roles exist in the database, they can be assigned.

Remove a role assignment from a team:

If you want to remove an assignment from a team, add state: absent to the teams > roles section, and reload the configuration file.

The following example:

  • Creates the custom:users:writer role
  • Assigns the custom:users:writer role and the fixed:users:writer role to the user admins team
  • Removes the custom:users:writer and the fixed:users:writer assignments from the user writers team, if those assignments exist.
  1. # config file version
  2. apiVersion: 2
  4. # Roles to insert/update in the database
  5. roles:
  6.   - name: 'custom:users:writer'
  7.     description: 'List/update other users in the organization'
  8.     version: 1
  9.     global: true
  10.     permissions:
  11.       - action: 'org.users:read'
  12.         scope: 'users:*'
  13.       - action: 'org.users:write'
  14.         scope: 'users:*'
  16. # Assignments to teams
  17. teams:
  18.   - name: 'user writers'
  19.     orgId: 1
  20.     roles:
  21.       - name: 'fixed:users:writer'
  22.         global: true
  23.         state: 'absent' # Remove assignment
  24.       - name: 'custom:users:writer'
  25.         global: true
  26.         state: 'absent' # Remove assignment
  27.   - name: 'user admins'
  28.     orgId: 1
  29.     roles:
  30.       - name: 'fixed:users:writer'
  31.         global: true
  32.       - name: 'custom:users:writer'
  33.         global: true

Note: The roles don’t have to be defined in the provisioning configuration files to be revoked. If roles exist in the database, they can be revoked.