permissions

156 notes in this subject, read out of this brain and free to use. This is page 1 of 3.

Remove team role assignment using provisioning

To remove a role assignment from a team using provisioning, add 'state: absent' to the teams > roles section in the YAML configuration file, then reload the configuration file. The roles do not need to be defined in the provisioning file to be revoked if they exist in the database.

Assign fixed role to user, team or service account in UI

To assign a fixed role in Grafana UI: 1) Sign in to Grafana. 2) Switch to the organization containing the user, team, or service account. 3) Go to Administration menu, select Users and access, then choose Users, Teams, or Service accounts. 4) In the Role column, select the fixed role to assign. 5) Click Update. The role assignment applies only within that organization.

Role assignment independence from role version

Role assignments are independent of the role version number. When provisioning role assignments, changes to the role version do not affect existing assignments.

RBAC role assignment via HTTP API

To assign fixed or custom roles via HTTP API, refer to the RBAC HTTP API endpoints: use the user role assignment endpoint to assign roles to a user or service account (service account ID can be used in place of user ID), and use the team role assignment endpoint to assign roles to a team.

Provisioning example: create custom role and assign to teams

Example YAML provisioning configuration showing how to create a custom:users:writer role with org.users:read and org.users:write permissions, then assign it along with fixed:users:writer role to user writers and user admins teams in organization 1: ```yaml apiVersion: 2 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:*' teams: - name: 'user writers' orgId: 1 roles: - name: 'custom:users:writer' global: true - name: 'fixed:users:writer' global: true - name: 'user admins' orgId: 1 roles: - name: 'custom:users:writer' global: true - name: 'fixed:users:writer' global: true ```

Permissions required to assign RBAC roles

To assign RBAC roles, your user account must have: 1) Organization administrator or server administrator permissions to assign roles within an organization; 2) Server administrator permissions to assign roles to a user in multiple organizations; 3) Either the fixed:roles:writer fixed role in the same organization, or a custom role with users.roles:add and users.roles:remove permissions; 4) The same roles you are granting to others (for example, to grant fixed:users:writer role, you must have it yourself).

Provisioning YAML attributes for team role assignment

The provisioning YAML configuration for assigning roles to teams uses these attributes: roles (custom roles to create/update), roles.name (role name), roles.version (role version number), roles.global (set to true, or specify orgId), roles.permissions (action and scope values), teams (teams to assign roles to), teams.orgId (organization ID, required as teams belong to orgs), teams.name (team name), teams.roles (custom or fixed roles to grant), teams.roles.name (role name), teams.roles.global (true or orgId, fixed roles are global).

RBAC role assignment requires planning

Before assigning RBAC roles, plan your RBAC rollout strategy and identify the fixed roles to assign. For information about available fixed roles, refer to RBAC role definitions.

Assign fixed role as server administrator to user across organizations

To assign a fixed role to a user across multiple organizations as a server administrator: 1) Sign in to Grafana as a server administrator. 2) Click Administration in the left-side menu, then Users and access, then Users. 3) Click the user. 4) In the Organizations section, click Change role. 5) Select a role within an organization to assign. 6) Click Save.

Role assignment scope is organization-specific

Role assignments apply only to the user, team, or service account within the affected organization and do not apply to other organizations. For example, granting the Data source editor role to a user in the Main organization allows the user to edit data sources only in the Main organization, not in other organizations.

Provisioning example: remove role assignments from team

Example YAML provisioning configuration showing how to remove fixed:users:writer and custom:users:writer role assignments from user writers team while keeping them assigned to user admins team: ```yaml apiVersion: 2 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:*' teams: - name: 'user writers' orgId: 1 roles: - name: 'fixed:users:writer' global: true state: 'absent' - name: 'custom:users:writer' global: true state: 'absent' - name: 'user admins' orgId: 1 roles: - name: 'fixed:users:writer' global: true - name: 'custom:users:writer' global: true ```

Basic roles cannot be assigned with grafana_role_assignment

The grafana_role_assignment resource cannot be used to assign basic roles (None, Viewer, Editor, Admin, Grafana Admin). Attempting to do so returns the error 'this endpoint cannot be used to assign basic, managed or external services roles'. Basic roles correspond to organization roles and must be managed through organization role settings instead.

RBAC provisioning available in Grafana Enterprise and Grafana Cloud

