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

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

Browse Source 
(cherry picked from commit 5043448769)

Co-authored-by: Mitch Seaman <mjseaman@users.noreply.github.com>
This commit is contained in:
Grot (@grafanabot)
2021-11-24 23:06:28 +01:00
committed by GitHub
co-authored by Mitch Seaman
parent 5412a903b1
commit 3e437fb3be
10 changed files with 479 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/http_api/access_control.md
+356 -39
View File
@@ -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:`<user 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:`<user 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"
}