From 2bbf4fa405efb03d47b8099ed4eada930254c205 Mon Sep 17 00:00:00 2001 From: Gabriel MABILLE Date: Fri, 4 Jun 2021 18:10:49 +0200 Subject: [PATCH] AccessControl: Update permissions and scopes in docs (#35263) * Saving the current changes made with @osg-grafana @donomii * Update remaining descriptions * Update docs/sources/enterprise/access-control/permissions.md Co-authored-by: Vardan Torosyan * Cleanup grammar Co-authored-by: Jeremy Price Co-authored-by: Vardan Torosyan --- .../enterprise/access-control/permissions.md | 102 +++++++++--------- 1 file changed, 52 insertions(+), 50 deletions(-) diff --git a/docs/sources/enterprise/access-control/permissions.md b/docs/sources/enterprise/access-control/permissions.md index cc75a90b44b..781d713c46b 100644 --- a/docs/sources/enterprise/access-control/permissions.md +++ b/docs/sources/enterprise/access-control/permissions.md @@ -5,11 +5,11 @@ keywords = ["grafana", "fine-grained access-control", "roles", "permissions", "e weight = 115 +++ -# Permissions +# Permissions -Each permission is defined by an action and a scope. When evaluating a fine-grained access decision, consider what specific action a user should be allowed to perform, and on what resources (its scope). +A permission is an action and a scope. When creating a fine-grained access control, consider what specific action a user should be allowed to perform, and on what resources (its scope). -To grant permissions to a user, create built-in role assignments. A built-in role assignment is a *modification* to one of the existing built-in roles in Grafana (Viewer, Editor, Admin) For more information, refer to [Built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}). +To grant permissions to a user, you create a built-in role assignment to map a role to a built-in role. A built-in role assignment *modifies* to one of the existing built-in roles in Grafana (Viewer, Editor, Admin). For more information, refer to [Built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}). To learn more about which permissions are used for which resources, refer to [Resources with fine-grained permissions]({{< relref "./_index.md#resources-with-fine-grained-permissions" >}}). @@ -17,59 +17,61 @@ action : The specific action on a resource defines what a user is allowed to perform if they have permission with the relevant action assigned to it. scope -: The scope describes where an action can be performed, such as reading a specific user profile. In such case, a permission is associated with the scope `users:` to the relevant role. Also, you can combine multiple scopes by using the `/` delimiter. +: The scope describes where an action can be performed, such as reading a specific user profile. In such case, a permission is associated with the scope `users:` to the relevant role. ## Action definitions -Note that below list is not exhaustive yet and more permissions will be available with further releases of fine-grained access control. +The following list contains fine-grained access control actions. -Action | Applicable scopes | Description +Actions | Applicable scopes | Descriptions --- | --- | --- -roles:list | roles:* | Allows to list available roles without permissions. -roles:read | roles:* | Allows to read a specific role with it's permissions. -roles:write | permissions:delegate | Allows to create or update a custom role. -roles:delete | permissions:delegate | Allows to delete a custom role. -roles.builtin:list | roles:* | Allows to list built-in role assignments. -roles.builtin:add | permissions:delegate | Allows to create a built-in role assignment. -roles.builtin:remove | permissions:delegate | Allows to delete a built-in role assignment. -reports.admin:write | reports:* | Allows to create or update reports. -reports:delete | reports:* | Allows to delete reports. -reports:read | reports:* | Allows to list all available reports and to get a specific report. -reports:send | reports:* | Allows to send report email. -reports.settings:write | n/a | Allows to update report settings. -reports.settings:read | n/a | Allows to read report settings. -provisioning:reload | service:access-control | Allows to reload provisioning files after an update. -users:read | global:users:* | Allows to read, search user profiles. -users:write | global:users:* | Allows to update user profiles. -users.teams:read | global:users:* | Allows to read user teams. -users.authtoken:list | global:users:* | Allows to list auth tokens assigned to users. -users.authtoken:update | global:users:* | Allows to update auth tokens assigned to users. -users.password:update | global:users:* | Allows to update users password. -users:delete | global:users:* | Allows to delete users. -users:create | n/a | Allows to create users. -users:enable | global:users:* | Allows to enable users. -users:disable | global:users:* | Allows to disable users. -users.permissions:update | global:users:* | Allows to update users org level permissions. -users:logout | global:users:* | Allows to enforce logout for users. -users.quotas:list | global:users:* | Allows to list user quotas. -users.quotas:update | global:users:* | Allows to update user quotas. -org.users.read | users:* | Allows to get user profiles within the organization. -org.users.add | users:* | Allows to add users to the organization. -org.users.remove | users:* | Allows to remove users from the organization. -org.users.role:update | users:* | Allows to update users organization role for the assigned organization. -ldap.user:read | n/a | Allows to read LDAP users. -ldap.user:sync | n/a | Allows to sync LDAP users. -ldap.status:read | n/a | Allows to check LDAP status. +roles:list | roles:* | List available roles without permissions. +roles:read | roles:* | Read a specific role with it's permissions. +roles:write | permissions:delegate | Create or update a custom role. +roles:delete | permissions:delegate | Delete a custom role. +roles.builtin:list | roles:* | List built-in role assignments. +roles.builtin:add | permissions:delegate | Create a built-in role assignment. +roles.builtin:remove | permissions:delegate | Delete a built-in role assignment. +reports.admin:create | reports:* | Create reports. +reports.admin:write | reports:* | Update reports. +reports:delete | reports:* | Delete reports. +reports:read | reports:* | List all available reports or get a specific report. +reports:send | reports:* | Send a report email. +reports.settings:write | n/a | Update report settings. +reports.settings:read | n/a | Read report settings. +provisioning:reload | service:access-control | Reload provisioning files. +users:read | global:users:* | Read or search user profiles. +users:write | global:users:* | Update a user’s profile. +users.teams:read | global:users:* | Read a user’s teams. +users.authtoken:list | global:users:* | List authentication tokens that are assigned to a user. +users.authtoken:update | global:users:* | Update authentication tokens that are assigned to a user. +users.password:update | global:users:* | Update a user’s password. +users:delete | global:users:* | Delete a user. +users:create | n/a | Create a user. +users:enable | global:users:* | Enable a user. +users:disable | global:users:* | Disable a user. +users.permissions:update | global:users:* | Update a user’s organization-level permissions. +users:logout | global:users:* | Log out a user. +users.quotas:list | global:users:* | List a user’s quotas. +users.quotas:update | global:users:* | Update a user’s quotas. +org.users.read | users:* | Get user profiles within an organization. +org.users.add | users:* | Add a user to an organization. +org.users.remove | users:* | Remove a user from an organization. +org.users.role:update | users:* | Update the organization role (`Viewer`, `Editor`, `Admin`) for an organization. +ldap.user:read | n/a | Get a user via LDAP. +ldap.user:sync | n/a | Sync a user via LDAP. +ldap.status:read | n/a | Verify the LDAP servers’ availability. +status:accesscontrol | service:access-control | Get access-control enabled status. ## Scope definitions -Note that below list is not exhaustive yet and more scopes will be available with further releases of fine-grained access control. +The following list contains fine-grained access control scopes. -Scope | Description ---- | --- -roles:* | Indicates against what roles an action can be performed. For example, `roles:*` assumes any roles, and `roles:randomuid` assumes only a role with UID `randomuid`. -permissions:delegate | The scope is only applicable for roles associated with the Access Control itself and indicates that you can delegate your permissions only, or a subset of it, by creating a new role or making an assignment. -reports:* | Indicates against what reports an action can be performed. -service:access-control | Only relevant for provisioning and indicates that the action can be performed only for access control provisioning files. -global:users:* | Indicates that action can be performed against users globally. -users:* | Indicates that an action can be performed against users in organization level. +Scopes | Descriptions +--- | --- +roles:* | Restrict an action to a set of roles. For example, `roles:*` matches any role, `roles:randomuid` matches only the role with UID `randomuid` and `roles:custom:reports:{editor,viewer}` matches both `custom:reports:editor` and `custom:reports:viewer` roles. +permissions:delegate | The scope is only applicable for roles associated with the Access Control itself and indicates that you can delegate your permissions only, or a subset of it, by creating a new role or making an assignment. +reports:* | Restrict an action to a set of reports. For example, `reports:*` matches any report and `reports:1` matches the report with id `1`. +service:accesscontrol | Restrict an action to target only the fine-grained access control service. For example, you can use this in conjunction with the `provisioning:reload` or the `status:accesscontrol` actions. +global:users:* | Restrict an action to a set of global users. +users:* | Restrict an action to a set of users from an organization.