RBAC provisioning with Terraform is available in Grafana Enterprise and Grafana Cloud only, not in the open-source Grafana.

Terraform provider version requirement for RBAC provisioning

The grafana/grafana Terraform provider must be version 1.29.0 or higher to provision RBAC roles and role assignments.

Assigning fixed or custom roles to teams with Terraform

Use the grafana_role_assignment resource to assign fixed or custom roles to teams: resource "grafana_team" "writers_team" { name = "terraform_writers_team" } resource "grafana_role_assignment" "writers_team_fixed_role" { role_uid = "fixed:dashboards:writer" teams = [grafana_team.writers_team.id] }

grafana_organization resource for setting user organization roles in self-managed Grafana

In self-managed Grafana, use the grafana_organization resource to manage organization membership and user organization roles. This resource uses Grafana's admin API and manages organization membership authoritatively: resource "grafana_organization" "org" { name = "my_org" admins = ["admin@example.com"] editors = ["editor@example.com"] viewers = ["viewer@example.com"] }

Terraform grafana_role resource for custom roles

Custom roles are created using the grafana_role resource. Fields include: name (required), description, uid (optional, must be prefixed with 'custom:'), version (default 1), global (boolean, default false), and permissions blocks. Each permission block contains an action (required) and scope (optional). Example: resource "grafana_role" "my_new_role" { name = "custom:users:manager" description = "Manage organization users and teams" uid = "customusersmanager" version = 1 global = false permissions { action = "org.users:read" scope = "users:*" } }

Setting organization role for service accounts in Terraform

Set the organization role for a service account using the role attribute on the grafana_service_account resource: resource "grafana_service_account" "admin_sa" { name = "terraform_admin_sa" role = "Admin" }

Setting user organization roles in Grafana Cloud

The grafana_organization resource is not supported in Grafana Cloud. To set an individual user's organization role in Grafana Cloud, use the PATCH /api/org/users/{user_id} Organization HTTP API endpoint, or use SCIM provisioning, SAML, or OIDC role mapping.

Looking up role UIDs for existing roles in Terraform provisioning

To assign an already existing fixed or custom role without provisioning it, you can look up its uid using the API endpoint for listing roles (refer to RBAC actions and scopes API documentation) and use that uid in a grafana_role_assignment resource. Similarly, you can look up and use IDs of users, teams, and service accounts that have not been provisioned.

Terraform grafana_role_assignment resource fields

The grafana_role_assignment resource has the following fields: role_uid (required, string), users (optional, list of user IDs), teams (optional, list of team IDs), service_accounts (optional, list of service account IDs). At least one of users, teams, or service_accounts must be specified.

Service account token recommended for RBAC Terraform provisioning

Service account tokens are the recommended authentication method for provisioning RBAC with Terraform in both self-managed Grafana and Grafana Cloud. Service accounts support fine-grained permissions, allowing the minimum set of permissions needed for provisioning.

Required roles for service account provisioning RBAC

A service account used for RBAC provisioning must have at least the roles 'Role reader' and 'Role writer'. If provisioning roles that grant specific permissions, the service account must also have permissions matching those actions. Alternatively, the Admin basic role can be assigned to the service account.

Minimum Grafana version for RBAC provisioning

Grafana version 9.2 or higher is required to provision RBAC with Terraform.

Terraform provider configuration with environment variables

The Grafana Terraform provider can read credentials from the GRAFANA_URL and GRAFANA_AUTH environment variables. Example provider block: terraform { required_providers { grafana = { source = "grafana/grafana" version = ">= 1.29.0" } } } provider "grafana" {} Then export environment variables before running Terraform: export GRAFANA_URL="https://your-instance.grafana.net" export GRAFANA_AUTH="glsa_token_string"

Synchronize RBAC through authentication providers

You can leverage authentication providers to manage user and team permissions in Grafana: map SAML, LDAP, or OAuth roles to Grafana basic roles (viewer, editor, or admin); use Grafana Enterprise team sync to synchronize teams from SAML, LDAP, or OAuth providers to Grafana; then assign RBAC permissions to users and teams within Grafana.

Example: Manage user permissions through teams

To grant access by team membership: 1. Ensure auto_assign_org=true, set auto_assign_org_id, and set auto_assign_org_role=None in configuration. 2. Restart Grafana. 3. Create a team with desired name. 4. Assign fixed roles to the team. 5. Add users to the team. Users will be added to default organization automatically but won't have permissions until assigned to a team.

