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 c3c52c1b2b6..3715bb13abc 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 @@ -38,13 +38,14 @@ The reference information that follows complements conceptual information about | `fixed:organization:reader` | `orgs:read`
`orgs.quotas:read` | Read an organization and its quotas. | | `fixed:organization:writer` | All permissions from `fixed:organization:reader` and
`orgs:write`
`orgs.preferences:read`
`orgs.preferences:write` | Read an organization, its quotas, or its preferences. Update organization properties, or its preferences. | | `fixed:organization:maintainer` | All permissions from `fixed:organization:reader` and
`orgs:write`
`orgs:create`
`orgs:delete`
`orgs.quotas:write` | Create, read, write, or delete an organization. Read or write its quotas. This role needs to be assigned globally. | -| | +| `fixed:teams:creator` ` | `teams:create`
`org.users:read` | Create a team and list organization users (required to manage the created team). | +| `fixed:teams:writer` | `teams:create`
`teams:delete`
`teams:read`
`teams:write`
`teams.permissions:read`
`teams.permissions:write` | Create, read, update and delete teams and manage team memberships. | ## Default built-in role assignments | Built-in role | Associated role | Description | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | Grafana Admin | `fixed:roles:reader`
`fixed:roles:writer`
`fixed:users:reader`
`fixed:users:writer`
`fixed:org.users:reader`
`fixed:org.users:writer`
`fixed:ldap:reader`
`fixed:ldap:writer`
`fixed:stats:reader`
`fixed:settings:reader`
`fixed:settings:writer`
`fixed:provisioning:writer`
`fixed:organization:reader`
`fixed:organization:maintainer`
`fixed:licensing:reader`
`fixed:licensing:writer` | Default [Grafana server administrator]({{< relref "../../permissions/_index.md#grafana-server-admin-role" >}}) assignments. | -| Admin | `fixed:reports:reader`
`fixed:reports:writer`
`fixed:datasources:reader`
`fixed:datasources:writer`
`fixed:organization:writer`
`fixed:datasources.permissions:reader`
`fixed:datasources.permissions:writer`
| Default [Grafana organization administrator]({{< relref "../../permissions/organization_roles.md" >}}) assignments. | -| Editor | `fixed:datasources:explorer` | Default [Editor]({{< relref "../../permissions/organization_roles.md" >}}) assignments. | +| Admin | `fixed:reports:reader`
`fixed:reports:writer`
`fixed:datasources:reader`
`fixed:datasources:writer`
`fixed:organization:writer`
`fixed:datasources.permissions:reader`
`fixed:datasources.permissions:writer`
`fixed:teams:writer`
| Default [Grafana organization administrator]({{< relref "../../permissions/organization_roles.md" >}}) assignments. | +| Editor | `fixed:datasources:explorer` and
`fixed:teams:creator` if the `editors_can_admin` configuration flag is enabled | Default [Editor]({{< relref "../../permissions/organization_roles.md" >}}) assignments. | | Viewer | `fixed:datasources:id:reader`
`fixed:organization:reader` | Default [Viewer]({{< relref "../../permissions/organization_roles.md" >}}) assignments. | diff --git a/docs/sources/enterprise/access-control/permissions.md b/docs/sources/enterprise/access-control/permissions.md index 372a008aec4..c37afbb04a3 100644 --- a/docs/sources/enterprise/access-control/permissions.md +++ b/docs/sources/enterprise/access-control/permissions.md @@ -94,6 +94,12 @@ The following list contains fine-grained access control actions. | `licensing:update` | n/a | Update the license token. | | `licensing:delete` | n/a | Delete the license token. | | `licensing.reports:read` | n/a | Get custom permission reports. | +| `teams:create` | n/a | Create teams. | +| `teams:read` | `teams:*`
`teams:id:*` | Read one or more teams and team preferences. | +| `teams:write` | `teams:*`
`teams:id:*` | Update one or more teams and team preferences. | +| `teams:delete` | `teams:*`
`teams:id:*` | Delete one or more teams. | +| `teams.permissions:read` | `teams:*`
`teams:id:*` | Read members and External Group Synchronization setup for teams. | +| `teams.permissions:write` | `teams:*`
`teams:id:*` | Add, remove and update members and manage External Group Synchronization setup for teams. | ## Scope definitions diff --git a/docs/sources/http_api/external_group_sync.md b/docs/sources/http_api/external_group_sync.md index 4930de025f5..095739bd7e1 100644 --- a/docs/sources/http_api/external_group_sync.md +++ b/docs/sources/http_api/external_group_sync.md @@ -9,10 +9,21 @@ 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. +> Refer to specific endpoints to understand what permissions are required. + ## Get External Groups `GET /api/teams/:teamId/groups` +#### Required permissions + +See note in the [introduction]({{< ref "#team-api" >}}) for an explanation. + +| Action | Scope | +| ---------------------- | -------- | +| teams.permissions:read | teams:\* | + **Example Request**: ```http @@ -47,6 +58,14 @@ Status Codes: `POST /api/teams/:teamId/groups` +#### Required permissions + +See note in the [introduction]({{< ref "#team-api" >}}) for an explanation. + +| Action | Scope | +| ----------------------- | -------- | +| teams.permissions:write | teams:\* | + **Example Request**: ```http @@ -81,6 +100,14 @@ Status Codes: `DELETE /api/teams/:teamId/groups/:groupId` +#### Required permissions + +See note in the [introduction]({{< ref "#team-api" >}}) for an explanation. + +| Action | Scope | +| ----------------------- | -------- | +| teams.permissions:write | teams:\* | + **Example Request**: ```http diff --git a/docs/sources/http_api/team.md b/docs/sources/http_api/team.md index f530a6f2cf4..967ba415114 100644 --- a/docs/sources/http_api/team.md +++ b/docs/sources/http_api/team.md @@ -15,6 +15,9 @@ Access to these API endpoints is restricted as follows: - Organization Admins are able to manage all teams and team members. - If the `editors_can_admin` configuration flag is enabled, Organization Editors are able to view details of all teams and to manage teams that they are Admin members of. +> 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. +> Refer to specific endpoints to understand what permissions are required. + ## Team Search With Paging `GET /api/teams/search?perpage=50&page=1&query=myteam` @@ -23,25 +26,23 @@ or `GET /api/teams/search?name=myteam` +#### Required permissions + +See note in the [introduction]({{< ref "#team-api" >}}) for an explanation. + +| Action | Scope | +| ---------- | -------- | +| teams:read | teams:\* | + +**Example Request**: + ```http -GET /api/teams/search?perpage=10&page=1&query=myteam HTTP/1.1 +GET /api/teams/search?perpage=10&page=1&query=mytestteam HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Basic YWRtaW46YWRtaW4= ``` -### Using the query parameter - -Default value for the `perpage` parameter is `1000` and for the `page` parameter is `1`. - -The `totalCount` field in the response can be used for pagination of the teams list E.g. if `totalCount` is equal to 100 teams and the `perpage` parameter is set to 10 then there are 10 pages of teams. - -The `query` parameter is optional and it will return results where the query value is contained in the `name` field. Query values with spaces need to be URL encoded e.g. `query=my%20team`. - -### Using the name parameter - -The `name` parameter returns a single team if the parameter matches the `name` field. - **Example Response**: ```http @@ -65,7 +66,19 @@ Content-Type: application/json } ``` -Status Codes: +### Using the query parameter + +Default value for the `perpage` parameter is `1000` and for the `page` parameter is `1`. + +The `totalCount` field in the response can be used for pagination of the teams list E.g. if `totalCount` is equal to 100 teams and the `perpage` parameter is set to 10 then there are 10 pages of teams. + +The `query` parameter is optional and it will return results where the query value is contained in the `name` field. Query values with spaces need to be URL encoded e.g. `query=my%20team`. + +### Using the name parameter + +The `name` parameter returns a single team if the parameter matches the `name` field. + +#### Status Codes: - **200** - Ok - **401** - Unauthorized @@ -76,6 +89,14 @@ Status Codes: `GET /api/teams/:id` +#### Required permissions + +See note in the [introduction]({{< ref "#team-api" >}}) for an explanation. + +| Action | Scope | +| ---------- | -------- | +| teams:read | teams:\* | + **Example Request**: ```http @@ -114,6 +135,14 @@ The Team `name` needs to be unique. `name` is required and `email`,`orgId` is op `POST /api/teams` +#### Required permissions + +See note in the [introduction]({{< ref "#team-api" >}}) for an explanation. + +| Action | Scope | +| ------------ | ----- | +| teams:create | N/A | + **Example Request**: ```http @@ -151,6 +180,14 @@ There are two fields that can be updated for a team: `name` and `email`. `PUT /api/teams/:id` +#### Required permissions + +See note in the [introduction]({{< ref "#team-api" >}}) for an explanation. + +| Action | Scope | +| ----------- | -------- | +| teams:write | teams:\* | + **Example Request**: ```http @@ -186,6 +223,14 @@ Status Codes: `DELETE /api/teams/:id` +#### Required permissions + +See note in the [introduction]({{< ref "#team-api" >}}) for an explanation. + +| Action | Scope | +| ------------ | -------- | +| teams:delete | teams:\* | + **Example Request**: ```http @@ -215,6 +260,14 @@ Status Codes: `GET /api/teams/:teamId/members` +#### Required permissions + +See note in the [introduction]({{< ref "#team-api" >}}) for an explanation. + +| Action | Scope | +| ---------------------- | -------- | +| teams.permissions:read | teams:\* | + **Example Request**: ```http @@ -260,6 +313,14 @@ Status Codes: `POST /api/teams/:teamId/members` +#### Required permissions + +See note in the [introduction]({{< ref "#team-api" >}}) for an explanation. + +| Action | Scope | +| ----------------------- | -------- | +| teams.permissions:write | teams:\* | + **Example Request**: ```http @@ -294,6 +355,14 @@ Status Codes: `DELETE /api/teams/:teamId/members/:userId` +#### Required permissions + +See note in the [introduction]({{< ref "#team-api" >}}) for an explanation. + +| Action | Scope | +| ----------------------- | -------- | +| teams.permissions:write | teams:\* | + **Example Request**: ```http @@ -323,6 +392,14 @@ Status Codes: `GET /api/teams/:teamId/preferences` +#### Required permissions + +See note in the [introduction]({{< ref "#team-api" >}}) for an explanation. + +| Action | Scope | +| ---------- | -------- | +| teams:read | teams:\* | + **Example Request**: ```http @@ -349,6 +426,14 @@ Content-Type: application/json `PUT /api/teams/:teamId/preferences` +#### Required permissions + +See note in the [introduction]({{< ref "#team-api" >}}) for an explanation. + +| Action | Scope | +| ----------- | -------- | +| teams:write | teams:\* | + **Example Request**: ```http