Menu

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.

Enterprise Open source

Assign RBAC roles

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 or team 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 or team 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.

Note: After you apply your changes, user and team permissions update immediately, and the UI reflects the new permissions the next time they reload their browser or visit another page.


Before you begin:

  • Plan your RBAC rollout strategy.

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

    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 or team 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 or team:

  1. Sign in to Grafana.

  2. Switch to the organization that contains the user or team.

    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.

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

  5. Click Update.

User role picker in an organization

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.

User role picker in Organization

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.
yaml
# config file version
apiVersion: 2

# Roles to insert/update in the database
roles:
  - name: 'custom:users:writer'
    description: 'List/update other users in the organization'
    version: 1
    global: true
    permissions:
      - action: 'org.users:read'
        scope: 'users:*'
      - action: 'org.users:write'
        scope: 'users:*'

# Assignments to teams
teams:
  - name: 'user writers'
    orgId: 1
    roles:
      # Custom role assignment
      - name: 'custom:users:writer'
        global: true
      # Fixed role assignment
      - name: 'fixed:users:writer'
        global: true
  - name: 'user admins'
    orgId: 1
    roles:
      - name: 'custom:users:writer'
        global: true
      - name: 'fixed:users:writer'
        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.
yaml
# config file version
apiVersion: 2

# Roles to insert/update in the database
roles:
  - name: 'custom:users:writer'
    description: 'List/update other users in the organization'
    version: 1
    global: true
    permissions:
      - action: 'org.users:read'
        scope: 'users:*'
      - action: 'org.users:write'
        scope: 'users:*'

# Assignments to teams
teams:
  - name: 'user writers'
    orgId: 1
    roles:
      - name: 'fixed:users:writer'
        global: true
        state: 'absent' # Remove assignment
      - name: 'custom:users:writer'
        global: true
        state: 'absent' # Remove assignment
  - name: 'user admins'
    orgId: 1
    roles:
      - name: 'fixed:users:writer'
        global: true
      - name: 'custom:users:writer'
        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.