Example: Revoke viewer app plugin access via provisioning

YAML provisioning file to remove all app plugin access and grant specific plugin access for basic:viewer: ```yaml --- apiVersion: 2 roles: - name: 'basic:viewer' version: 8 global: true from: - name: 'basic:viewer' global: true permissions: - action: 'plugins.app:access' scope: 'plugins:*' state: 'absent' - action: 'plugins.app:access' scope: 'plugins:id:kentik-connect-app' state: 'present' ```

Example: Reduce scope of service accounts

To limit service account scope: 1. Create a Service Account with 'None' basic role. 2. Assign only the necessary fixed roles to the Service Account. This reduces required permissions and minimizes risk of compromise.

When to modify basic roles versus create custom roles

Modify basic roles when Grafana's definitions of viewers, editors, and admins do not match your organization's definition. Create custom roles when fixed role definitions do not meet permissions requirements. Example: if fixed:dashboards:writer allows deletion but you want users to create and update dashboards only, create custom:dashboards:creator without the dashboards:delete permission.

Assign roles to teams for organizational alignment

Assign roles to teams when you have a subset of users that align to your organizational structure and you want all team members to have the same access level. When additional users are assigned to a team, the system automatically assigns permissions to those users. Example: all members of an engineering team need fixed:reports:reader and fixed:reports:writer roles.

Assign roles to users when one-off scenarios

Assign roles to users when you have a one-off scenario where a small number of users require access to a resource or when you want to assign temporary access. This approach becomes difficult to manage as you scale Grafana usage with large numbers of users. Example: IT department member needs fixed:licensing:reader and fixed:licensing:writer roles to manage Grafana Enterprise license.

Note on fixed:reports:writer role scope

The fixed:reports:writer role assigns more permissions than just creating reports. Refer to fixed role definitions documentation for complete permission assignments.

Example: Prevent viewers from accessing an App Plugin

By default, Viewers, Editors, and Admins have access to all App Plugins their organization role allows. To prevent Viewers from accessing a specific App plugin: 1. Remove the permission plugins.app:access with scope plugins:* from basic:viewer. 2. Grant permission plugins.app:access with scope plugins:id:<plugin-id> for only the allowed plugins.

RBAC rollout strategy key questions

An RBAC rollout strategy helps determine how to implement RBAC before assigning roles to users and teams. The strategy should answer: Should basic roles or fixed/custom roles be assigned to users? When should custom roles be created? Which entities should receive fixed and custom roles? How can permissions be rolled out for easy management? Which assignment approach should be used: Grafana UI, provisioning, or API?

Example: Prevent admin user creation via provisioning

YAML provisioning file to remove user creation permissions from basic:grafana_admin: ```yaml apiVersion: 2 roles: - name: 'basic:grafana_admin' global: true version: 3 from: - name: 'basic:grafana_admin' global: true permissions: - action: 'users:create' state: 'absent' - action: 'org.users:add' scope: 'users:*' state: 'absent' ```

Example: Prevent admin user creation via API

Bash script to fetch basic_grafana_admin role, remove user creation permissions using jq, and update via API: ```bash # Fetch the role, modify it to remove the undesired permissions and increment its version curl -H 'Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697' \ -X GET '<grafana_url>/api/access-control/roles/basic_grafana_admin' | \ jq 'del(.created)| del(.updated) | del(.permissions[].created) | del(.permissions[].updated) | .version += 1' | \ jq 'del(.permissions[] | select (.action == "users:create")) | del(.permissions[] | select (.action == "org.users:add" and .scope == "users:*"))' > /tmp/basic_grafana_admin.json # Update the role curl -H 'Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697' -H 'Content-Type: application/json' \ -X PUT -d @/tmp/basic_grafana_admin.json '<grafana_url>/api/access-control/roles/basic_grafana_admin' ```

Example: Prevent Grafana Admin from creating and inviting users

To prevent Grafana Admin from creating users and inviting them to an organization, remove these permissions from basic:grafana_admin: users:create (no scope) and org.users:add with scope users:*.

Service accounts security best practice

Using Service Accounts for M2M communications is efficient, but they can pose a security threat if not properly scoped. Begin by creating a Service Account with None basic role, then assign only the necessary permissions.

