Docs: Fine-grained access control refactor (#47536)
* fleshing out About topic * docs, fgac refactor initial draft * updated FGAC with service account details * finalized restructure * make prettier, corrects spelling * fixes typo * adds rollout strategy topic * started name change * renamed to rbac throughout docs * copy edit to about and actions and scopes docs * finishes content reorg * draft of refactored refactored docs * corrects relrefs * formatting tweaks * fixes typo * copy updates to about rbac * rbac rollout docs edits * update rbac role assignment docs * content update to manage rbac roles doc * sort and reorder roles reference in rbac docs * alphabetize permissions table * Update docs/sources/enterprise/settings-updates.md Co-authored-by: Mitch Seaman <mjseaman@users.noreply.github.com> * incorporates feedback, makes prettier * update http api references in rbac docs * fix broken refs and improve wording on enabling RBAC provisioning Co-authored-by: eleijonmarck <eric.leijonmarck@gmail.com> Co-authored-by: Mitchel Seaman <mitchel.seaman@gmail.com> Co-authored-by: Mitch Seaman <mjseaman@users.noreply.github.com>
This commit is contained in:
Christopher Moyer
co-authored by
Mitch Seaman
eleijonmarck
Mitchel Seaman
Mitch Seaman
eleijonmarck
Mitchel Seaman
parent
647f749652
commit
a20b3e2d59
@@ -39,7 +39,7 @@ dashboards, creating users, and updating data sources.
|
||||
|
||||
Grafana Enterprise includes all of the Grafana OSS APIs as well as those that follow:
|
||||
|
||||
- [Fine-grained access control API]({{< relref "access_control.md" >}})
|
||||
- [Role-based access control API]({{< relref "access_control.md" >}})
|
||||
- [Data source permissions API]({{< relref "datasource_permissions.md" >}})
|
||||
- [External group sync API]({{< relref "external_group_sync.md" >}})
|
||||
- [License API]({{< relref "licensing.md" >}})
|
||||
|
||||
@@ -1,16 +1,16 @@
|
||||
+++
|
||||
title = "Fine-grained access control HTTP API "
|
||||
description = "Fine-grained access control API"
|
||||
keywords = ["grafana", "http", "documentation", "api", "fine-grained-access-control", "acl", "enterprise"]
|
||||
title = "RBAC HTTP API"
|
||||
description = ""
|
||||
keywords = ["grafana", "http", "documentation", "api", "role-based-access-control", "acl", "enterprise"]
|
||||
aliases = ["/docs/grafana/latest/http_api/accesscontrol/"]
|
||||
+++
|
||||
|
||||
# Fine-grained access control API
|
||||
# RBAC API
|
||||
|
||||
> Fine-grained access control API is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../enterprise" >}}).
|
||||
> Role-based access control API is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../enterprise" >}}).
|
||||
|
||||
The API can be used to create, update, get and list roles, and create or remove built-in role assignments.
|
||||
To use the API, you would need to [enable fine-grained access control]({{< relref "../enterprise/access-control/_index.md#enable-fine-grained-access-control" >}}).
|
||||
To use the API, you would need to [enable role-based access control]({{< relref "../enterprise/access-control/_index.md#enable-role-based-access-control" >}}).
|
||||
|
||||
The API does not currently work with an API Token. So in order to use these API endpoints you will have to use [Basic auth]({{< relref "./auth/#basic-auth" >}}).
|
||||
|
||||
@@ -18,9 +18,9 @@ The API does not currently work with an API Token. So in order to use these API
|
||||
|
||||
`GET /api/access-control/status`
|
||||
|
||||
Returns an indicator to check if fine-grained access control is enabled or not.
|
||||
Returns an indicator to check if role-based access control is enabled or not.
|
||||
|
||||
### Required permissions
|
||||
#### Required permissions
|
||||
|
||||
| Action | Scope |
|
||||
| -------------------- | ---------------------- |
|
||||
@@ -47,12 +47,12 @@ Content-Type: application/json; charset=UTF-8
|
||||
|
||||
#### Status codes
|
||||
|
||||
| Code | Description |
|
||||
| ---- | ---------------------------------------------------------------------------------- |
|
||||
| 200 | Returned a flag indicating if the fine-grained access control is enabled or no. |
|
||||
| 403 | Access denied |
|
||||
| 404 | Not found, an indication that fine-grained access control is not available at all. |
|
||||
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
|
||||
| Code | Description |
|
||||
| ---- | -------------------------------------------------------------------------------- |
|
||||
| 200 | Returned a flag indicating if the role-based access control is enabled or no. |
|
||||
| 403 | Access denied |
|
||||
| 404 | Not found, an indication that role-based access control is not available at all. |
|
||||
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
|
||||
|
||||
## Create and manage custom roles
|
||||
|
||||
@@ -62,7 +62,7 @@ Content-Type: application/json; charset=UTF-8
|
||||
|
||||
Gets all existing roles. The response contains all global and organization local roles, for the organization which user is signed in.
|
||||
|
||||
Refer to the [Role scopes]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information.
|
||||
Refer to the [Basic roles]({{< relref "../enterprise/access-control/about-rbac#basic-roles" >}}) for more information.
|
||||
|
||||
Query Parameters:
|
||||
|
||||
@@ -215,7 +215,7 @@ Content-Type: application/json; charset=UTF-8
|
||||
|
||||
`POST /api/access-control/roles`
|
||||
|
||||
Creates a new custom role and maps given permissions to that role. Note that roles with the same prefix as [Fixed Roles]({{< relref "../enterprise/access-control/roles.md" >}}) can't be created.
|
||||
Creates a new custom role and maps given permissions to that role. Note that roles with the same prefix as [Fixed roles]({{< relref "../enterprise/access-control/about-rbac#fixed-roles" >}}) can't be created.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
@@ -253,24 +253,24 @@ Content-Type: application/json
|
||||
|
||||
#### JSON body schema
|
||||
|
||||
| Field Name | Date Type | Required | Description |
|
||||
| ----------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| uid | string | No | UID of the role. If not present, the UID will be automatically created for you and returned in response. Refer to the [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information. |
|
||||
| global | boolean | No | A flag indicating if the role is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request. Refer to the [Role scopes]({{< relref "../enterprise/access-control/roles.md#role-scopes" >}}) for more information. |
|
||||
| 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. |
|
||||
| hidden | boolean | No | Specify whether the role is hidden or not. If set to `true`, then the role does not show in the role picker. It will not be listed by API endpoints unless explicitly specified. |
|
||||
| permissions | Permission | No | If not present, the role will be created without any permissions. |
|
||||
| Field Name | Date Type | Required | Description |
|
||||
| ----------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| uid | string | No | UID of the role. If not present, the UID will be automatically created for you and returned in response. Refer to the [Custom roles]({{< relref "../enterprise/access-control/about-rbac#custom-roles" >}}) for more information. |
|
||||
| global | boolean | No | A flag indicating if the role is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request. |
|
||||
| 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/about-rbac#custom-roles" >}}) for more information. |
|
||||
| name | string | Yes | Name of the role. Refer to [Custom roles]({{< relref "../enterprise/access-control/about-rbac#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. |
|
||||
| hidden | boolean | No | Specify whether the role is hidden or not. If set to `true`, then the role does not show in the role picker. It will not be listed by API endpoints unless explicitly specified. |
|
||||
| permissions | Permission | No | If not present, the role will be created without any permissions. |
|
||||
|
||||
**Permission**
|
||||
|
||||
| Field Name | Data Type | Required | Description |
|
||||
| ---------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| action | string | Yes | Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md" >}}) for full list of available actions. |
|
||||
| scope | string | No | If not present, no scope will be mapped to the permission. Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md#scope-definitions" >}}) for full list of available scopes. |
|
||||
| Field Name | Data Type | Required | Description |
|
||||
| ---------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| action | string | Yes | Refer to [Custom role actions and scopes]({{< relref "../enterprise/access-control/custom-role-actions-scopes" >}}) for full list of available actions. |
|
||||
| scope | string | No | If not present, no scope will be mapped to the permission. Refer to [[Custom role actions and scopes]({{< relref "../enterprise/access-control/custom-role-actions-scopes" >}}) for full list of available scopes. |
|
||||
|
||||
#### Example response
|
||||
|
||||
@@ -366,10 +366,10 @@ Content-Type: application/json
|
||||
|
||||
**Permission**
|
||||
|
||||
| Field Name | Data Type | Required | Description |
|
||||
| ---------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| action | string | Yes | Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md" >}}) for full list of available actions. |
|
||||
| scope | string | No | If not present, no scope will be mapped to the permission. Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md#scope-definitions" >}}) for full list of available scopes. |
|
||||
| Field Name | Data Type | Required | Description |
|
||||
| ---------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| action | string | Yes | Refer to [Custom role actions and scopes]({{< relref "../enterprise/access-control/custom-role-actions-scopes" >}}) for full list of available actions. |
|
||||
| scope | string | No | If not present, no scope will be mapped to the permission. Refer to [Custom role actions and scopes]({{< relref "../enterprise/access-control/custom-role-actions-scopes" >}}) for full list of available scopes. |
|
||||
|
||||
#### Example response
|
||||
|
||||
@@ -439,10 +439,10 @@ Accept: application/json
|
||||
|
||||
#### Query parameters
|
||||
|
||||
| Param | Type | Required | Description |
|
||||
| ------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| force | boolean | No | When set to `true`, the role will be deleted with all it's assignments. |
|
||||
| global | boolean | No | A flag indicating if the role is global or not. If set to false, the default org ID of the authenticated user will be used from the request. Refer to the [Role scopes]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information. |
|
||||
| Param | Type | Required | Description |
|
||||
| ------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| force | boolean | No | When set to `true`, the role will be deleted with all it's assignments. |
|
||||
| global | boolean | No | A flag indicating if the role is global or not. If set to false, the default org ID of the authenticated user will be used from the request. Refer to the [About RBAC]({{< relref "../enterprise/access-control/about-rbac" >}}) for more information. |
|
||||
|
||||
#### Example response
|
||||
|
||||
@@ -955,9 +955,11 @@ 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 built-in role assignments
|
||||
## Create and remove built-in (basic) 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.
|
||||
API set allows to create or remove [basic role assignments]({{< relref "../enterprise/access-control/assign-rbac-roles" >}}) and list current assignments.
|
||||
|
||||
> **Note:** Basic roles are referred to as **"built-in"** roles in the API. "Basic" and "built-in" refer to the same thing: the Grafana Administrator, Org Administrator, Editor, and Viewer roles.
|
||||
|
||||
### Get all built-in role assignments
|
||||
|
||||
@@ -1066,11 +1068,11 @@ Content-Type: application/json
|
||||
|
||||
#### JSON body schema
|
||||
|
||||
| Field Name | Date Type | Required | Description |
|
||||
| ----------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| roleUid | string | Yes | UID of the role. |
|
||||
| builtinRole | boolean | Yes | Can be one of `Viewer`, `Editor`, `Admin` or `Grafana Admin`. |
|
||||
| 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. Refer to the [Built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information. |
|
||||
| Field Name | Date Type | Required | Description |
|
||||
| ----------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| roleUid | string | Yes | UID of the role. |
|
||||
| builtinRole | boolean | Yes | Can be one of `Viewer`, `Editor`, `Admin` or `Grafana Admin`. |
|
||||
| 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
|
||||
|
||||
@@ -1117,9 +1119,9 @@ Accept: application/json
|
||||
|
||||
#### 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. Refer to the [Built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information. |
|
||||
| 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 response
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ The Admin HTTP API does not currently work with an API Token. API Tokens are cur
|
||||
the permission of server admin, only users can be given that permission. So in order to use these API calls you will have to use Basic Auth and the Grafana user
|
||||
must have the Grafana Admin permission. (The default admin user is called `admin` and has permission to use this API.)
|
||||
|
||||
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
> If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
> Refer to specific resources to understand what permissions are required.
|
||||
|
||||
## Fetch settings
|
||||
|
||||
@@ -9,7 +9,7 @@ aliases = ["/docs/grafana/latest/http_api/annotations/"]
|
||||
|
||||
This is the API documentation for the new Grafana Annotations feature released in Grafana 4.6. Annotations are saved in the Grafana database (sqlite, mysql or postgres). Annotations can be organization annotations that can be shown on any dashboard by configuring an annotation data source - they are filtered by tags. Or they can be tied to a panel on a dashboard and are then only shown on that panel.
|
||||
|
||||
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, access to endpoints will be controlled by Fine-grained access control permissions.
|
||||
> If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, access to endpoints will be controlled by role-based access control permissions.
|
||||
> Refer to specific endpoints to understand what permissions are required.
|
||||
|
||||
## Find Annotations
|
||||
|
||||
@@ -7,7 +7,7 @@ aliases = ["/docs/grafana/latest/http_api/datasource/"]
|
||||
|
||||
# Data source API
|
||||
|
||||
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
> If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
> Refer to specific resources to understand what permissions are required.
|
||||
|
||||
## Get all data sources
|
||||
|
||||
@@ -9,7 +9,7 @@ aliases = ["/docs/grafana/latest/http_api/datasourcepermissions/"]
|
||||
|
||||
> The Data Source Permissions is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../enterprise" >}}).
|
||||
|
||||
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
> If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
> Refer to specific resources to understand what permissions are required.
|
||||
|
||||
This API can be used to enable, disable, list, add and remove permissions for a data source.
|
||||
|
||||
@@ -9,7 +9,7 @@ aliases = ["/docs/grafana/latest/http_api/external_group_sync/"]
|
||||
|
||||
> External Group Synchronization is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../enterprise" >}}).
|
||||
|
||||
> If you have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, access to endpoints will be controlled by Fine-grained access control permissions.
|
||||
> If you have [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, access to endpoints will be controlled by role-based access control permissions.
|
||||
> Refer to specific endpoints to understand what permissions are required.
|
||||
|
||||
## Get External Groups
|
||||
|
||||
@@ -9,7 +9,7 @@ aliases = ["/docs/grafana/latest/http_api/licensing/"]
|
||||
|
||||
Licensing is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../enterprise" >}}).
|
||||
|
||||
If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
Refer to specific resources to understand what permissions are required.
|
||||
|
||||
## Check license availability
|
||||
|
||||
@@ -11,7 +11,7 @@ The Organization HTTP API is divided in two resources, `/api/org` (current organ
|
||||
and `/api/orgs` (admin organizations). One big difference between these are that
|
||||
the admin of all organizations API only works with basic authentication, see [Admin Organizations API](#admin-organizations-api) for more information.
|
||||
|
||||
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
> If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
> Refer to specific resources to understand what permissions are required.
|
||||
|
||||
## Current Organization API
|
||||
|
||||
@@ -11,7 +11,7 @@ This API allows you to interact programmatically with the [Reporting]({{< relref
|
||||
|
||||
> Reporting is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../enterprise" >}}).
|
||||
|
||||
> If you have [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
> If you have [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
> Refer to specific resources to understand what permissions are required.
|
||||
|
||||
## Send a report
|
||||
|
||||
@@ -16,7 +16,7 @@ Access to these API endpoints is restricted as follows:
|
||||
- If you enable `editors_can_admin` configuration flag, then Organization Editors can create teams and manage teams where they are Admin.
|
||||
- If you enable `editors_can_admin` configuration flag, Editors can find out whether a team that they are not members of exists by trying to create a team with the same name.
|
||||
|
||||
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, access to endpoints will be controlled by Fine-grained access control permissions.
|
||||
> If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, access to endpoints will be controlled by role-based access control permissions.
|
||||
> Refer to specific endpoints to understand what permissions are required.
|
||||
|
||||
## Team Search With Paging
|
||||
|
||||
@@ -7,7 +7,7 @@ aliases = ["/docs/grafana/latest/http_api/user/"]
|
||||
|
||||
# User API
|
||||
|
||||
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
> If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
|
||||
> Refer to specific resources to understand what permissions are required.
|
||||
|
||||
## Search Users
|
||||
|
||||
Reference in New Issue
Block a user