public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[Docs] Document FGAC user role assignment (#41797)

Browse Source
This commit is contained in:
Mitch Seaman
2021-11-24 22:50:48 +01:00
committed by GitHub
parent 18b5e40d5a
commit 5043448769
10 changed files with 479 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/enterprise/access-control/_index.md
+1 -1
View File
@@ -21,7 +21,7 @@ Fine-grained access control considers a) _who_ has an access (`identity`), and b
You can grant, change, or revoke access to _users_ (`identity`). When an authenticated user tries to access a Grafana resource, the authorization system checks the required fine-grained permissions for the resource and determines whether or not the action is allowed. Refer to [Fine-grained permissions]({{< relref "./permissions.md" >}}) for a complete list of available permissions.
To grant or revoke access to your users, create or remove built-in role assignments. For more information, refer to [Built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}).
Refer to [Assign roles]({{< relref "./roles.md#assign-roles" >}}) to learn about grant or revoke access to your users.
## Resources with fine-grained permissions
docs/sources/enterprise/access-control/fine-grained-access-control-references.md
+2 -2
View File
@@ -13,8 +13,8 @@ The reference information that follows complements conceptual information about
| Fixed roles | Permissions | Descriptions |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fixed:roles:reader` | `roles:read`<br>`roles:list`<br>`roles.builtin:list` | Read all access control roles and built-in role assignments. |
| `fixed:roles:writer` | All permissions from `fixed:roles:reader` and <br>`roles:write`<br>`roles:delete`<br>`roles.builtin:add`<br>`roles.builtin:remove` | Create, read, update, or delete all roles and built-in role assignments. |
| `fixed:roles:reader` | `roles:read`<br>`roles:list`<br>`users.roles:list`<br>`users.permissions:list`<br>`roles.builtin:list` | Read all access control roles, roles and permissions assigned to users and built-in role assignments. |
| `fixed:roles:writer` | All permissions from `fixed:roles:reader` and <br>`roles:write`<br>`roles:delete`<br>`users.roles:add`<br>`users.roles:remove`<br>`roles.builtin:add`<br>`roles.builtin:remove` | Create, read, update, or delete all roles, assign or unassign roles to users and built-in role assignments. |
| `fixed:reports:reader` | `reports:read`<br>`reports:send`<br>`reports.settings:read` | Read all reports and shared report settings. |
| `fixed:reports:writer` | All permissions from `fixed:reports:reader` and <br>`reports.admin:write`<br>`reports:delete`<br>`reports.settings:write` | Create, read, update, or delete all reports and shared report settings. |
| `fixed:users:reader` | `users:read`<br>`users.quotas:list`<br>`users.authtoken:list`<br>`users.teams:read` | Read all users and their information, such as team memberships, authentication tokens, and quotas. |
docs/sources/enterprise/access-control/manage-role-assignments/_index.md
+15
View File
@@ -0,0 +1,15 @@
+++
title = "Manage role assignments"
description = ""
keywords = ["grafana", "fine-grained-access-control", "roles", "permissions", "enterprise"]
weight = 115
+++
# Manage role assignments
To grant or revoke access to your users, you can assign [Roles]({{< relref "../roles.md" >}}) to users, [Organization roles]({{< relref "../../../permissions/organization_roles.md" >}}) and [Grafana Server Admin]({{< relref "../../../permissions/_index.md#grafana-server-admin-role" >}}) role.
The following pages provide more information on how to manage role assignments:
- [Manage user role assignments]({{< relref "manage-user-role-assignments.md" >}}).
- [Manage role assignments to Organization roles and Grafana Server Admin role]({{< relref "manage-built-in-role-assignments.md" >}}).
docs/sources/enterprise/access-control/manage-role-assignments/manage-built-in-role-assignments.md
+19
View File
@@ -0,0 +1,19 @@
+++
title = "Manage built-in role assignments"
description = "Manage built-in role assignments"
keywords = ["grafana", "fine-grained-access-control", "roles", "permissions", "fine-grained-access-control-usage", "enterprise"]
weight = 210
+++
# Built-in role assignments
To control what your users can access or not, you can assign or unassign [Custom roles]({{< ref "#custom-roles" >}}) or [Fixed roles]({{< ref "#fixed-roles" >}}) to the existing [Organization roles]({{< relref "../../../permissions/organization_roles.md" >}}) or to [Grafana Server Admin]({{< relref "../../../permissions/_index.md#grafana-server-admin-role" >}}) role.
These assignments are called built-in role assignments.
During startup, Grafana will create default assignments for you. When you make any changes to the built-on role assignments, Grafana will take them into account and won’t overwrite during next start.
For more information, refer to [Fine-grained access control references]({{< relref "../fine-grained-access-control-references.md#default-built-in-role-assignments" >}}).
# Manage built-in role assignments
You can create or remove built-in role assignments using [Fine-grained access control API]({{< relref "../../../http_api/access_control.md#create-and-remove-built-in-role-assignments" >}}) or using [Grafana Provisioning]({{< relref "../provisioning.md#manage-default-built-in-role-assignments" >}}).
docs/sources/enterprise/access-control/manage-role-assignments/manage-user-role-assignments.md
+64
View File
@@ -0,0 +1,64 @@
+++
title = "Manage user role assignments"
description = "Manage user role assignments"
keywords = ["grafana", "fine-grained-access-control", "roles", "permissions", "fine-grained-access-control-usage", "enterprise"]
weight = 200
+++
# Manage user role assignments
There are two ways to assign roles directly to users: in the UI using the role picker, and using the API.
## Manage users' roles within a specific Organization using the role picker
In order to assign roles to a user within a specific Organization using the role picker, you must have a user account with one of the following:
- The Admin built-in role.
- The Server Admin role.
- The fixed role `fixed:permissions:writer`, [assigned for the given Organization]({{< relref "../roles/#scope-of-assignments" >}}).
- A custom role with `users.roles:add` and `users.roles:remove` permissions.
You must also have the permissions granted by the roles that you want to assign or revoke.
Steps:
1. Navigate to the Users Configuration page by hovering over **Configuration** (the gear icon) in the left navigation menu and selecting **Users**.
1. Click on the **Role** column in the row for the user whose role you would like to edit.
1. Deselect one or more selected roles that you would like to remove from that user.
1. Select one or more roles that you would like to assign to that user.
1. Click the **Apply** button to apply the selected roles to that user.
![User role picker in Organization](/static/img/docs/enterprise/user_role_picker_global.png)
The user's permissions will update immediately, and the UI will reflect their new permissions the next time they reload their browser or visit a new page.
**Note**: The roles that you select will be assigned only within the given Organization. For example, if you grant the user the "Data source editor" role while you are in the main Organization, then that user will be able to edit data source in the main Organization but not in others.
## Manage users' roles in multiple Organizations using the role picker
In order to assign roles across multiple Organizations to a user using the role picker, you must have a user account with one of the following:
- The Server Admin built-in role
- The fixed role `fixed:permissions:writer`, [assigned globally]({{< relref "../roles/#scope-of-assignments" >}}).
- A custom role with `users.roles:add` and `users.roles:remove` permissions, [assigned globally]({{< relref "../roles/#scope-of-assignments" >}}).
You must also have the permissions granted by the roles that you want to assign or revoke within the Organization in which you're making changes.
Steps:
1. Navigate to the Users Admin page by hovering over **Server Admin** (the shield icon) in the left navigation menu and selecting **Users**.
1. Click on a user row to edit that user's roles.
1. Under the **Organizations** header, you will see a list of roles assigned to that user within each of their Organizations. Click on the roles in an organization to open the role picker.
1. Deselect one or more selected roles that you would like to remove from that user.
1. Select one or more roles that you would like to assign to that user.
1. Click the **Apply** button to apply the selected roles to that user.
![User role picker in Organization](/static/img/docs/enterprise/user_role_picker_in_org.png)
The user's permissions will update immediately, and the UI will reflect their new permissions the next time they reload their browser or visit a new page.
**Note**: The roles that you select will be assigned only within one Organization. For example, if you grant the user the "Data source editor" role in the row for the main Organization, then that user will be able to edit data source in the main Organization but not in others.
## Manage users' roles via API
To manage user role assignment via API, refer to the [fine-grained access control HTTP API docs]({{< relref "../../../http_api/access_control.md#create-and-remove-user-role-assignments" >}}).
docs/sources/enterprise/access-control/permissions.md
+5 -1
View File
@@ -2,7 +2,7 @@
title = "Permissions"
description = "Understand fine-grained access control permissions"
keywords = ["grafana", "fine-grained access-control", "roles", "permissions", "enterprise"]
weight = 115
weight = 110
+++
# Permissions
@@ -54,6 +54,10 @@ The following list contains fine-grained access control actions.
| `users:logout` | `global:users:*` <br> `global:users:id:*` | Sign out a user. |
| `users.quotas:list` | `global:users:*` <br> `global:users:id:*` | List a user’s quotas. |
| `users.quotas:update` | `global:users:*` <br> `global:users:id:*` | Update a user’s quotas. |
| `users.roles:list` | `users:*` | List roles assigned directly to a user. |
| `users.roles:add` | `permissions:delegate` | Assign a role to a user. |
| `users.roles:remove` | `permissions:delegate` | Unassign a role from a auser. |
| `users.permissions:list` | `users:*` | List permissions of a user. |
| `org.users:read` | `users:*` <br> `users:id:*` | Get user profiles within an organization. |
| `org.users:add` | `users:*` | Add a user to an organization. |
| `org.users:remove` | `users:*` <br> `users:id:*` | Remove a user from an organization. |
docs/sources/enterprise/access-control/provisioning.md
+1 -1
View File
@@ -25,7 +25,7 @@ You can create, update, and delete custom roles, as well as create and remove bu
To create or update custom roles, you can add a list of `roles` in the configuration.
Every role has a [version]({{< relref "./roles.md#custom-roles" >}}) number. For each role you update, you must remember to increment it, otherwise changes won't be accounted for.
Every role has a [version]({{< relref "./roles.md#custom-roles" >}}) 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.
docs/sources/enterprise/access-control/roles.md
+12 -11
View File
@@ -44,6 +44,14 @@ Role names must be unique within an organization.
Roles with names prefixed by `fixed:` are fixed roles created by Grafana and cannot be created or modified by users.
### Display name
A role's display name is intended as a human friendly identifier for the role, helping users understand the purpose of a role. The display name of the role is displayed in the role picker in the UI.
### Group
A role's group is used to organize roles in the role picker in the UI.
### Role version
The version of a role is a positive integer which defines the current version of the role. When updating a role, you can either omit the version field to increment the previous value by 1 or set a new version which must be strictly larger than the previous version for the update to succeed.
@@ -67,20 +75,13 @@ If a Grafana Server Admin wants to delegate that privilege to other users, they
Note that you won't be able to create, update or delete a custom role with permissions which you yourself do not have. For example, if the only permission you have is a `users:create`, you won't be able to create a role with other permissions.
## Built-in role assignments
## Assign roles
To control what your users can access or not, you can assign or unassign [Custom roles]({{< ref "#custom-roles" >}}) or [Fixed roles]({{< ref "#fixed-roles" >}}) to the existing [Organization roles]({{< relref "../../permissions/organization_roles.md" >}}) or to [Grafana Server Admin]({{< relref "../../permissions/_index.md#grafana-server-admin-role" >}}) role.
These assignments are called built-in role assignments.
[Custom roles]({{< ref "#custom-roles" >}}) and [Fixed roles]({{< ref "#fixed-roles" >}}) can be assigned to users, the existing [Organization roles]({{< relref "../../permissions/organization_roles.md" >}}) and to [Grafana Server Admin]({{< relref "../../permissions/_index.md#grafana-server-admin-role" >}}) role.
During startup, Grafana will create default assignments for you. When you make any changes to the built-on role assignments, Grafana will take them into account and won’t overwrite during next start.
For more information, refer to [Fine-grained access control references]({{< relref "./fine-grained-access-control-references.md#default-built-in-role-assignments" >}}).
## Create and remove built-in role assignments
You can create or remove built-in role assignments using [Fine-grained access control API]({{< relref "../../http_api/access_control.md" >}}) or using [Grafana Provisioning]({{< relref "./provisioning" >}}).
Visit [Manage role assignments]({{< relref "manage-role-assignments/_index.md" >}}) page for more details.
### Scope of assignments
A built-in role assignment can be either _global_ or _organization local_. _Global_ assignments are not mapped to any specific organization and will be applied to all organizations, whereas _organization local_ assignments are only applied for that specific organization.
A role assignment can be either _global_ or _organization local_. _Global_ assignments are not mapped to any specific organization and will be applied to all organizations, whereas _organization local_ assignments are only applied for that specific organization.
You can only create _organization local_ assignments for _organization local_ roles.
docs/sources/enterprise/access-control/usage-scenarios.md
+4
View File
@@ -132,6 +132,10 @@ Example response:
}
```
## Manage roles granted directly to users
To learn about granting roles to users, refer to [Manage user role assignments]({{< relref "manage-role-assignments/manage-user-role-assignments.md" >}}) page.
## Create your first custom role
You can create your custom role by either using an [HTTP API]({{< relref "../../http_api/access_control.md#create-a-new-custom-role" >}}) or by using [Grafana provisioning]({{< relref "./provisioning.md" >}}).