From b38d3f339ae06c01c0242b3657905ca45daa3d07 Mon Sep 17 00:00:00 2001 From: Vardan Torosyan Date: Fri, 4 Feb 2022 13:17:25 +0100 Subject: [PATCH] Documentation for granting and revoking access for teams. (#44863) --- .../fine-grained-access-control-references.md | 4 +- .../manage-role-assignments/_index.md | 3 +- .../manage-team-role-assignments.md | 38 ++++ .../manage-user-role-assignments.md | 4 +- .../enterprise/access-control/permissions.md | 6 +- docs/sources/http_api/access_control.md | 212 ++++++++++++++++++ 6 files changed, 261 insertions(+), 6 deletions(-) create mode 100644 docs/sources/enterprise/access-control/manage-role-assignments/manage-team-role-assignments.md diff --git a/docs/sources/enterprise/access-control/fine-grained-access-control-references.md b/docs/sources/enterprise/access-control/fine-grained-access-control-references.md index 36e1e83342b..c3c52c1b2b6 100644 --- a/docs/sources/enterprise/access-control/fine-grained-access-control-references.md +++ b/docs/sources/enterprise/access-control/fine-grained-access-control-references.md @@ -13,8 +13,8 @@ The reference information that follows complements conceptual information about | Fixed roles | Permissions | Descriptions | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `fixed:roles:reader` | `roles:read`
`roles:list`
`users.roles:list`
`users.permissions:list`
`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
`roles:write`
`roles:delete`
`users.roles:add`
`users.roles:remove`
`roles.builtin:add`
`roles.builtin:remove` | Create, read, update, or delete all roles, assign or unassign roles to users and built-in role assignments. | +| `fixed:roles:reader` | `roles:read`
`roles:list`
`teams.roles:list`
`users.roles:list`
`users.permissions:list`
`roles.builtin:list` | Read all access control roles, roles and permissions assigned to users, teams and built-in role assignments. | +| `fixed:roles:writer` | All permissions from `fixed:roles:reader` and
`roles:write`
`roles:delete`
`teams.roles:add`
`teams.roles:remove`
`users.roles:add`
`users.roles:remove`
`roles.builtin:add`
`roles.builtin:remove` | Create, read, update, or delete all roles, assign or unassign roles to users, teams and built-in role assignments. | | `fixed:reports:reader` | `reports:read`
`reports:send`
`reports.settings:read` | Read all reports and shared report settings. | | `fixed:reports:writer` | All permissions from `fixed:reports:reader` and
`reports.admin:write`
`reports:delete`
`reports.settings:write` | Create, read, update, or delete all reports and shared report settings. | | `fixed:users:reader` | `users:read`
`users.quotas:list`
`users.authtoken:list`
`users.teams:read` | Read all users and their information, such as team memberships, authentication tokens, and quotas. | diff --git a/docs/sources/enterprise/access-control/manage-role-assignments/_index.md b/docs/sources/enterprise/access-control/manage-role-assignments/_index.md index 25b93e3abe1..36f750a009e 100644 --- a/docs/sources/enterprise/access-control/manage-role-assignments/_index.md +++ b/docs/sources/enterprise/access-control/manage-role-assignments/_index.md @@ -7,9 +7,10 @@ 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. +To grant or revoke access to your users, you can assign [Roles]({{< relref "../roles.md" >}}) to users and teams, or to [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 team role assignments]({{< relref "manage-team-role-assignments.md" >}}). - [Manage role assignments to Organization roles and Grafana Server Admin role]({{< relref "manage-built-in-role-assignments.md" >}}). diff --git a/docs/sources/enterprise/access-control/manage-role-assignments/manage-team-role-assignments.md b/docs/sources/enterprise/access-control/manage-role-assignments/manage-team-role-assignments.md new file mode 100644 index 00000000000..57808939368 --- /dev/null +++ b/docs/sources/enterprise/access-control/manage-role-assignments/manage-team-role-assignments.md @@ -0,0 +1,38 @@ ++++ +title = "Manage team role assignments" +description = "Manage team role assignments" +keywords = ["grafana", "fine-grained-access-control", "roles", "permissions", "fine-grained-access-control-usage", "enterprise"] +weight = 200 ++++ + +# Manage team role assignments + +There are two ways to assign roles directly to teams: in the UI using the role picker, and using the API. + +## Manage teams' roles within a specific Organization using the role picker + +In order to assign roles to a team within a specific Organization using the role picker, you must have an account with one of the following: + +- The Admin built-in role. +- The Server Admin role. +- The fixed role `fixed:roles:writer`, [assigned for the given Organization]({{< relref "../roles/#scope-of-assignments" >}}). +- A custom role with `teams.roles:add` and `teams.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 Teams page by hovering over **Configuration** (the gear icon) in the left navigation menu and selecting **Teams**. +1. Click on the **Roles** column in the row for the team whose roles you would like to edit. +1. Deselect one or more selected roles that you would like to remove from that team. +1. Select one or more roles that you would like to assign to that team. +1. Click the **Update** button to apply the selected roles to that team. + +![Team role assignment](/static/img/docs/enterprise/team_role_assignment.png) +![Team roles assigned](/static/img/docs/enterprise/team_role_assigned.png) + +The team's permissions will update immediately, and the UI will reflect its new permissions. + +## Manage teams' roles via API + +To manage team role assignments via API, refer to the [fine-grained access control HTTP API docs]({{< relref "../../../http_api/access_control.md#create-and-remove-team-role-assignments" >}}). diff --git a/docs/sources/enterprise/access-control/manage-role-assignments/manage-user-role-assignments.md b/docs/sources/enterprise/access-control/manage-role-assignments/manage-user-role-assignments.md index e537fe6d2bd..70c1193a97b 100644 --- a/docs/sources/enterprise/access-control/manage-role-assignments/manage-user-role-assignments.md +++ b/docs/sources/enterprise/access-control/manage-role-assignments/manage-user-role-assignments.md @@ -15,7 +15,7 @@ In order to assign roles to a user within a specific Organization using the role - 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" >}}). +- The fixed role `fixed:roles: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. @@ -26,7 +26,7 @@ Steps: 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. +1. Click the **Update** button to apply the selected roles to that user. ![User role picker in Organization](/static/img/docs/enterprise/user_role_picker_global.png) diff --git a/docs/sources/enterprise/access-control/permissions.md b/docs/sources/enterprise/access-control/permissions.md index 6bca31e0889..372a008aec4 100644 --- a/docs/sources/enterprise/access-control/permissions.md +++ b/docs/sources/enterprise/access-control/permissions.md @@ -40,6 +40,9 @@ The following list contains fine-grained access control actions. | `reports.settings:write` | n/a | Update report settings. | | `reports.settings:read` | n/a | Read report settings. | | `provisioning:reload` | `provisioners:*` | Reload provisioning files. To find the exact scope for specific provisioner, see [Scope definitions]({{< relref "./permissions.md#scope-definitions" >}}). | +| `teams.roles:list` | `teams:*` | List roles assigned directly to a team. | +| `teams.roles:add` | `permissions:delegate` | Assign a role to a team. | +| `teams.roles:remove` | `permissions:delegate` | Unassign a role from a team. | | `users:read` | `global:users:*` | Read or search user profiles. | | `users:write` | `global:users:*`
`global:users:id` | Update a user’s profile. | | `users.teams:read` | `global:users:*`
`global:users:id:*` | Read a user’s teams. | @@ -56,7 +59,7 @@ The following list contains fine-grained access control actions. | `users.quotas:update` | `global:users:*`
`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.roles:remove` | `permissions:delegate` | Unassign a role from a user. | | `users.permissions:list` | `users:*` | List permissions of a user. | | `org.users:read` | `users:*`
`users:id:*` | Get user profiles within an organization. | | `org.users:add` | `users:*` | Add a user to an organization. | @@ -103,6 +106,7 @@ The following list contains fine-grained access control scopes. | `reports:*`
`reports:id:*` | Restrict an action to a set of reports. For example, `reports:*` matches any report and `reports:id:1` matches the report whose ID is `1`. | | `services:accesscontrol` | Restrict an action to target only the fine-grained access control service. You can use this in conjunction with the `status:accesscontrol` actions. | | `global:users:*`
`global:users:id:*` | Restrict an action to a set of global users. For example, `global:users:*` matches any user and `global:users:id:1` matches the user whose ID is `1`. | +| `teams:*`
`teams:id:*` | Restrict an action to a set of teams from an organization. For example, `teams:*` matches any team and `teams:id:1` matches the team whose ID is `1`. | | `users:*`
`users:id:*` | Restrict an action to a set of users from an organization. For example, `users:*` matches any user and `users:id:1` matches the user whose ID is `1`. | | `orgs:*`
`orgs:id:*` | Restrict an action to a set of organizations. For example, `orgs:*` matches any organization and `orgs:id:1` matches the organization whose ID is `1`. | | `settings:*` | Restrict an action to a subset of settings. For example, `settings:*` matches all settings, `settings:auth.saml:*` matches all SAML settings, and `settings:auth.saml:enabled` matches the enable property on the SAML settings. | diff --git a/docs/sources/http_api/access_control.md b/docs/sources/http_api/access_control.md index f9b5f9a0dda..946c652830e 100644 --- a/docs/sources/http_api/access_control.md +++ b/docs/sources/http_api/access_control.md @@ -726,6 +726,218 @@ Content-Type: application/json; charset=UTF-8 | 404 | Role not found. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | +## Create and remove team role assignments + +### List roles assigned to a team + +`GET /api/access-control/teams/:teamId/roles` + +Lists the roles that have been directly assigned to a given team. + +#### Required permissions + +| Action | Scope | +| ---------------- | -------------------- | +| teams.roles:list | teams:id:`` | + +#### Example request + +```http +GET /api/access-control/teams/1/roles +Accept: application/json +``` + +#### Example response + +```http +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 + +[ + { + "version": 4, + "uid": "j08ZBi-nk", + "name": "fixed:licensing:reader", + "displayName": "Licensing reader", + "description": "Read licensing information and licensing reports.", + "group": "Licenses", + "updated": "2022-02-03T14:19:50+01:00", + "created": "0001-01-01T00:00:00Z", + "global": false + } +] +``` + +#### Status codes + +| Code | Description | +| ---- | -------------------------------------------------------------------- | +| 200 | Set of assigned roles is returned. | +| 403 | Access denied. | +| 500 | Unexpected error. Refer to body and/or server logs for more details. | + +### Add a team role assignment + +`POST /api/access-control/teams/:teamId/roles` + +Assign a role to a specific team. + +For bulk updates consider [Set team role assignments]({{< ref "#set-team-role-assignments" >}}). + +#### Required permissions + +`permission:delegate` scope ensures that users can only assign roles which have same, or a subset of permissions which the user has. +For example, if a user does not have the permissions required to create users, they won't be able to assign a role that contains these permissions. This is done to prevent escalation of privileges. + +| Action | Scope | +| --------------- | -------------------- | +| teams.roles:add | permissions:delegate | + +#### Example request + +```http +POST /api/access-control/teams/1/roles +Accept: application/json +Content-Type: application/json + +{ + "roleUid": "XvHQJq57z" +} +``` + +#### JSON body schema + +| Field Name | Data Type | Required | Description | +| ---------- | --------- | -------- | ---------------- | +| roleUid | string | Yes | UID of the role. | + +#### Example response + +```http +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 + +{ + "message": "Role added to the team." +} +``` + +#### Status codes + +| Code | Description | +| ---- | -------------------------------------------------------------------- | +| 200 | Role is assigned to a team. | +| 403 | Access denied. | +| 404 | Role not found. | +| 500 | Unexpected error. Refer to body and/or server logs for more details. | + +## Remove a user role assignment + +`DELETE /api/access-control/teams/:teams/roles/:roleUID` + +Revoke a role from a team. + +For bulk updates consider [Set team role assignments]({{< ref "#set-team-role-assignments" >}}). + +#### Required permissions + +`permission:delegate` scope ensures that users can only unassign roles which have same, or a subset of permissions which the user has. +For example, if a user does not have the permissions required to create users, they won't be able to assign a role that contains these permissions. This is done to prevent escalation of privileges.``` + +| Action | Scope | +| ------------------ | -------------------- | +| teams.roles:remove | permissions:delegate | + +#### Example request + +```http +DELETE /api/access-control/teams/1/roles/AFUXBHKnk +Accept: application/json +``` + +#### Example response + +```http +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 + +{ + "message": "Role removed from team." +} +``` + +#### Status codes + +| Code | Description | +| ---- | -------------------------------------------------------------------- | +| 200 | Role is unassigned. | +| 403 | Access denied. | +| 500 | Unexpected error. Refer to body and/or server logs for more details. | + +### Set team role assignments + +`PUT /api/access-control/teams/:teamId/roles` + +Update the team's role assignments to match the provided set of UIDs. +This will remove any assigned roles that aren't in the request and add +roles that are in the set but are not already assigned to the user. + +If you want to add or remove a single role, consider using +[Add a team role assignment]({{< ref "#add-a-team-role-assignment" >}}) or +[Remove a team role assignment]({{< ref "#remove-a-team-role-assignment" >}}) +instead. + +#### Required permissions + +`permission:delegate` scope ensures that users can only assign or unassign roles which have same, or a subset of permissions which the user has. +For example, if a user does not have required permissions for creating users, they won't be able to assign or unassign a role to a team which will allow to do that. This is done to prevent escalation of privileges. + +| Action | Scope | +| ------------------ | -------------------- | +| teams.roles:add | permissions:delegate | +| teams.roles:remove | permissions:delegate | + +#### Example request + +```http +PUT /api/access-control/teams/1/roles +Accept: application/json +Content-Type: application/json + +{ + "roleUids": [ + "ZiHQJq5nk", + "GzNQ1357k" + ] +} +``` + +#### JSON body schema + +| Field Name | Date Type | Required | Description | +| ---------- | --------- | -------- | ------------------ | +| roleUids | list | Yes | List of role UIDs. | + +#### Example response + +```http +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 + +{ + "message": "Team roles have been updated." +} +``` + +#### Status codes + +| Code | Description | +| ---- | -------------------------------------------------------------------- | +| 200 | Roles have been assigned. | +| 403 | Access denied. | +| 404 | Role not found. | +| 500 | Unexpected error. Refer to body and/or server logs for more details. | + ## Create and remove built-in role assignments API set allows to create or remove [built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) and list current assignments.