Provisioning

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

    The configuration files must be placed in provisioning/access-control/. Grafana performs provisioning during the startup. Refer to the 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.

    To create or update custom roles, you can add a list of 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 accounted for.

    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 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.     version: 1
    8.     global: true
    9.     permissions:
    10.       - action: 'users:read'
    11.         scope: 'users:*'
    12.       - action: 'users:write'
    13.         scope: 'users:*'
    14.       - action: 'users:create'
    15.         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.

    Here is an example YAML file to delete a role:

    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.

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

    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.         scope: 'users:*'
    14.       - action: 'users:create'
    15.         scope: 'users:*'
    16.     builtInRoles:
    17.       - name: 'Editor'
    18.       - name: 'Admin'

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

    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:

    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

    • Refer to Permissions for full list of valid permissions.
    • Check 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.
    • 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.

    Role deletion

    • Either the role name or must be provided