Fine-grained access control usage scenarios

    Before you get started, make sure to enable fine-grained access control.

    You can use the Fine-grained access control HTTP API to see all available built-in role assignments. The response contains a mapping between one of the organization roles (, Editor, Admin) or Grafana Admin to the custom or fixed roles.

    Example request:

    You must use the base64 username:password Basic Authorization here. Auth tokens are not applicable here.

    Example response:

    1. {
    2.     "Admin": [
    3.         ...
    4.         {
    5.             "version": 2,
    6.             "uid": "qQui_LCMk",
    7.             "name": "fixed:users:org:edit",
    8.             "description": "Allows every read action for user organizations and in addition allows to administer user organizations.",
    9.             "global": true,
    10.             "updated": "2021-05-17T20:49:18+02:00",
    11.             "created": "2021-05-13T16:24:26+02:00"
    12.         },
    13.         {
    14.             "version": 1,
    15.             "uid": "Kz9m_YjGz",
    16.             "name": "fixed:reporting:admin:edit",
    17.             "description": "Gives access to edit any report or the organization's general reporting settings.",
    18.             "global": true,
    19.             "updated": "2021-05-13T16:24:26+02:00",
    20.             "created": "2021-05-13T16:24:26+02:00"
    21.         }
    22.         ...
    23.     ],
    24.     "Grafana Admin": [
    25.         ...
    26.         {
    27.             "version": 2,
    28.             "uid": "qQui_LCMk",
    29.             "name": "fixed:users:org:edit",
    30.             "description": "Allows every read action for user organizations and in addition allows to administer user organizations.",
    31.             "global": true,
    32.             "updated": "2021-05-17T20:49:18+02:00",
    33.             "created": "2021-05-13T16:24:26+02:00"
    34.         },
    35.             "version": 2,
    36.             "uid": "ajum_YjGk",
    37.             "name": "fixed:users:admin:read",
    38.             "description": "Allows to list and get users and related information.",
    40.             "updated": "2021-05-17T20:49:17+02:00",
    41.             "created": "2021-05-13T16:24:26+02:00"
    42.         },
    43.         {
    44.             "version": 2,
    45.             "uid": "K3um_LCMk",
    46.             "name": "fixed:users:admin:edit",
    47.             "description": "Allows every read action for users and in addition allows to administer users.",
    48.             "global": true,
    49.             "updated": "2021-05-17T20:49:17+02:00",
    50.             "created": "2021-05-13T16:24:26+02:00"
    51.         },
    52.         ...
    53.     ]
    54. }

    To see what permissions each of the assigned roles have, you can a by using an HTTP API.

    Example response:

    1. {
    2.     "version": 2,
    3.     "uid": "qQui_LCMk",
    4.     "name": "fixed:users:org:edit",
    5.     "description": "Allows every read action for user organizations and in addition allows to administer user organizations.",
    6.     "global": true,
    7.     "permissions": [
    8.         {
    9.             "action": "org.users:add",
    10.             "scope": "users:*",
    11.             "updated": "2021-05-17T20:49:18+02:00",
    12.             "created": "2021-05-17T20:49:18+02:00"
    13.         },
    14.         {
    15.             "action": "org.users:read",
    16.             "scope": "users:*",
    17.             "updated": "2021-05-17T20:49:18+02:00",
    18.             "created": "2021-05-17T20:49:18+02:00"
    19.         },
    20.             "action": "org.users:remove",
    21.             "scope": "users:*",
    22.             "updated": "2021-05-17T20:49:18+02:00",
    23.             "created": "2021-05-17T20:49:18+02:00"
    24.         },
    25.         {
    26.             "action": "org.users.role:update",
    28.             "updated": "2021-05-17T20:49:18+02:00",
    29.             "created": "2021-05-17T20:49:18+02:00"
    30.         }
    31.     ],
    32.     "updated": "2021-05-17T20:49:18+02:00",
    33.     "created": "2021-05-13T16:24:26+02:00"
    34. }

    You can create your custom role by either using an or by using Grafana provisioning. You can take a look at to decide what permissions would you like to map to your role.

    Example HTTP request:

    Example response:

    1. {
    2.     "version": 1,
    3.     "uid": "jZrmlLCkGksdka",
    4.     "name": "custom:users:admin",
    5.     "description": "My custom role which gives users permissions to create users",
    6.     "global": true,
    7.     "permissions": [
    8.         {
    9.             "action": "users:create"
    10.             "updated": "2021-05-17T22:07:31.569936+02:00",
    11.             "created": "2021-05-17T22:07:31.569935+02:00"
    12.         }
    13.     ],
    14.     "updated": "2021-05-17T22:07:31.564403+02:00",
    15.     "created": "2021-05-17T22:07:31.564403+02:00"
    16. }

    Once the custom role is created, you can create a built-in role assignment by using an HTTP API. If you created your role using , you can also create the assignment with it.

    Example HTTP request:

    1. {
    2.     "message": "Built-in role grant added"
    3. }

    In order to create reports, you need to have reports.admin:write permission. By default, a Grafana Admin or organization Admin can create reports as there is a which comes with reports.admin:write permission.

    If you want your users who have the Viewer organization role to create reports, you have two options:

    1. Create a built-in role assignment and map the fixed:reporting:admin:edit fixed role to the Viewer built-in role. Note that the fixed:reporting:admin:edit fixed role allows doing more than creating reports. Refer to fixed roles for full list of permission assignments.
    2. with reports.admin:write permission, and create a built-in role assignment for Viewer organization role.

    In order to create users, you need to have users:create permission. By default, a user with the Grafana Admin role can create users as there is a which comes with users:create permission.

    If you want to prevent Grafana Admin from creating users, you can do the following:

    1. Check all built-in role assignments to see what built-in role assignments are available.
    2. From built-in role assignments, find the role which gives users:create permission. Refer to for full list of permission assignments.
    3. Remove the built-in role assignment by using an Fine-grained access control HTTP API or by using .

    By default, the Grafana Server Admin is the only user who can create and manage custom roles. If you want your users to do the same, you have two options:

    1. with roles.builtin:add and roles:write permissions, then create a built-in role assignment for organization role.

    Note that any user with the ability to modify roles can only create, update or delete roles with permissions they themselves have been granted. For example, a user with the Editor role would be able to create and manage roles only with the permissions they have, or with a subset of them.