Provisioning

You can create, change or remove Custom roles and create or remove built-in role assignments, by adding one or more YAML configuration files in the provisioning/access-control/ directory. Refer to Grafana provisioning to learn more about provisioning.

If you want to manage roles and built-in role assignments by API, refer to the Fine-grained access control HTTP API.

Configuration

The configuration files must be placed in provisioning/access-control/. Grafana performs provisioning during the startup. Refer to the Reload provisioning configurations to understand how you can reload configuration at runtime.

Manage custom roles

You can create, update, and delete custom roles, as well as create and remove built-in role assignments.

Create or update roles

To create or update custom roles, you can add a list of roles in the configuration.

Every role has a version number. For each role you update, you must remember to increment it, otherwise changes won’t be applied.

When you update a role, the existing role inside Grafana is altered to be exactly what is specified in the YAML file, including permissions.

Here is an example YAML file to create a local role with a set of permissions:

  1. # config file version
  2. apiVersion: 1
  4. # Roles to insert into the database, or roles to update in the database
  5. roles:
  6.   - name: custom:users:editor
  7.     description: 'This role allows users to list, create, or update other users within the organization.'
  8.     version: 1
  9.     orgId: 1
  10.     permissions:
  11.       - action: 'users:read'
  12.         scope: 'users:*'
  13.       - action: 'users:write'
  14.         scope: 'users:*'
  15.       - action: 'users:create'
  16.         scope: 'users:*'

Here is an example YAML file to create a global role with a set of permissions, where the global:true option makes a role global:

  1. # config file version
  2. apiVersion: 1
  4. # Roles to insert into the database, or roles to update in the database
  5. roles:
  6.   - name: custom:users:editor
  7.     description: 'This role allows users to list, create, or update other users within the organization.'
  8.     version: 1
  9.     global: true
  10.     permissions:
  11.       - action: 'users:read'
  12.         scope: 'users:*'
  13.       - action: 'users:write'
  14.         scope: 'users:*'
  15.       - action: 'users:create'
  16.         scope: 'users:*'

The orgId is lost when the role is set to global.

Delete roles

To delete a role, add a list of roles under the deleteRoles section in the configuration file.

Note: Any role in the deleteRoles section is deleted before any role in the roles section is saved.

Here is an example YAML file to delete a role:

  1. # config file version
  2. apiVersion: 1
  4. # list of roles that should be deleted
  5. deleteRoles:
  6.   - name: custom:reports:editor
  7.     orgId: 1
  8.     force: true

Assign your custom role to specific built-in roles

To assign roles to built-in roles, add said built-in roles to the builtInRoles section of your roles. To remove a specific assignment, remove it from the list.

Note: Assignments are updated if the version of the role is greater or equal to the one stored internally. You don’t need to increment the version number of the role to update its assignments.

For example, the following role is assigned to an organization editor or an organization administrator:

  1. # config file version
  2. apiVersion: 1
  4. # Roles to insert/update in the database
  5. roles:
  6.   - name: custom:users:editor
  7.     description: 'This role allows users to list/create/update other users in the organization'
  8.     version: 1
  9.     orgId: 1
  10.     permissions:
  11.       - action: 'users:read'
  12.         scope: 'users:*'
  13.       - action: 'users:write'
  14.         scope: 'users:*'
  15.       - action: 'users:create'
  16.         scope: 'users:*'
  17.     builtInRoles:
  18.       - name: 'Editor'
  19.       - name: 'Admin'

Assign your custom role to specific teams

To assign roles to teams, add said teams to the teams section of your roles. To remove a specific assignment, remove it from the list.

Note: Assignments are updated if the version of the role is greater or equal to the one stored internally.
You don’t need to increment the version number of the role to update its assignments.
Assignments to built-in roles will be ignored. Use addDefaultAssignments and removeDefaultAssignments instead.

In order for provisioning to succeed, specified teams must already exist. Additionally, since teams are local to an organization, the organization has to be specified in the assignment.

For example, the following role is assigned to the user editors team and user admins team:

  1. # config file version
  2. apiVersion: 1
  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:*'
  15.     teams:
  16.       - name: 'user editors'
  17.         orgId: 1
  18.       - name: 'user admins'
  19.         orgId: 1

Assign fixed roles to specific teams

To assign a fixed role to teams, add said teams to the teams section of the associated entry. To remove a specific assignment, remove it from the list.

Note: Since fixed roles are global, the Global attribute has to be specified. A fixed role will never be updated through provisioning.

In order for provisioning to succeed, specified teams must already exist. Additionally, since teams are local to an organization, the organization has to be specified in the assignment.

For example, the following fixed role is assigned to the user editors team and user admins team:

  1. # config file version
  2. apiVersion: 1
  4. # Roles to insert/update in the database
  5. roles:
  6.   - name: fixed:users:writer
  7.     global: true
  8.     teams:
  9.       - name: 'user editors'
  10.         orgId: 1
  11.       - name: 'user admins'
  12.         orgId: 1

