diff --git a/docs/sources/enterprise/access-control/_index.md b/docs/sources/enterprise/access-control/_index.md index 938aea7f812..7cb95a794bb 100644 --- a/docs/sources/enterprise/access-control/_index.md +++ b/docs/sources/enterprise/access-control/_index.md @@ -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 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 dd9d0eaf087..5a1d99c7f73 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`
`roles.builtin:list` | Read all access control roles and built-in role assignments. | -| `fixed:roles:writer` | All permissions from `fixed:roles:reader` and
`roles:write`
`roles:delete`
`roles.builtin:add`
`roles.builtin:remove` | Create, read, update, or delete all roles and built-in role assignments. | +| `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: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 new file mode 100644 index 00000000000..25b93e3abe1 --- /dev/null +++ b/docs/sources/enterprise/access-control/manage-role-assignments/_index.md @@ -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" >}}). diff --git a/docs/sources/enterprise/access-control/manage-role-assignments/manage-built-in-role-assignments.md b/docs/sources/enterprise/access-control/manage-role-assignments/manage-built-in-role-assignments.md new file mode 100644 index 00000000000..1409b7bcad1 --- /dev/null +++ b/docs/sources/enterprise/access-control/manage-role-assignments/manage-built-in-role-assignments.md @@ -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" >}}). 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 new file mode 100644 index 00000000000..e537fe6d2bd --- /dev/null +++ b/docs/sources/enterprise/access-control/manage-role-assignments/manage-user-role-assignments.md @@ -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" >}}). diff --git a/docs/sources/enterprise/access-control/permissions.md b/docs/sources/enterprise/access-control/permissions.md index 29e220ef47a..560fc928360 100644 --- a/docs/sources/enterprise/access-control/permissions.md +++ b/docs/sources/enterprise/access-control/permissions.md @@ -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:*`
`global:users:id:*` | Sign out a user. | | `users.quotas:list` | `global:users:*`
`global:users:id:*` | List a user’s quotas. | | `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.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. | | `org.users:remove` | `users:*`
`users:id:*` | Remove a user from an organization. | diff --git a/docs/sources/enterprise/access-control/provisioning.md b/docs/sources/enterprise/access-control/provisioning.md index 2c096b9cd19..6601812e545 100644 --- a/docs/sources/enterprise/access-control/provisioning.md +++ b/docs/sources/enterprise/access-control/provisioning.md @@ -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. diff --git a/docs/sources/enterprise/access-control/roles.md b/docs/sources/enterprise/access-control/roles.md index f8578088820..ac6843eb6cf 100644 --- a/docs/sources/enterprise/access-control/roles.md +++ b/docs/sources/enterprise/access-control/roles.md @@ -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. diff --git a/docs/sources/enterprise/access-control/usage-scenarios.md b/docs/sources/enterprise/access-control/usage-scenarios.md index 7f8f9703e65..de31c0ab73e 100644 --- a/docs/sources/enterprise/access-control/usage-scenarios.md +++ b/docs/sources/enterprise/access-control/usage-scenarios.md @@ -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" >}}). diff --git a/docs/sources/http_api/access_control.md b/docs/sources/http_api/access_control.md index a69718203a0..4762dc30416 100644 --- a/docs/sources/http_api/access_control.md +++ b/docs/sources/http_api/access_control.md @@ -86,23 +86,27 @@ Content-Type: application/json; charset=UTF-8 [ { - "version": 1, - "uid": "Kz9m_YjGz", - "name": "fixed:reporting:admin:edit", - "description": "Gives access to edit any report or the organization's general reporting settings.", - "global": true, - "updated": "2021-05-13T16:24:26+02:00", - "created": "2021-05-13T16:24:26+02:00" + "version": 3, + "uid": "XvHQJq57z", + "name": "fixed:reports:reader", + "displayName": "Report reader", + "description": "Read all reports and shared report settings.", + "group": "Reports", + "updated": "2021-11-19T10:48:00+01:00", + "created": "2021-11-19T10:48:00+01:00", + "global": false }, { - "version": 5, - "uid": "vi9mlLjGz", - "name": "fixed:permissions:admin:read", - "description": "Gives access to read and list roles and permissions, as well as built-in role assignments.", - "global": true, - "updated": "2021-05-13T22:41:49+02:00", - "created": "2021-05-13T16:24:26+02:00" - } + "version": 4, + "uid": "6dNwJq57z", + "name": "fixed:reports:writer", + "displayName": "Report writer", + "description": "Create, read, update, or delete all reports and shared report settings.", + "group": "Reports", + "updated": "2021-11-19T10:48:00+01:00", + "created": "2021-11-19T10:48:00+01:00", + "global": false + }, ] ``` @@ -141,27 +145,59 @@ HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { - "version": 2, - "uid": "jZrmlLCGk", - "name": "fixed:permissions:admin:edit", - "description": "Gives access to create, update and delete roles, as well as manage built-in role assignments.", - "global": true, + "version": 4, + "uid": "6dNwJq57z", + "name": "fixed:reports:writer", + "displayName": "Report writer", + "description": "Create, read, update, or delete all reports and shared report settings.", + "group": "Reports", "permissions": [ { - "action": "roles:delete", - "scope": "permissions:delegate", - "updated": "2021-05-13T16:24:26+02:00", - "created": "2021-05-13T16:24:26+02:00" + "action": "reports:delete", + "scope": "reports:*", + "updated": "2021-11-19T10:48:00+01:00", + "created": "2021-11-19T10:48:00+01:00" }, { - "action": "roles:list", - "scope": "roles:*", - "updated": "2021-05-13T16:24:26+02:00", - "created": "2021-05-13T16:24:26+02:00" + "action": "reports:read", + "scope": "reports:*", + "updated": "2021-11-19T10:48:00+01:00", + "created": "2021-11-19T10:48:00+01:00" + }, + { + "action": "reports:send", + "scope": "reports:*", + "updated": "2021-11-19T10:48:00+01:00", + "created": "2021-11-19T10:48:00+01:00" + }, + { + "action": "reports.admin:create", + "scope": "", + "updated": "2021-11-19T10:48:00+01:00", + "created": "2021-11-19T10:48:00+01:00" + }, + { + "action": "reports.admin:write", + "scope": "reports:*", + "updated": "2021-11-19T10:48:00+01:00", + "created": "2021-11-19T10:48:00+01:00" + }, + { + "action": "reports.settings:read", + "scope": "", + "updated": "2021-11-19T10:48:00+01:00", + "created": "2021-11-19T10:48:00+01:00" + }, + { + "action": "reports.settings:write", + "scope": "", + "updated": "2021-11-19T10:48:00+01:00", + "created": "2021-11-19T10:48:00+01:00" } ], - "updated": "2021-05-13T16:24:26+02:00", - "created": "2021-05-13T16:24:26+02:00" + "updated": "2021-11-19T10:48:00+01:00", + "created": "2021-11-19T10:48:00+01:00", + "global": false } ``` @@ -170,7 +206,7 @@ Content-Type: application/json; charset=UTF-8 | Code | Description | | ---- | -------------------------------------------------------------------- | | 200 | Role is returned. | -| 403 | Access denied | +| 403 | Access denied. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | ### Create a new custom role @@ -200,7 +236,9 @@ Content-Type: application/json "uid": "jZrmlLCGka", "name": "custom:delete:roles", "description": "My custom role which gives users permissions to delete roles", - "global": true, + "group":"My Group", + "displayName": "My Custom Role", + "global": false, "permissions": [ { "action": "roles:delete", @@ -219,6 +257,8 @@ Content-Type: application/json | version | number | No | Version of the role. If not present, version 0 will be assigned to the role and returned in the response. Refer to the [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information. | | name | string | Yes | Name of the role. Refer to [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information. | | description | string | No | Description of the role. | +| displayName | string | No | Display name of the role, visible in the UI. | +| group | string | No | The group name the role belongs to. | | permissions | Permission | No | If not present, the role will be created without any permissions. | **Permission** @@ -239,7 +279,9 @@ Content-Type: application/json; charset=UTF-8 "uid": "jZrmlLCGka", "name": "custom:delete:create:roles", "description": "My custom role which gives users permissions to delete and create roles", - "global": true, + "group":"My Group", + "displayName": "My Custom Role", + "global": false, "permissions": [ { "action": "roles:delete", @@ -288,7 +330,9 @@ Content-Type: application/json "version": 3, "name": "custom:delete:write:roles", "description": "My custom role which gives users permissions to delete and write roles", - "global": true, + "group":"My Group", + "displayName": "My Custom Role", + "global": false, "permissions": [ { "action": "roles:delete", @@ -309,6 +353,8 @@ Content-Type: application/json | version | number | Yes | Version of the role. Must be incremented for update to work. | | name | string | Yes | Name of the role. | | description | string | No | Description of the role. | +| displayName | string | No | Display name of the role, visible in the UI. | +| group | string | No | The group name the role belongs to. | | permissions | List of Permissions | No | The full list of permissions the role should have after the update. | **Permission** @@ -329,6 +375,8 @@ Content-Type: application/json; charset=UTF-8 "uid":"jZrmlLCGka", "name":"custom:delete:write:roles", "description":"My custom role which gives users permissions to delete and write roles", + "group":"My Group", + "displayName": "My Custom Role", "permissions":[ { "action":"roles:delete", @@ -345,7 +393,7 @@ Content-Type: application/json; charset=UTF-8 ], "updated":"2021-08-06T18:27:41+02:00", "created":"2021-08-06T18:27:40+02:00", - "global":true + "global":false } ``` @@ -377,7 +425,7 @@ For example, if a user does not have required permissions for creating users, th #### Example request ```http -DELETE /api/access-control/roles/jZrmlLCGka?force=true&global=true +DELETE /api/access-control/roles/jZrmlLCGka?force=true&global=false Accept: application/json ``` @@ -407,6 +455,275 @@ Content-Type: application/json; charset=UTF-8 | 403 | Access denied | | 500 | Unexpected error. Refer to body and/or server logs for more details. | +## Create and remove user role assignments + +### List roles assigned to a user + +`GET /api/access-control/users/:userId/roles` + +Lists the roles that have been directly assigned to a given user. The list does not include built-in roles (Viewer, Editor, Admin or Grafana Admin), and it does not include roles that have been inherited from a team. + +#### Required permissions + +| Action | Scope | +| ---------------- | -------------------- | +| users.roles:list | users:id:`` | + +#### Example request + +```http +GET /api/access-control/users/1/roles +Accept: application/json +``` + +#### Example response + +```http +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 + +[ + { + "version": 4, + "uid": "6dNwJq57z", + "name": "fixed:reports:writer", + "displayName": "Report writer", + "description": "Create, read, update, or delete all reports and shared report settings.", + "group": "Reports", + "updated": "2021-11-19T10:48:00+01:00", + "created": "2021-11-19T10:48:00+01:00", + "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. | + +### List permissions assigned to a user + +`GET /api/access-control/users/:userId/permissions` + +Lists the permissions that a given user has. + +#### Required permissions + +| Action | Scope | +| ---------------------- | -------------------- | +| users.permissions:list | users:id:`` | + +#### Example request + +```http +GET /api/access-control/users/1/permissions +Accept: application/json +``` + +#### Example response + +```http +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 + +[ + { + "action": "ldap.status:read", + "scope": "" + }, + { + "action": "ldap.user:read", + "scope": "" + } +] +``` + +#### Status codes + +| Code | Description | +| ---- | -------------------------------------------------------------------- | +| 200 | Set of assigned permissions is returned. | +| 403 | Access denied. | +| 500 | Unexpected error. Refer to body and/or server logs for more details. | + +### Add a user role assignment + +`POST /api/access-control/users/:userId/roles` + +Assign a role to a specific user. + +For bulk updates consider +[Set user role assignments]({{< ref "#set-user-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 required permissions for creating users, they won't be able to assign a role which will allow to do that. This is done to prevent escalation of privileges. + +| Action | Scope | +| --------------- | -------------------- | +| users.roles:add | permissions:delegate | + +#### Example request + +```http +POST /api/access-control/users/1/roles +Accept: application/json +Content-Type: application/json + +{ + "global": false, + "roleUid": "XvHQJq57z" +} +``` + +#### JSON body schema + +| Field Name | Data Type | Required | Description | +| ---------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| roleUid | string | Yes | UID of the role. | +| global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to create organization local assignment. | + +#### Example response + +```http +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 + +{ + "message": "Role added to the user." +} +``` + +#### Status codes + +| Code | Description | +| ---- | -------------------------------------------------------------------- | +| 200 | Role is assigned to a user. | +| 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/users/:userId/roles/:roleUID` + +Revoke a role from a user. + +For bulk updates consider +[Set user role assignments]({{< ref "#set-user-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 required permissions for creating users, they won't be able to unassign a role which will allow to do that. This is done to prevent escalation of privileges. + +| Action | Scope | +| ------------------ | -------------------- | +| users.roles:remove | permissions:delegate | + +#### Query parameters + +| Param | Type | Required | Description | +| ------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to remove assignment. | + +#### Example request + +```http +DELETE /api/access-control/users/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 user." +} +``` + +#### 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 user role assignments + +`PUT /api/access-control/users/:userId/roles` + +Update the user'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 user role assignment]({{< ref "#add-a-user-role-assignment" >}}) or +[Remove a user role assignment]({{< ref "#remove-a-user-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 which will allow to do that. This is done to prevent escalation of privileges. + +| Action | Scope | +| ------------------ | -------------------- | +| users.roles:add | permissions:delegate | +| users.roles:remove | permissions:delegate | + +#### Example request + +```http +PUT /api/access-control/users/1/roles +Accept: application/json +Content-Type: application/json + +{ + "global": false, + "roleUids": [ + "ZiHQJq5nk", + "GzNQ1357k" + ] +} +``` + +#### JSON body schema + +| Field Name | Date Type | Required | Description | +| ---------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request. | +| roleUids | list | Yes | List of role UIDs. | + +#### Example response + +```http +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 + +{ + "message": "User 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. @@ -444,7 +761,7 @@ Content-Type: application/json; charset=UTF-8 "uid": "qQui_LCMk", "name": "fixed:users:org:edit", "description": "", - "global": true, + "global": false, "updated": "2021-05-13T16:24:26+02:00", "created": "2021-05-13T16:24:26+02:00" }, @@ -453,7 +770,7 @@ Content-Type: application/json; charset=UTF-8 "uid": "PeXmlYjMk", "name": "fixed:users:org:read", "description": "", - "global": true, + "global": false, "updated": "2021-05-13T16:24:26+02:00", "created": "2021-05-13T16:24:26+02:00" } @@ -464,7 +781,7 @@ Content-Type: application/json; charset=UTF-8 "uid": "qQui_LCMk", "name": "fixed:users:org:edit", "description": "", - "global": true, + "global": false, "updated": "2021-05-13T16:24:26+02:00", "created": "2021-05-13T16:24:26+02:00" }