Example: Enable viewers to create reports via API

Bash script to fetch basic_viewer role, add report permissions using jq, and update via API: ```bash # Fetch the role, modify it to add the desired permissions and increment its version curl -H 'Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697' \ -X GET '<grafana_url>/api/access-control/roles/basic_viewer' | \ jq 'del(.created)| del(.updated) | del(.permissions[].created) | del(.permissions[].updated) | .version += 1' | \ jq '.permissions += [{"action": "reports:create"}, {"action": "reports:read", "scope": "reports:*"}, {"action": "reports:write", "scope": "reports:*"}, {"action": "reports:send", "scope": "reports:*"}]' > /tmp/basic_viewer.json # Update the role curl -H 'Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697' -H 'Content-Type: application/json' \ -X PUT -d @/tmp/basic_viewer.json '<grafana_url>/api/access-control/roles/basic_viewer' ```

Permissions for viewers to create reports

To enable Viewers to create reports, add these permissions to basic:viewer role: reports:create (no scope), reports:write with scope reports:* and reports:id:*, and reports:read with scope reports:*. This can be done via RBAC HTTP API or provisioning by inheriting from fixed:reports:writer role.

Constraint on custom role creation and modification

Any user or service account with ability to modify roles can only create, update, or delete roles with permissions they have been granted. For example, a user with Editor role can only create and manage roles with permissions they have or with a subset of them.

Example: Enable editors to create custom roles via provisioning

YAML provisioning file to add fixed:roles:writer role permissions to basic:editor: ```yaml apiVersion: 2 roles: - name: 'basic:editor' global: true version: 3 from: - name: 'basic:editor' global: true - name: 'fixed:roles:writer' global: true ```

Example: Enable editors to create custom roles via API

Bash script to fetch basic_editor role, add role management permissions using jq, and update via API: ```bash # Fetch the role, modify it to add the desired permissions and increment its version curl -H 'Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697' \ -X GET '<grafana_url>/api/access-control/roles/basic_editor' | \ jq 'del(.created)| del(.updated) | del(.permissions[].created) | del(.permissions[].updated) | .version += 1' | \ jq '.permissions += [{"action": "roles:read", "scope": "roles:*"}, {"action": "roles:write", "scope": "permissions:type:delegate"}, {"action": "roles:delete", "scope": "permissions:type:delegate"}]' > /tmp/basic_editor.json # Update the role curl -H 'Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697' -H 'Content-Type: application/json' \ -X PUT -d @/tmp/basic_editor.json '<grafana_url>/api/access-control/roles/basic_editor' ```

Permissions required for editors to create custom roles

By default, only Grafana Server Admin can create and manage custom roles. To enable Editors to create custom roles, add these permissions to the basic:editor role: roles:read with scope roles:*, roles:write with scope permissions:type:delegate, and roles:delete with scope permissions:type:delegate. This can be done via RBAC HTTP API or provisioning by inheriting from fixed:roles:writer role.

Example: Enable viewers to create reports via provisioning

YAML provisioning file to add fixed:reports:writer role permissions to basic:viewer: ```yaml apiVersion: 2 roles: - name: 'basic:viewer' global: true version: 3 from: - name: 'basic:viewer' global: true - name: 'fixed:reports:writer' global: true ```

Custom role for alert access in specific folder via API

Example curl request to create a custom role with alert and datasource access: ``` curl --location --request POST '<grafana_url>/api/access-control/roles/' \ --header 'Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697' \ --header 'Content-Type: application/json' \ --data-raw '{ "version": 1, "name": "custom:alerts.reader.in.folder.123", "displayName": "Read-only access to alerts in folder Test-Folder", "description": "Let user query DS1 and DS2, and read alerts in folder Test-Folders", "group":"Custom", "global": false, "permissions": [ { "action": "folders:read", "scope": "folders:uid:YEcBGYU22" }, { "action": "alert.rules:read", "scope": "folders:uid:YEcBGYU22" }, { "action": "datasources:query", "scope": "datasources:uid:_oAfGYUnk" }, { "action": "datasources:query", "scope": "datasources:uid:YYcBGYUnk" } ] }' ``` This example creates a role for a Test-Folder with ID 92 containing an alert rule that queries two data sources (DS1 with UID _oAfGYUnk and DS2 with UID YYcBGYUnk).