Manage default built-in role assignments

During startup, Grafana creates default built-in role assignments with fixed roles. You can remove and later restore those assignments with provisioning.

Remove default assignment

To remove default built-in role assignments, use the removeDefaultAssignments element in the configuration file. You need to provide the built-in role name and fixed role name.

Here is an example:

  1. # config file version
  2. apiVersion: 1
  4. # list of default built-in role assignments that should be removed
  5. removeDefaultAssignments:
  6.   - builtInRole: 'Grafana Admin'
  7.     fixedRole: 'fixed:permissions:admin'

Restore default assignment

To restore the default built-in role assignment, use the addDefaultAssignments element in the configuration file. You need to provide the built-in role name and the fixed-role name.

Here is an example:

  1. # config file version
  2. apiVersion: 1
  4. # list of default built-in role assignments that should be added back
  5. addDefaultAssignments:
  6.   - builtInRole: 'Admin'
  7.     fixedRole: 'fixed:reporting:admin:read'

Full example of a role configuration file

  1. # config file version
  2. apiVersion: 1
  4. # list of default built-in role assignments that should be removed
  5. removeDefaultAssignments:
  6.   # <string>, must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
  7.   - builtInRole: 'Grafana Admin'
  8.     # <string>, must be one of the existing fixed roles
  9.     fixedRole: 'fixed:permissions:admin'
  11. # list of default built-in role assignments that should be added back
  12. addDefaultAssignments:
  13.   # <string>, must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
  14.   - builtInRole: 'Admin'
  15.     # <string>, must be one of the existing fixed roles
  16.     fixedRole: 'fixed:reporting:admin:read'
  18. # list of roles that should be deleted
  19. deleteRoles:
  20.   # <string> name of the role you want to create. Required if no uid is set
  21.   - name: 'custom:reports:editor'
  22.     # <string> uid of the role. Required if no name
  23.     uid: 'customreportseditor1'
  24.     # <int> org id. will default to Grafana's default if not specified
  25.     orgId: 1
  26.     # <bool> force deletion revoking all grants of the role
  27.     force: true
  28.   - name: 'custom:global:reports:reader'
  29.     uid: 'customglobalreportsreader1'
  30.     # <bool> overwrite org id and removes a global role
  31.     global: true
  32.     force: true
  34. # list of roles to insert/update depending on what is available in the database
  35. roles:
  36.   # <string, required> name of the role you want to create. Required
  37.   - name: 'custom:users:editor'
  38.     # <string> uid of the role. Has to be unique for all orgs.
  39.     uid: customuserseditor1
  40.     # <string> description of the role, informative purpose only.
  41.     description: 'Role for our custom user editors'
  42.     # <int> version of the role, Grafana will update the role when increased
  43.     version: 2
  44.     # <int> org id. will default to Grafana's default if not specified
  45.     orgId: 1
  46.     # <list> list of the permissions granted by this role
  47.     permissions:
  48.       # <string, required> action allowed
  49.       - action: 'users:read'
  50.         #<string> scope it applies to
  51.         scope: 'users:*'
  52.       - action: 'users:write'
  53.         scope: 'users:*'
  54.       - action: 'users:create'
  55.         scope: 'users:*'
  56.     # <list> list of builtIn roles the role should be assigned to
  57.     builtInRoles:
  58.       # <string, required> name of the builtin role you want to assign the role to
  59.       - name: 'Editor'
  60.         # <int> org id. will default to the role org id
  61.         orgId: 1
  62.   - name: 'custom:global:users:reader'
  63.     uid: 'customglobalusersreader1'
  64.     description: 'Global Role for custom user readers'
  65.     version: 1
  66.     # <bool> overwrite org id and creates a global role
  67.     global: true
  68.     permissions:
  69.       - action: 'users:read'
  70.         scope: 'users:*'
  71.     builtInRoles:
  72.       - name: 'Viewer'
  73.         orgId: 1
  74.       - name: 'Editor'
  75.         # <bool> overwrite org id and assign role globally
  76.         global: true
  77.   - name: fixed:users:writer
  78.     global: true
  79.     # <list> list of teams the role should be assigned to
  80.     teams:
  81.       - name: 'user editors'
  82.         orgId: 1

Supported settings

The following sections detail the supported settings for roles and built-in role assignments.

  • Refer to Permissions for full list of valid permissions.
  • Check Custom roles to understand attributes for roles.
  • The default org ID is used if orgId is not specified in any of the configuration blocks.

Validation rules

A basic set of validation rules are applied to the input yaml files.

Roles

  • name must not be empty
  • name must not have fixed: prefix.

Permissions

  • name must not be empty

Built-in role assignments

  • name must be one of the Organization roles (Viewer, Editor, Admin) or Grafana Admin.
  • When orgId is not specified, it inherits the orgId from role. For global roles the default orgId is used.
  • orgId in the role and in the assignment must be the same for none global roles.

Role deletion

  • Either the role name or uid must be provided