IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

RBAC: update data source permission API reference (#76613)

Browse Source 
* update data source permission docs

* Update datasource_permissions.md

* Update docs/sources/developers/http_api/datasource_permissions.md

Co-authored-by: Gabriel MABILLE <gamab@users.noreply.github.com>

* Apply suggestions from code review

---------

Co-authored-by: Gabriel MABILLE <gamab@users.noreply.github.com>
This commit is contained in:
Ieva 2023-10-24 14:51:12 +01:00 committed by GitHub
parent ed54239a9f
commit 7a9ec6b4e0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 185 additions and 156 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

341
docs/sources/developers/http_api/datasource_permissions.md
View File

@ -27,124 +27,30 @@ title: Datasource Permissions HTTP API
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes" >}}) for more information. > If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes" >}}) for more information.
This API can be used to enable, disable, list, add and remove permissions for a data source. This API can be used to list, add and remove permissions for a data source.
Permissions can be set for a user or a team. Permissions cannot be set for Admins - they always have access to everything. Permissions can be set for a user, team, service account or a basic role (Admin, Editor, Viewer).
The permission levels for the permission field:
- 1 = Query
## Enable permissions for a data source
`POST /api/datasources/:id/enable-permissions`
Enables permissions for the data source with the given `id`. No one except Org Admins will be able to query the data source until permissions have been added which permit certain users or teams to query the data source.
**Required permissions**
See note in the [introduction]({{< ref "#data-source-permissions-api" >}}) for an explanation.
| Action | Scope |
| ----------------------------- | ---------------------------------------------------------------------------- |
| datasources.permissions:write | datasources:\*<br>datasources:id:\*<br>datasources:id:1 (single data source) |
### Examples
**Example request:**
```http
POST /api/datasources/1/enable-permissions
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{}
```
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 35
{"message":"Datasource permissions enabled"}
```
Status codes:
- **200** - Ok
- **400** - Permissions cannot be enabled, see response body for details
- **401** - Unauthorized
- **403** - Access denied
- **404** - Datasource not found
## Disable permissions for a data source
`POST /api/datasources/:id/disable-permissions`
Disables permissions for the data source with the given `id`. All existing permissions will be removed and anyone will be able to query the data source.
**Required permissions**
See note in the [introduction]({{< ref "#data-source-permissions-api" >}}) for an explanation.
| Action | Scope |
| ----------------------------- | ---------------------------------------------------------------------------- |
| datasources.permissions:write | datasources:\*<br>datasources:id:\*<br>datasources:id:1 (single data source) |
### Examples
**Example request:**
```http
POST /api/datasources/1/disable-permissions
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{}
```
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 35
{"message":"Datasource permissions disabled"}
```
Status codes:
- **200** - Ok
- **400** - Permissions cannot be disabled, see response body for details
- **401** - Unauthorized
- **403** - Access denied
- **404** - Datasource not found
## Get permissions for a data source ## Get permissions for a data source
`GET /api/datasources/:id/permissions` `GET /api/access-control/datasources/:uid`
Gets all existing permissions for the data source with the given `id`. Gets all existing permissions for the data source with the given `uid`.
**Required permissions** **Required permissions**
See note in the [introduction]({{< ref "#data-source-permissions-api" >}}) for an explanation. See note in the [introduction]({{< ref "#data-source-permissions-api" >}}) for an explanation.
| Action | Scope | | Action | Scope |
| ---------------------------- | ---------------------------------------------------------------------------- | | ---------------------------- | ------------------------------------------------------------------------------------------ |
| datasources.permissions:read | datasources:\*<br>datasources:id:\*<br>datasources:id:1 (single data source) | | datasources.permissions:read | datasources:\*<br>datasources:uid:\*<br>datasources:uid:my_datasource (single data source) |
### Examples ### Examples
**Example request:** **Example request:**
```http ```http
GET /api/datasources/1/permissions HTTP/1.1 GET /api/access-control/datasources/my_datasource HTTP/1.1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
@ -157,36 +63,57 @@ HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8 Content-Type: application/json; charset=UTF-8
Content-Length: 551 Content-Length: 551
{ [
"datasourceId": 1,
"enabled": true,
"permissions":
[
{ {
"id": 1, "id": 1,
"datasourceId": 1, "roleName": "fixed:datasources:reader",
"userId": 1, "isManaged": false,
"userLogin": "user", "isInherited": false,
"userEmail": "user@test.com", "isServiceAccount": false,
"userAvatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56", "userId": 1,
"permission": 1, "userLogin": "admin_user",
"permissionName": "Query", "userAvatarUrl": "/avatar/admin_user",
"created": "2017-06-20T02:00:00+02:00", "actions": [
"updated": "2017-06-20T02:00:00+02:00", "datasources:read",
"datasources:query",
"datasources:read",
"datasources:query",
"datasources:write",
"datasources:delete"
],
"permission": "Edit"
}, },
{ {
"id": 2, "id": 2,
"datasourceId": 1, "roleName": "managed:teams:1:permissions",
"teamId": 1, "isManaged": true,
"team": "A Team", "isInherited": false,
"teamAvatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56", "isServiceAccount": false,
"permission": 1, "team": "A team",
"permissionName": "Query", "teamId": 1,
"created": "2017-06-20T02:00:00+02:00", "teamAvatarUrl": "/avatar/523d70c8551046f441727d690431858c",
"updated": "2017-06-20T02:00:00+02:00", "actions": [
} "datasources:read",
] "datasources:query"
} ],
"permission": "Query"
},
{
"id": 3,
"roleName": "basic:admin",
"isManaged": false,
"isInherited": false,
"isServiceAccount": false,
"builtInRole": "Admin",
"actions": [
"datasources:query",
"datasources:read",
"datasources:write",
"datasources:delete"
],
"permission": "Edit"
},
]
``` ```
Status codes: Status codes:
@ -194,35 +121,37 @@ Status codes:
- **200** - Ok - **200** - Ok
- **401** - Unauthorized - **401** - Unauthorized
- **403** - Access denied - **403** - Access denied
- **404** - Datasource not found - **500** - Internal error
## Add permission for a data source ## Add or revoke access to a data source for a user
`POST /api/datasources/:id/permissions` `POST /api/access-control/datasources/:uid/users/:id`
Adds a user permission for the data source with the given `id`. Sets user permission for the data source with the given `uid`.
To add a permission, set the `permission` field to either `Query`, `Edit`, or `Admin`.
To remove a permission, set the `permission` field to an empty string.
**Required permissions** **Required permissions**
See note in the [introduction]({{< ref "#data-source-permissions-api" >}}) for an explanation. See note in the [introduction]({{< ref "#data-source-permissions-api" >}}) for an explanation.
| Action | Scope | | Action | Scope |
| ----------------------------- | ---------------------------------------------------------------------------- | | ----------------------------- | ------------------------------------------------------------------------------------------ |
| datasources.permissions:write | datasources:\*<br>datasources:id:\*<br>datasources:id:1 (single data source) | | datasources.permissions:write | datasources:\*<br>datasources:uid:\*<br>datasources:uid:my_datasource (single data source) |
### Examples ### Examples
**Example request:** **Example request:**
```http ```http
POST /api/datasources/1/permissions POST /api/access-control/datasources/my_datasource/users/1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{ {
"userId": 1, "permission": "Query",
"permission": 1
} }
``` ```
@ -233,22 +162,19 @@ HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8 Content-Type: application/json; charset=UTF-8
Content-Length: 35 Content-Length: 35
{"message":"Datasource permission added"} {"message": "Permission updated"}
``` ```
Adds a team permission for the data source with the given `id`.
**Example request:** **Example request:**
```http ```http
POST /api/datasources/1/permissions POST /api/access-control/datasources/my_datasource/users/1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{ {
"teamId": 1, "permission": "",
"permission": 1
} }
``` ```
@ -259,7 +185,7 @@ HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8 Content-Type: application/json; charset=UTF-8
Content-Length: 35 Content-Length: 35
{"message":"Datasource permission added"} {"message": "Permission removed"}
``` ```
Status codes: Status codes:
@ -268,31 +194,37 @@ Status codes:
- **400** - Permission cannot be added, see response body for details - **400** - Permission cannot be added, see response body for details
- **401** - Unauthorized - **401** - Unauthorized
- **403** - Access denied - **403** - Access denied
- **404** - Datasource not found
## Remove permission for a data source ## Add or revoke access to a data source for a team
`DELETE /api/datasources/:id/permissions/:permissionId` `POST /api/access-control/datasources/:uid/teams/:id`
Removes the permission with the given `permissionId` for the data source with the given `id`. Sets team permission for the data source with the given `uid`.
To add a permission, set the `permission` field to either `Query`, `Edit`, or `Admin`.
To remove a permission, set the `permission` field to an empty string.
**Required permissions** **Required permissions**
See note in the [introduction]({{< ref "#data-source-permissions-api" >}}) for an explanation. See note in the [introduction]({{< ref "#data-source-permissions-api" >}}) for an explanation.
| Action | Scope | | Action | Scope |
| ----------------------------- | ---------------------------------------------------------------------------- | | ----------------------------- | ------------------------------------------------------------------------------------------ |
| datasources.permissions:write | datasources:\*<br>datasources:id:\*<br>datasources:id:1 (single data source) | | datasources.permissions:write | datasources:\*<br>datasources:uid:\*<br>datasources:uid:my_datasource (single data source) |
### Examples ### Examples
**Example request:** **Example request:**
```http ```http
DELETE /api/datasources/1/permissions/2 POST /api/access-control/datasources/my_datasource/teams/1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"permission": "Edit",
}
``` ```
**Example response:** **Example response:**
@ -302,12 +234,109 @@ HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8 Content-Type: application/json; charset=UTF-8
Content-Length: 35 Content-Length: 35
{"message":"Datasource permission removed"} {"message": "Permission updated"}
```
**Example request:**
```http
POST /api/access-control/datasources/my_datasource/teams/1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"permission": "",
}
```
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 35
{"message": "Permission removed"}
``` ```
Status codes: Status codes:
- **200** - Ok - **200** - Ok
- **400** - Permission cannot be added, see response body for details
- **401** - Unauthorized
- **403** - Access denied
## Add or revoke access to a data source for a basic role
`POST /api/access-control/datasources/:uid/builtInRoles/:builtinRoleName`
Sets permission for the data source with the given `uid` to all users who have the specified basic role.
You can set permissions for the following basic roles: `Admin`, `Editor`, `Viewer`.
To add a permission, set the `permission` field to either `Query`, `Edit`, or `Admin`.
To remove a permission, set the `permission` field to an empty string.
**Required permissions**
See note in the [introduction]({{< ref "#data-source-permissions-api" >}}) for an explanation.
| Action | Scope |
| ----------------------------- | ------------------------------------------------------------------------------------------ |
| datasources.permissions:write | datasources:\*<br>datasources:uid:\*<br>datasources:uid:my_datasource (single data source) |
### Examples
**Example request:**
```http
POST /api/access-control/datasources/my_datasource/builtInRoles/Admin
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"permission": "Edit",
}
```
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 35
{"message": "Permission updated"}
```
**Example request:**
```http
POST /api/access-control/datasources/my_datasource/builtInRoles/Viewer
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"permission": "",
}
```
**Example response:**
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 35
{"message": "Permission removed"}
```
Status codes:
- **200** - Ok
- **400** - Permission cannot be added, see response body for details
- **401** - Unauthorized - **401** - Unauthorized
- **403** - Access denied - **403** - Access denied
- **404** - Datasource not found or permission not found