Example: Assign user-specific set of roles

1. Create a user with 'No Basic Role' selected under organization roles. 2. Assign the user a set of fixed roles that meet requirements.

Example: Provide dashboards across multiple geographies

1. Create a folder for each geography (e.g., 'US' folder and 'EU' folder). 2. Add dashboards to each folder. 3. Use folder permissions to add US-based users as Editors to the 'US' folder and EU-based users as Editors to the 'EU' folder.

Example: Only alert managers team can manage alerts

1. Create an 'Alert Managers' team and assign all applicable alerting fixed roles to it. 2. Add users to the team. 3. Remove all permissions with actions prefixed with 'alert.' from Viewer, Editor, and Admin basic roles.

Example: Limit viewer, editor, or admin permissions

Review the permissions associated with the basic role and change the permissions of the basic role.

Example: Provide internal viewers Explore access, prevent external contractors

1. Create a team named 'Internal employees'. 2. Assign fixed:datasources:explorer role to the team. 3. Add internal employees to the team or map from SAML/LDAP/OAuth using Team Sync. 4. Assign viewer role to both internal employees and contractors.

Methods to assign RBAC roles

RBAC roles can be assigned using four methods: Grafana UI (for limited role assignments with a role picker), Grafana HTTP API (to automate role assignment), Terraform (to assign and manage role assignments if using Terraform for provisioning), or Grafana provisioning (robust approach to assign, remove, and delete roles in a single YAML file).

Example: Revoke viewer app plugin access via API

Bash script to fetch basic_viewer role, remove all app access, and grant specific app access using jq: ```bash # Fetch the role, modify it to remove the undesired permissions, add the new permission and increment its version curl -H 'Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697' \ -X GET '<grafana_url>/api/access-control/roles/basic_viewer' | \ jq 'del(.created)| del(.updated) | del(.permissions[].created) | del(.permissions[].updated) | .version += 1' | \ jq 'del(.permissions[] | select (.action == "plugins.app:access" and .scope == "plugins:*"))' | \ jq '.permissions += [{"action": "plugins.app:access", "scope": "plugins:id:kentik-connect-app"}]' > /tmp/basic_viewer.json # Update the role curl -H 'Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697' -H 'Content-Type: application/json' \ -X PUT -d @/tmp/basic_viewer.json '<grafana_url>/api/access-control/roles/basic_viewer' ```

Basic role 'No Basic Role' cannot be modified

The 'No Basic Role' permissions cannot be modified or updated. It is a role without permissions.

Example: Remove app plugin access via provisioning

To remove access to a specific app plugin via provisioning, remove the permission from the role and update it. Bash script to fetch role, remove specific app permission, and update: ```bash # Fetch the role, modify it to remove permissions to kentik-connect-app and increment role version curl -H 'Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697' \ -X GET '<grafana_url>/api/access-control/roles/basic_viewer' | \ jq 'del(.created)| del(.updated) | del(.permissions[].created) | del(.permissions[].updated) | .version += 1' | \ jq 'del(.permissions[] | select (.action == "plugins.app:access" and .scope == "plugins:id:kentik-connect-app"))' # Update the role curl -H 'Authorization: Bearer glsa_iNValIdinValiDinvalidinvalidinva_5b582697' -H 'Content-Type: application/json' \ -X PUT -d @/tmp/basic_viewer.json '<grafana_url>/api/access-control/roles/basic_viewer' ```

Impact of modifying basic roles across organizations

Changes made to basic roles impact the role definition for all organizations in the Grafana instance. For example, if you add fixed:users:writer permissions to the viewer basic role, all viewers in any organization can create users within that org.

Configuration settings for team-based permission management

To enable team-based permission management: ``` [users] # Set to true to automatically assign new users to the default organization (id 1) auto_assign_org = true # Set this value to automatically add new users to the provided organization (if auto_assign_org above is set to true) auto_assign_org_id = <org_id> # Default role new users will be automatically assigned (if auto_assign_org above is set to true) auto_assign_org_role = None ```

Team Folders tab on team details page

Each team page includes a Folders tab that lists all folders owned by that team, showing Name and Full path columns.

Team folders in folder picker

When saving or moving a dashboard, the folder picker shows a 'Team folders' section at the top of the folder tree. Your first team folder is preselected by default.

Give your agent this brain