diff --git a/CHANGELOG.md b/CHANGELOG.md
index a9738006ddf..3e6627f9103 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -524,7 +524,7 @@ The access mode "browser" is deprecated in the following data sources and will b
### Features and enhancements
-- **AccessControl:** Apply fine-grained access control to licensing. (Enterprise)
+- **AccessControl:** Apply role-based access control to licensing. (Enterprise)
- **Alerting:** Add UI for contact point testing with custom annotations and labels. [#40491](https://github.com/grafana/grafana/pull/40491), [@nathanrodman](https://github.com/nathanrodman)
- **Alerting:** Make alert state indicator in panel header work with Grafana 8 alerts. [#38713](https://github.com/grafana/grafana/pull/38713), [@domasx2](https://github.com/domasx2)
- **Alerting:** Option for Discord notifier to use webhook name. [#40463](https://github.com/grafana/grafana/pull/40463), [@Skyebold](https://github.com/Skyebold)
diff --git a/docs/sources/administration/manage-users-and-permissions/about-users-and-permissions.md b/docs/sources/administration/manage-users-and-permissions/about-users-and-permissions.md
index fae09d88af4..82b3a24e4d6 100644
--- a/docs/sources/administration/manage-users-and-permissions/about-users-and-permissions.md
+++ b/docs/sources/administration/manage-users-and-permissions/about-users-and-permissions.md
@@ -14,7 +14,7 @@ You can assign a user one of three types of permissions:
- Organization permissions: Manage access to dashboards, alerts, plugins, teams, playlists, and other resources for an entire organization. The available roles are Viewer, Editor, and Admin.
- Dashboard and folder permission: Manage access to dashboards and folders
-> **Note**: If you are running Grafana Enterprise, you can also control access to data sources and use fine-grained access control to grant read and write permissions for specific resources. For more information about access control options available with Grafana Enterprise, refer to [Grafana Enterprise user permissions features](#grafana-enterprise-user-permissions-features).
+> **Note**: If you are running Grafana Enterprise, you can also control access to data sources and use role-based access control to grant user access to read and write permissions to specific Grafana resources. For more information about access control options available with Grafana Enterprise, refer to [Grafana Enterprise user permissions features](#grafana-enterprise-user-permissions-features).
## Grafana server administrators
@@ -133,7 +133,7 @@ While Grafana OSS includes a robust set of permissions and settings that you can
Grafana Enterprise provides the following permissions-related features:
- Data source permissions
-- Fine-grained access control
+- Role-based access control (RBAC)
### Data source permissions
@@ -141,11 +141,11 @@ By default, a user can query any data source in an organization, even if the dat
Data source permissions enable you to restrict data source query permissions to specific **Users** and **Teams**. For more information about assigning data source permissions, refer to [Data source permissions]({{< relref "../../enterprise/datasource_permissions.md" >}}).
-### Fine-grained access control
+### Role-based access control
-Fine-grained access control provides you a way of granting, changing, and revoking user read and write access to Grafana resources, such as users, reports, and authentication.
+RBAC provides you a way of granting, changing, and revoking user read and write access to Grafana resources, such as users, reports, and authentication.
-For more information about fine-grained access control, refer to [Fine-grained access control]({{< relref "../../enterprise/access-control" >}}).
+For more information about RBAC, refer to [Role-based access control]({{< relref "../../enterprise/access-control" >}}).
### Learn more
diff --git a/docs/sources/administration/manage-users-and-permissions/manage-dashboard-permissions/_index.md b/docs/sources/administration/manage-users-and-permissions/manage-dashboard-permissions/_index.md
index e22c5a2dca8..98a51a8590c 100644
--- a/docs/sources/administration/manage-users-and-permissions/manage-dashboard-permissions/_index.md
+++ b/docs/sources/administration/manage-users-and-permissions/manage-dashboard-permissions/_index.md
@@ -140,4 +140,4 @@ Dashboard permissions settings:
Result: You receive an error message that cannot override a higher permission with a lower permission in the same dashboard. User1 has administrator permissions.
-> Refer to [Fine-grained access Control]({{< relref "../../../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how to use fine-grained permissions to restrict access to dashboards, folders, administrative functions, and other resources.
+> Refer to [Role-based access Control]({{< relref "../../../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how to use RBAC permissions to restrict access to dashboards, folders, administrative functions, and other resources.
diff --git a/docs/sources/administration/provisioning.md b/docs/sources/administration/provisioning.md
index 910e0512ef0..a79941f3c11 100644
--- a/docs/sources/administration/provisioning.md
+++ b/docs/sources/administration/provisioning.md
@@ -601,4 +601,4 @@ The following sections detail the supported settings and secure settings for eac
Grafana Enterprise supports provisioning for the following resources:
-- [Access Control Provisioning]({{< relref "../enterprise/access-control/provisioning.md" >}})
+- [Access control provisioning]({{< relref "../enterprise/access-control/_index.md" >}})
diff --git a/docs/sources/administration/view-server/view-server-settings.md b/docs/sources/administration/view-server/view-server-settings.md
index dd9ea6a19d0..859202fd4c5 100644
--- a/docs/sources/administration/view-server/view-server-settings.md
+++ b/docs/sources/administration/view-server/view-server-settings.md
@@ -8,7 +8,7 @@ weight = 300
# View Grafana server settings
-> Refer to [Fine-grained access control]({{< relref "../../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how you can control access with fine-grained permissions.
+> Refer to [Role-based access control]({{< relref "../../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how you can control access with RBAC permissions.
If you are a Grafana server administrator, use the Settings tab to view the settings that are applied to your Grafana server via the [Configuration]({{< relref "../configuration.md#config-file-locations" >}}) file and any environmental variables.
diff --git a/docs/sources/administration/view-server/view-server-stats.md b/docs/sources/administration/view-server/view-server-stats.md
index bbd732eece2..e25542f2be0 100644
--- a/docs/sources/administration/view-server/view-server-stats.md
+++ b/docs/sources/administration/view-server/view-server-stats.md
@@ -7,7 +7,7 @@ weight = 400
# View Grafana server stats
-> Refer to [Fine-grained access control]({{< relref "../../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how you can control access with fine-grained permissions.
+> Refer to [Role-based access control]({{< relref "../../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how you can control access with RBAC permissions.
If you are a Grafana server admin, then you can view useful statistics about your Grafana server in the Stats & Licensing tab.
diff --git a/docs/sources/auth/ldap.md b/docs/sources/auth/ldap.md
index a289fc12038..5945a86dd96 100644
--- a/docs/sources/auth/ldap.md
+++ b/docs/sources/auth/ldap.md
@@ -13,7 +13,7 @@ group memberships and Grafana Organization user roles.
> [Enhanced LDAP authentication]({{< relref "../enterprise/enhanced_ldap.md" >}}) is available in [Grafana Cloud Advanced](https://grafana.com/docs/grafana-cloud/) and in [Grafana Enterprise]({{< relref "../enterprise" >}}).
-> Refer to [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how you can control access with fine-grained permissions.
+> Refer to [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how you can control access with role-based permissions.
## Supported LDAP Servers
diff --git a/docs/sources/enterprise/_index.md b/docs/sources/enterprise/_index.md
index 958578d0820..191b87bd80e 100644
--- a/docs/sources/enterprise/_index.md
+++ b/docs/sources/enterprise/_index.md
@@ -41,9 +41,9 @@ With Grafana Enterprise [enhanced LDAP]({{< relref "enhanced_ldap.md" >}}), you
## Enterprise features
-With Grafana Enterprise, you get access to new features, including:
+With Grafana Enterprise, you get access to the following features:
-- [Fine-grained access control]({{< relref "access-control/_index.md" >}}) to control access with fine-grained roles and permissions.
+- [Role-based access control]({{< relref "./access-control/_index.md" >}}) to control access with role-based permissions.
- [Data source permissions]({{< relref "datasource_permissions.md" >}}) to restrict query access to specific teams and users.
- [Data source query caching]({{< relref "query-caching.md" >}}) to temporarily store query results in Grafana to reduce data source load and rate limiting.
- [Reporting]({{< relref "reporting.md" >}}) to generate a PDF report from any dashboard and set up a schedule to have it emailed to whoever you choose.
diff --git a/docs/sources/enterprise/access-control/_index.md b/docs/sources/enterprise/access-control/_index.md
index a70c9aa3801..3cc2faa0db8 100644
--- a/docs/sources/enterprise/access-control/_index.md
+++ b/docs/sources/enterprise/access-control/_index.md
@@ -1,74 +1,13 @@
-+++
-title = "Fine-grained access control"
-description = "Grant, change, or revoke access to Grafana resources"
-keywords = ["grafana", "fine-grained-access-control", "roles", "permissions", "enterprise"]
-weight = 100
-+++
+---
+title: 'Grafana Role-based access control (RBAC)'
+menuTitle: 'Role-based access control (RBAC)'
+description: 'RBAC provides a standardized way of granting, changing, and revoking access when it comes to viewing and modifying Grafana resources, such as users and reports.'
+aliases: []
+weight: 120
+---
-# Fine-grained access control
+# Role-based access control (RBAC)
-> **Note:** Fine-grained access control is in beta, and you can expect changes in future releases.
+RBAC provides a standardized way of granting, changing, and revoking access when it comes to viewing and modifying Grafana resources, such as dashboards, reports, and administrative settings.
-Fine-grained access control provides a standardized way of granting, changing, and revoking access when it comes to viewing and modifying Grafana resources, such as users and reports.
-Fine-grained access control works alongside the current Grafana permissions, and it allows you granular control of users’ actions. For more information about Grafana permissions, refer to [About users and permissions]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md" >}}).
-
-To learn more about how fine-grained access control works, refer to [Roles]({{< relref "./roles.md" >}}) and [Permissions]({{< relref "./permissions.md" >}}).
-To use the fine-grained access control system, refer to [Fine-grained access control usage scenarios]({{< relref "./usage-scenarios.md" >}}).
-
-## Access management
-
-Fine-grained access control considers a) _who_ has an access (`identity`), and b) _what they can do_ and on which _Grafana resource_ (`role`).
-
-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.
-
-Refer to [Assign roles]({{< relref "./roles.md#assign-roles" >}}) to learn about grant or revoke access to your users.
-
-## Resources with fine-grained permissions
-
-Fine-grained access control is available for the following capabilities:
-
-- [Use Explore mode]({{< relref "../../explore/_index.md" >}})
-- [Manage users]({{< relref "../../administration/manage-users-and-permissions/manage-server-users/_index.md" >}})
-- [Manage LDAP authentication]({{< relref "../../auth/ldap/_index.md" >}})
-- [Manage data sources]({{< relref "../../datasources/_index.md" >}})
-- [Manage data source permissions]({{< relref "../datasource_permissions.md" >}})
-- [Manage a Grafana Enterprise license]({{< relref "../license/_index.md" >}})
-- [Provision Grafana]({{< relref "../../administration/provisioning/_index.md" >}})
-- [Manage reports]({{< relref "../reporting.md" >}})
-- [View server information]({{< relref "../../administration/view-server/_index.md" >}})
-- [Manage teams]({{< relref "../../administration/manage-users-and-permissions/manage-teams/_index.md" >}})
-- [Manage dashboards and folders]({{< relref "../../dashboards/_index.md" >}})
-- [Manage annotations]({{< relref "../../visualizations/annotations.md" >}})
-- [Alerting]({{< relref "../../alerting/unified-alerting/_index.md">}})
-
-To learn about specific endpoints where you can use fine-grained access control, refer to [Permissions]({{< relref "./permissions.md" >}}) and to the relevant [API]({{< relref "../../http_api/_index.md" >}}) documentation.
-
-## Enable fine-grained access control
-
-Fine-grained access control is available behind the `accesscontrol` feature toggle in Grafana Enterprise 8.0+.
-You can enable it either in a [config file]({{< relref "../../administration/configuration.md#config-file-locations" >}}) or by [configuring an environment variable]({{< relref "../../administration/configuration/#configure-with-environment-variables" >}}).
-
-### Enable in config file
-
-In your [config file]({{< relref "../../administration/configuration.md#config-file-locations" >}}), add `accesscontrol` as a [feature_toggle]({{< relref "../../administration/configuration.md#feature_toggle" >}}).
-
-```
-[feature_toggles]
-# enable features, separated by spaces
-enable = accesscontrol
-```
-
-### Enable with an environment variable
-
-You can use `GF_FEATURE_TOGGLES_ENABLE = accesscontrol` environment variable to override the config file configuration and enable fine-grained access control.
-
-Refer to [Configuring with environment variables]({{< relref "../../administration/configuration.md#/#override-configuration-with-environment-variables" >}}) for more information.
-
-### Verify if enabled
-
-You can verify if fine-grained access control is enabled or not by sending an HTTP request to the [Check endpoint]({{< relref "../../http_api/access_control.md#check-if-enabled" >}}).
-
-## Caveats
-
-If you have created a folder with unique identifier (uid) set to "general", you will not be able to manage its permissions with fine-grained access control.
-Any [folder permissions]({{< relref "../../administration/manage-users-and-permissions/manage-dashboard-permissions/_index.md" >}}) set for this folder will be disregarded when fine-grained access control is enabled.
+{{< section >}}
diff --git a/docs/sources/enterprise/access-control/about-rbac.md b/docs/sources/enterprise/access-control/about-rbac.md
new file mode 100644
index 00000000000..48ee5597bea
--- /dev/null
+++ b/docs/sources/enterprise/access-control/about-rbac.md
@@ -0,0 +1,99 @@
+---
+title: 'About RBAC in Grafana'
+menuTitle: 'About RBAC'
+description: 'Role-based access control (RBAC) provides a standardized way of granting, changing, and revoking access so that users can view and modify Grafana resources, such as users and reports.'
+aliases: [docs/grafana/latest/enterprise/access-control/, docs/grafana/latest/enterprise/access-control/roles/]
+weight: 10
+---
+
+# About RBAC
+
+Role-based access control (RBAC) provides a standardized way of granting, changing, and revoking access so that users can view and modify Grafana resources, such as users and reports.
+RBAC extends Grafana basic roles that are included in Grafana OSS, and enables you more granular control of users’ actions.
+
+> **Note:** RBAC is in beta, so you can expect changes in future releases.
+
+By using RBAC you can provide users with permissions that extend the permissions available with basic roles. For example, you can use RBAC to:
+
+- Modify existing basic roles: for example, enable an editor to create reports
+- Assign fixed roles to users and teams: for example, grant an engineering team the ability to create data sources
+- Create custom roles: for example, a role that allows users to create and edit dashboards, but not delete them
+
+Basic roles contain multiple fixed roles. Fixed roles in turn contain multiple permissions, each of which has an action and a scope. Here is an example of the hierarchy of Basic roles, fixed roles, permissions, actions, and scopes.
+
+- **Basic role:** `Viewer`
+ - **Fixed role:** `fixed:datasources:reader`
+ - **Permission:**
+ - **Action:** `datasources:read`
+ - **Scope:** `datasources:*`
+
+## Basic roles
+
+Basic roles are the standard roles that are available in Grafana OSS. If you have purchased a Grafana Enterprise license, you can still use basic roles.
+
+Grafana includes the following basic roles:
+
+- Grafana administrator
+- Organization administrator
+- Editor
+- Viewer
+
+Each basic role is comprised of a number of _fixed roles_ that control the permissions a basic role grants. For example, the viewer basic role contains the following fixed roles among others:
+
+- `fixed:datasources:id:reader`: Enables the viewer to see the ID of a data source.
+- `fixed:organization:reader`: Enables the viewer to see a list of organizations.
+- `fixed:annotations:reader`: Enables the viewer to see annotations that other users have added to a dashboard.
+- `fixed:annotations.dashboard:writer`: Enables the viewer to add annotations to a dashboard.
+
+You can use RBAC to modify the fixed roles associated with any basic role, to modify what viewers, editors, or admins can do. For more information about the fixed roles associated with each basic role, refer to [Basic role definitions]({{< relref "./rbac-fixed-basic-role-definitions#basic-role-assignments" >}}).
+
+> **Note:** You must assign each Grafana user a basic role.
+
+## Fixed roles
+
+Grafana Enterprise includes the ability for you to assign discrete fixed roles to users and teams. This gives you finer-grained control over user permissions than you would have with basic roles alone. These roles are called "fixed" because you cannot change or delete fixed roles. You can also create _custom_ roles of your own; see more information in the [custom roles section]({{< relref "#custom-roles" >}}) below.
+
+Assign fixed roles when the basic roles do not meet your permission requirements. For example, you might want a user with the basic viewer role to also edit dashboards. Or, you might want anyone with the editor role to also add and manage users. Fixed roles provide users more granular access to create, view, and update the following Grafana resources:
+
+- [Alerting]({{< relref "../../alerting/unified-alerting/_index.md">}})
+- [Annotations]({{< relref "../../dashboards/annotations.md" >}})
+- [API keys]({{< relref "../../administration/api-keys/_index.md" >}})
+- [Dashboards and folders]({{< relref "../../dashboards/_index.md" >}})
+- [Data sources]({{< relref "../../datasources/_index.md" >}})
+- [Explore]({{< relref "../../explore/_index.md" >}})
+- [Folders]({{< relref "../../dashboards/dashboard_folders.md" >}})
+- [LDAP]({{< relref "../../auth/ldap/_index.md" >}})
+- [Licenses]({{< relref "../license/_index.md" >}})
+- [Organizations]({{< relref "../../administration/manage-organizations/_index.md" >}})
+- [Provisioning]({{< relref "../../administration/provisioning/_index.md" >}})
+- [Reports]({{< relref "../reporting.md" >}})
+- [Roles]({{< relref "../../administration/manage-users-and-permissions/_index.md" >}})
+- [Settings]({{< relref "../settings-updates.md" >}})
+- [Service accounts]({{< relref "../../administration/service-accounts/_index.md" >}})
+- [Teams]({{< relref "../../administration/manage-users-and-permissions/manage-teams/_index.md" >}})
+- [Users]({{< relref "../../administration/manage-users-and-permissions/manage-server-users/_index.md" >}})
+
+To learn more about the permissions you can grant for each resource, refer to [RBAC role definitions]({{< relref "./rbac-fixed-basic-role-definitions.md" >}}).
+
+## Custom roles
+
+If you are a Grafana Enterprise customer, you can create custom roles to manage user permissions in a way that meets your security requirements.
+
+Custom roles contain unique combinations of permissions _actions_ and _scopes_. An action defines the action a use can perform on a Grafana resource. For example, the `teams.roles:list` action allows a user to see a list of roles associated with each team.
+
+A scope describes where an action can be performed. For example, the `teams:1` scope restricts the user's action to the team with ID `1`. When paired with the `teams.roles:list` action, this permission prohibits the user from viewing the roles for teams other than team `1`.
+
+Consider creating a custom role when fixed roles do not meet your permissions requirements.
+
+### Custom role creation
+
+You can use either of the following methods to create, assign, and manage custom roles:
+
+- Grafana provisioning: You can use a YAML file to configure roles. For more information about using provisioning to create custom roles, refer to [Manage RBAC roles]({{< relref "./manage-rbac-roles.md" >}}). For more information about using provisioning to assign RBAC roles to users or teams, refer to [Assign RBAC roles]({{< relref "./assign-rbac-roles.md" >}}).
+- RBAC API: As an alternative, you can use the Grafana HTTP API to create and manage roles. For more information about the HTTP API, refer to [RBAC API]({{< relref "../../http_api/access_control.md" >}}).
+
+## Limitation
+
+If you have created a folder with the name `General` or `general`, you cannot manage its permissions with RBAC.
+
+If you set [folder permissions]({{< relref "../../administration/manage-users-and-permissions/manage-dashboard-permissions/_index.md" >}}) for a folder named `General` or `general`, the system disregards the folder when RBAC is enabled.
diff --git a/docs/sources/enterprise/access-control/assign-rbac-roles.md b/docs/sources/enterprise/access-control/assign-rbac-roles.md
new file mode 100644
index 00000000000..d023a6eb7e9
--- /dev/null
+++ b/docs/sources/enterprise/access-control/assign-rbac-roles.md
@@ -0,0 +1,289 @@
+---
+title: 'Assign Grafana RBAC roles'
+menuTitle: 'Assign RBAC roles'
+description: 'Learn how to assign RBAC roles to users and teams in Grafana.'
+aliases:
+ [
+ docs/grafana/latest/enterprise/access-control/manage-role-assignments/manage-user-role-assignments/,
+ docs/grafana/latest/enterprise/access-control/manage-role-assignments/manage-built-in-role-assignments/,
+ ]
+weight: 40
+---
+
+# Assign RBAC roles
+
+In this topic you'll learn how to use the role picker, provisioning, and the HTTP API to assign fixed and custom roles to users and teams.
+
+## Assign fixed roles in the UI using the role picker
+
+This section describes how to:
+
+- Assign a fixed role to a user or team as an organization administrator.
+- Assign a fixed role to a user as a server administrator. This approach enables you to assign a fixed role to a user in multiple organizations, without needing to switch organizations.
+
+In both cases, the assignment applies only to the user or team within the affected organization, and no other organizations. For example, if you grant the user the **Data source editor** role in the **Main** organization, then the user can edit data sources in the **Main** organization, but not in other organizations.
+
+> **Note:** After you apply your changes, user and team permissions update immediately, and the UI reflects the new permissions the next time they reload their browser or visit another page.
+
+
+
+**Before you begin:**
+
+- [Plan your RBAC rollout strategy]({{< relref "./plan-rbac-rollout-strategy.md" >}}).
+- Identify the fixed roles that you want to assign to the user or team.
+
+ For more information about available fixed roles, refer to [RBAC role definitions]({{< relref "./rbac-fixed-basic-role-definitions.md" >}}).
+
+- Ensure that your own user account has the correct permissions:
+ - If you are assigning permissions to a user or team within an organization, you must have organization administrator or server administrator permissions.
+ - If you are assigning permissions to a user who belongs to multiple organizations, you must have server administrator permissions.
+ - Your Grafana user can also assign fixed role if it has either the `fixed:roles:writer` fixed role assigned to the same organization to which you are assigning RBAC to a user, or a custom role with `users.roles:add` and `users.roles:remove` permissions.
+ - Your own user account must have the roles you are granting. For example, if you would like to grant the `fixed:users:writer` role to a team, you must have that role yourself.
+
+
+
+**To assign a fixed role to a user or team:**
+
+1. Sign in to Grafana.
+2. Switch to the organization that contains the user or team.
+
+ For more information about switching organizations, refer to [Switch organizations](../../administration/manage-user-preferences/_index.md#switch-organizations).
+
+3. Hover your cursor over **Configuration** (the gear icon) in the left navigation menu, and click **Users** or **Teams**.
+4. In the **Role** column, select the fixed role that you want to assign to the user or team.
+5. Click **Update**.
+
+
+
+
+
+**To assign a fixed role as a server administrator:**
+
+1. Sign in to Grafana, hover your cursor over **Server Admin** (the shield icon) in the left navigation menu, and click **Users**.
+1. Click a user.
+1. In the **Organizations** section, select a role within an organization that you want to assign to the user.
+1. Click **Update**.
+
+
+
+## Assign fixed or custom roles to a team using provisioning
+
+Instead of using the Grafana role picker, you can use file-based provisioning to assign fixed roles to teams. If you have a large number of teams, provisioning can provide an easier approach to assigning and managing role assignments.
+
+
+
+**Before you begin:**
+
+- [Enable role provisioning]({{< relref "./enable-rbac-and-provisioning#enable-role-provisioning" >}})
+- Ensure that the team to which you are adding the fixed role exists. For more information about creating teams, refer to [Manage teams]({{< relref "../../administration/manage-users-and-permissions/manage-teams/_index.md">}})
+
+
+
+**To assign a fixed role to a team:**
+
+1. Open the YAML configuration file.
+
+1. Refer to the following table to add attributes and values.
+
+ | Attribute | Description |
+ | --------- | ------------------------------------------------------------------------------------------------------------------------------ |
+ | `name` | Enter the name of the fixed role. |
+ | `global` | Enter `true`. Because fixed roles are global, you must specify the global attribute. You cannot change fixed role definitions. |
+ | `teams` | Enter the team or teams to which you are adding the fixed role. |
+ | `orgId` | Because teams belong to organizations, you must add the `orgId` value. |
+
+1. Reload the provisioning configuration file.
+
+ For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}).
+
+The following example assigns the `users:writer` fixed role to the `user editors` and `user admins` teams:
+
+```yaml
+# config file version
+apiVersion: 1
+
+# Roles to insert/update in the database
+roles:
+ - name: fixed:users:writer
+ global: true
+ teams:
+ - name: 'user editors'
+ orgId: 1
+ - name: 'user admins'
+ orgId: 1
+```
+
+
+
+**To assign a custom role to a team:**
+
+1. Open the YAML configuration file.
+
+1. Refer to the following table to add attributes and values.
+
+ | Attribute | Description |
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+ | `name` | Enter the name of the custom role. |
+ | `version` | Enter the custom role version number. Assignments are updated if the version of the role is greater then or equal to the version number stored internally. If you are updating a role assignment, you are not required to increment the role version number. |
+ | `global` | Enter `true` or `false` |
+ | `permissions` | Enter the permissions `action` and `scope` values. For more information about permissions actions and scopes, refer to [LINK] |
+ | `teams` | Enter the team or teams to which you are adding the custom role. |
+ | `orgId` | Because teams belong to organizations, you must add the `orgId` value. |
+
+1. Reload the provisioning configuration file.
+
+ For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}).
+
+The following example assigns the `custom:users:writer` role to the `user editors` and `user admins` teams:
+
+```yaml
+# config file version
+apiVersion: 1
+
+# Roles to insert/update in the database
+roles:
+ - name: custom:users:writer
+ description: 'List/update other users in the organization'
+ version: 1
+ global: true
+ permissions:
+ - action: 'org.users:read'
+ scope: 'users:*'
+ - action: 'org.users:write'
+ scope: 'users:*'
+ teams:
+ - name: 'user editors'
+ orgId: 1
+ - name: 'user admins'
+ orgId: 1
+```
+
+> **Note:** If you want to remove a fixed role assignment from a team, remove it from the YAML file, save your changes, and reload the configuration file.
+
+## Assign a fixed or custom role to a basic role
+
+If you want to extend the permissions of a basic role, you can modify it by adding a fixed role or a basic role to it.
+
+You can also remove fixed or custom roles from basic roles. For example, you can remove the `fixed:users:writer` fixed role from the Administrator basic role if you would prefer that administrators not manage users. Learn more in the topic [remove a fixed role from a basic role]({{< relref "manage-rbac-roles.md#remove-a-fixed-role-from-a-basic-role" >}}).
+
+### Assign a fixed role to a basic role using provisioning
+
+If you want to extend the permissions of a basic role, and you identify a fixed role that meets your permission requirements, you can assign a fixed role to a basic role.
+
+
+
+**Before you begin:**
+
+- [Enable role provisioning]({{< relref "./enable-rbac-and-provisioning#enable-role-provisioning" >}})
+- Determine which fixed role you want to add to a basic role
+
+
+
+**To add a fixed role to a basic role:**
+
+1. Open the YAML configuration file and locate the `addDefaultAssignments` section.
+
+1. Refer to the following table to add attributes and values.
+
+ | Attribute | Description |
+ | ------------- | --------------------------------- |
+ | `builtInRole` | Enter the name of the basic role. |
+ | `fixedRole` | Enter the name of the fixed role. |
+
+1. Reload the provisioning configuration file.
+
+ For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}).
+
+The following example restores a default basic and fixed role assignment.
+
+```yaml
+# config file version
+apiVersion: 1
+
+# list of default basic role assignments that should be added back
+addDefaultAssignments:
+ - builtInRole: 'Admin'
+ fixedRole: 'fixed:reporting:admin:read'
+```
+
+### Assign a custom role to a basic role using provisioning
+
+If you want to extend the permissions of a basic role, and assigning fixed roles to the basic role does not meet your permission requirements, you can create a custom role and assign that role to a basic role.
+
+
+
+**Before you begin:**
+
+- [Enable role provisioning]({{< relref "./enable-rbac-and-provisioning#enable-role-provisioning" >}})
+- [Add a custom role]({{< relref "./manage-rbac-roles#create-custom-role" >}})
+
+
+
+**To assign a custom role to a basic role:**
+
+1. Open the YAML configuration file and locate the `builtInRoles` section.
+
+1. Refer to the following table to add attributes and values.
+
+ | Attribute | Description |
+ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+ | `name` | Enter the name of the custom role. |
+ | `version` | Enter the custom role version number. Assignments are updated if the version of the role is greater than or equal to the version number stored internally. If you are updating a role assignment, you are not required to increment the role version number. |
+ | `orgId` | If you do not enter an `orgId`, it inherits the `orgId` from `role`. For global roles the default `orgId` is used. `orgId` in the `role` and in the assignment must be the same for non-global roles. |
+ | `permissions` | Enter the permissions `action` and `scope` values. For more information about permissions actions and scopes, refer to [LINK] |
+ | `builtInRoles` | Enter the `name` of an organization role, for example `Viewer`, `Editor`, or `Admin`, or enter `Grafana Admin`. |
+
+1. Reload the provisioning configuration file.
+
+ For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}).
+
+The following example assigns the `users:editor` custom role to the basic editor and admin roles.
+
+```yaml
+# config file version
+apiVersion: 1
+
+# Roles to insert/update in the database
+roles:
+ - name: custom:users:editor
+ description: 'This role allows users to list/create/update other users in the organization'
+ version: 1
+ orgId: 1
+ permissions:
+ - action: 'users:read'
+ scope: 'users:*'
+ - action: 'users:write'
+ scope: 'users:*'
+ - action: 'users:create'
+ scope: 'users:*'
+ builtInRoles:
+ - name: 'Editor'
+ - name: 'Admin'
+```
+
+## Assign a custom role to a basic role using the HTTP API
+
+As an alternative to assigning roles using the role picker or provisioning, you can use the Grafana HTTP API to assign fixed and custom roles to users and teams. For more information about the HTTP API, refer to the [RBAC HTTP API documentation]({{< relref "../../http_api/access_control.md#create-a-basic-role-assignment" >}}).
+
+The following example shows you how to assign a custom role to a basic role using the HTTP API.
+
+**Example request**
+
+```
+curl --location --request POST '/api/access-control/builtin-roles' \
+--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+ "roleUid": "jZrmlLCkGksdka",
+ "builtinRole": "Viewer",
+ "global": true
+}'
+```
+
+**Example response**
+
+```
+{
+ "message": "Built-in role grant added"
+}
+```
diff --git a/docs/sources/enterprise/access-control/permissions.md b/docs/sources/enterprise/access-control/custom-role-actions-scopes.md
similarity index 95%
rename from docs/sources/enterprise/access-control/permissions.md
rename to docs/sources/enterprise/access-control/custom-role-actions-scopes.md
index 9f3bf2e009e..48cfc02c68b 100644
--- a/docs/sources/enterprise/access-control/permissions.md
+++ b/docs/sources/enterprise/access-control/custom-role-actions-scopes.md
@@ -1,157 +1,153 @@
-+++
-title = "Permissions"
-description = "Understand fine-grained access control permissions"
-keywords = ["grafana", "fine-grained access-control", "roles", "permissions", "enterprise"]
-weight = 110
-+++
+---
+title: 'Grafana RBAC permissions, actions, and scopes'
+menuTitle: 'RBAC permissions, actions, and scopes'
+description: 'Learn about Grafana RBAC permissions, actions, and scopes.'
+aliases: [docs/grafana/latest/enterprise/access-control/permissions/]
+weight: 80
+---
-# Permissions
+# RBAC permissions, actions, and scopes
-A permission is an action and a scope. When creating a fine-grained access control, consider what specific action a user should be allowed to perform, and on what resources (its scope).
+A permission is comprised of an action and a scope. When creating a custom role, consider the actions the user can perform and the resource(s) on which they can perform those actions.
-To grant permissions to a user, you create a built-in role assignment to map a role to a built-in role. A built-in role assignment _modifies_ to one of the existing built-in roles in Grafana (Viewer, Editor, Admin). For more information, refer to [Built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}).
+To learn more about the Grafana resources to which you can apply RBAC, refer to [Resources with RBAC permissions]({{< relref "./about-rbac.md#fixed-roles" >}}).
-To learn more about which permissions are used for which resources, refer to [Resources with fine-grained permissions]({{< relref "./_index.md#resources-with-fine-grained-permissions" >}}).
-
-action
-: The specific action on a resource defines what a user is allowed to perform if they have permission with the relevant action assigned to it.
-
-scope
-: The scope describes where an action can be performed, such as reading a specific user profile. In such case, a permission is associated with the scope `users:` to the relevant role.
+- **Action:** An action describes what tasks a user can perform on a resource.
+- **Scope:** A scope describes where an action can be performed, such as reading a specific user profile. In this example, a permission is associated with the scope `users:` to the relevant role.
## Action definitions
-The following list contains fine-grained access control actions.
+The following list contains role-based access control actions.
| Action | Applicable scope | Description |
| ------------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `roles:list` | `roles:*` | List available roles without permissions. |
-| `roles:read` | `roles:*`
`roles:uid:*` | Read a specific role with its permissions. |
-| `roles:write` | `permissions:delegate` | Create or update a custom role. |
-| `roles:delete` | `permissions:delegate` | Delete a custom role. |
-| `roles.builtin:list` | `roles:*` | List built-in role assignments. |
-| `roles.builtin:add` | `permissions:delegate` | Create a built-in role assignment. |
-| `roles.builtin:remove` | `permissions:delegate` | Delete a built-in role assignment. |
+| `alert.instances.external:read` | `datasources:*`
`datasources:uid:*` | Read alerts and silences in data sources that support alerting. |
+| `alert.instances.external:write` | `datasources:*`
`datasources:uid:*` | Manage alerts and silences in data sources that support alerting. |
+| `alert.instances:create` | n/a | Create silences in the current organization. |
+| `alert.instances:read` | n/a | Read alerts and silences in the current organization. |
+| `alert.instances:update` | n/a | Update and expire silences in the current organization. |
+| `alert.notifications.external:read` | `datasources:*`
`datasources:uid:*` | Read templates, contact points, notification policies, and mute timings in data sources that support alerting. |
+| `alert.notifications.external:write` | `datasources:*`
`datasources:uid:*` | Manage templates, contact points, notification policies, and mute timings in data sources that support alerting. |
+| `alert.notifications:create` | n/a | Create templates, contact points, notification policies, and mute timings in the current organization. |
+| `alert.notifications:delete` | n/a | Delete templates, contact points, notification policies, and mute timings in the current organization. |
+| `alert.notifications:read` | n/a | Read all templates, contact points, notification policies, and mute timings in the current organization. |
+| `alert.notifications:update` | n/a | Update templates, contact points, notification policies, and mute timings in the current organization. |
+| `alert.rules.external:read` | `datasources:*`
`datasources:uid:*` | Read alert rules in data sources that support alerting (Prometheus, Mimir, and Loki) |
+| `alert.rules.external:write` | `datasources:*`
`datasources:uid:*` | Create, update, and delete alert rules in data sources that support alerting (Mimir and Loki). |
+| `alert.rules:create` | `folders:*`
`folders:id:*` | Create Grafana alert rules in a folder. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
+| `alert.rules:delete` | `folders:*`
`folders:id:*` | Delete Grafana alert rules in a folder. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
+| `alert.rules:read` | `folders:*`
`folders:id:*` | Read Grafana alert rules in a folder. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
+| `alert.rules:update` | `folders:*`
`folders:id:*` | Update Grafana alert rules in a folder. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
+| `annotations.create` | `annotations:*`
`annotations:type:*` | Create annotations. |
+| `annotations.delete` | `annotations:*`
`annotations:type:*` | Delete annotations. |
+| `annotations.read` | `annotations:*`
`annotations:type:*` | Read annotations and annotation tags. |
+| `annotations.write` | `annotations:*`
`annotations:type:*` | Update annotations. |
+| `dashboards.permissions:read` | `dashboards:*`
`dashboards:id:*`
`folders:*`
`folders:id:*` | Read permissions for one or more dashboards. |
+| `dashboards.permissions:write` | `dashboards:*`
`dashboards:id:*`
`folders:*`
`folders:id:*` | Update permissions for one or more dashboards. |
+| `dashboards:create` | `folders:*`
`folders:id:*` | Create dashboards in one or more folders. |
+| `dashboards:delete` | `dashboards:*`
`dashboards:id:*`
`folders:*`
`folders:id:*` | Delete one or more dashboards. |
+| `dashboards:edit` | `dashboards:*`
`dashboards:id:*`
`folders:*`
`folders:id:*` | Edit one or more dashboards (only in ui). |
+| `dashboards:read` | `dashboards:*`
`dashboards:id:*`
`folders:*`
`folders:id:*` | Read one or more dashboards. |
+| `dashboards:write` | `dashboards:*`
`dashboards:id:*`
`folders:*`
`folders:id:*` | Update one or more dashboards. |
+| `datasources.id:read` | `datasources:*`
`datasources:name:*` | Read data source IDs. |
+| `datasources.permissions:read` | `datasources:*`
`datasources:id:*` | List data source permissions. |
+| `datasources.permissions:write` | `datasources:*`
`datasources:id:*` | Update data source permissions. |
+| `datasources:create` | n/a | Create data sources. |
+| `datasources:delete` | `datasources:id:*`
`datasources:uid:*`
`datasources:name:*` | Delete data sources. |
+| `datasources:explore` | n/a | Enable access to the **Explore** tab. |
+| `datasources:query` | n/a
`datasources:*`
`datasources:id:*` | Query data sources. |
+| `datasources:read` | n/a
`datasources:*`
`datasources:id:*`
`datasources:uid:*`
`datasources:name:*` | List data sources. |
+| `datasources:write` | `datasources:*`
`datasources:id:*` | Update data sources. |
+| `folders.permissions:write` | `folders:*`
`folders:id:*` | Update permissions for one or more folders. |
+| `folders:create` | n/a | Create folders. |
+| `folders:delete` | `folders:*`
`folders:id:*` | Delete one or more folders. |
+| `folders:read` | `folders:*`
`folders:id:*` | Read one or more folders. |
+| `folders:write` | `folders:*`
`folders:id:*` | Update one or more folders. |
+| `folers.permissions:read` | `folders:*`
`folders:id:*` | Read permissions for one or more folders. |
+| `ldap.config:reload` | n/a | Reload the LDAP configuration. |
+| `ldap.status:read` | n/a | Verify the availability of the LDAP server or servers. |
+| `ldap.user:read` | n/a | Read users via LDAP. |
+| `ldap.user:sync` | n/a | Sync users via LDAP. |
+| `licensing.reports:read` | n/a | Get custom permission reports. |
+| `licensing:delete` | n/a | Delete the license token. |
+| `licensing:read` | n/a | Read licensing information. |
+| `licensing:update` | n/a | Update the license token. |
+| `org.users.role:update` | `users:*`
`users:id:*` | Update the organization role (`Viewer`, `Editor`, or `Admin`) of an organization. |
+| `org.users:add` | `users:*` | Add a user to an organization. |
+| `org.users:read` | `users:*`
`users:id:*` | Get user profiles within an organization. |
+| `org.users:remove` | `users:*`
`users:id:*` | Remove a user from an organization. |
+| `org:create` | n/a | Create an organization. |
+| `orgs.preferences:read` | `orgs:*`
`orgs:id:*` | Read organization preferences. |
+| `orgs.preferences:write` | `orgs:*`
`orgs:id:*` | Update organization preferences. |
+| `orgs.quotas:read` | `orgs:*`
`orgs:id:*` | Read organization quotas. |
+| `orgs.quotas:write` | `orgs:*`
`orgs:id:*` | Update organization quotas. |
+| `orgs:delete` | `orgs:*`
`orgs:id:*` | Delete one or more organizations. |
+| `orgs:read` | `orgs:*`
`orgs:id:*` | Read one or more organizations. |
+| `orgs:write` | `orgs:*`
`orgs:id:*` | Update one or more organizations. |
+| `provisioning:reload` | `provisioners:*` | Reload provisioning files. To find the exact scope for specific provisioner, see [Scope definitions]({{< relref "#scope-definitions" >}}). |
| `reports.admin:create` | n/a | Create reports. |
| `reports.admin:write` | `reports:*`
`reports:id:*` | Update reports. |
+| `reports.settings:read` | n/a | Read report settings. |
+| `reports.settings:write` | n/a | Update report settings. |
| `reports:delete` | `reports:*`
`reports:id:*` | Delete reports. |
| `reports:read` | `reports:*` | List all available reports or get a specific report. |
| `reports:send` | `reports:*` | Send a report email. |
-| `reports.settings:write` | n/a | Update report settings. |
-| `reports.settings:read` | n/a | Read report settings. |
-| `provisioning:reload` | `provisioners:*` | Reload provisioning files. To find the exact scope for specific provisioner, see [Scope definitions]({{< relref "./permissions.md#scope-definitions" >}}). |
-| `teams.roles:list` | `teams:*` | List roles assigned directly to a team. |
+| `roles.builtin:add` | `permissions:delegate` | Create a built-in role assignment. |
+| `roles.builtin:list` | `roles:*` | List built-in role assignments. |
+| `roles.builtin:remove` | `permissions:delegate` | Delete a built-in role assignment. |
+| `roles:delete` | `permissions:delegate` | Delete a custom role. |
+| `roles:list` | `roles:*` | List available roles without permissions. |
+| `roles:read` | `roles:*`
`roles:uid:*` | Read a specific role with its permissions. |
+| `roles:write` | `permissions:delegate` | Create or update a custom role. |
+| `server.stats:read` | n/a | Read Grafana instance statistics. |
+| `settings:read` | `settings:*`
`settings:auth.saml:*`
`settings:auth.saml:enabled` (property level) | Read the [Grafana configuration settings]({{< relref "../../administration/configuration/_index.md" >}}) |
+| `settings:write` | `settings:*`
`settings:auth.saml:*`
`settings:auth.saml:enabled` (property level) | Update any Grafana configuration settings that can be [updated at runtime]({{< relref "../../enterprise/settings-updates/_index.md" >}}). |
+| `status:accesscontrol` | `services:accesscontrol` | Get access-control enabled status. |
+| `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. |
| `teams.roles:add` | `permissions:delegate` | Assign a role to a team. |
+| `teams.roles:list` | `teams:*` | List roles assigned directly to a team. |
| `teams.roles:remove` | `permissions:delegate` | Unassign a role from a team. |
-| `users:read` | `global.users:*` | Read or search user profiles. |
-| `users:write` | `global.users:*`
`global.users:id:*` | Update a user’s profile. |
-| `users.teams:read` | `global.users:*`
`global.users:id:*` | Read a user’s teams. |
+| `teams:create` | n/a | Create teams. |
+| `teams:delete` | `teams:*`
`teams:id:*` | Delete one or more 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. |
| `users.authtoken:list` | `global.users:*`
`global.users:id:*` | List authentication tokens that are assigned to a user. |
| `users.authtoken:update` | `global.users:*`
`global.users:id:*` | Update authentication tokens that are assigned to a user. |
| `users.password:update` | `global.users:*`
`global.users:id:*` | Update a user’s password. |
-| `users:delete` | `global.users:*`
`global.users:id:*` | Delete a user. |
-| `users:create` | n/a | Create a user. |
-| `users:enable` | `globa.users:*`
`global.users:id:*` | Enable a user. |
-| `users:disable` | `global.users:*`
`global.users:id:*` | Disable a user. |
+| `users.permissions:list` | `users:*` | List permissions of a user. |
| `users.permissions:update` | `global.users:*`
`global.users:id:*` | Update a user’s organization-level permissions. |
-| `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:list` | `users:*` | List roles assigned directly to a user. |
| `users.roles:remove` | `permissions:delegate` | Unassign a role from a user. |
-| `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. |
-| `org.users.role:update` | `users:*`
`users:id:*` | Update the organization role (`Viewer`, `Editor`, or `Admin`) of an organization. |
-| `orgs:read` | `orgs:*`
`orgs:id:*` | Read one or more organizations. |
-| `orgs:write` | `orgs:*`
`orgs:id:*` | Update one or more organizations. |
-| `org:create` | n/a | Create an organization. |
-| `orgs:delete` | `orgs:*`
`orgs:id:*` | Delete one or more organizations. |
-| `orgs.quotas:read` | `orgs:*`
`orgs:id:*` | Read organization quotas. |
-| `orgs.quotas:write` | `orgs:*`
`orgs:id:*` | Update organization quotas. |
-| `orgs.preferences:read` | `orgs:*`
`orgs:id:*` | Read organization preferences. |
-| `orgs.preferences:write` | `orgs:*`
`orgs:id:*` | Update organization preferences. |
-| `ldap.user:read` | n/a | Read users via LDAP. |
-| `ldap.user:sync` | n/a | Sync users via LDAP. |
-| `ldap.status:read` | n/a | Verify the availability of the LDAP server or servers. |
-| `ldap.config:reload` | n/a | Reload the LDAP configuration. |
-| `status:accesscontrol` | `services:accesscontrol` | Get access-control enabled status. |
-| `settings:read` | `settings:*`
`settings:auth.saml:*`
`settings:auth.saml:enabled` (property level) | Read the [Grafana configuration settings]({{< relref "../../administration/configuration/_index.md" >}}) |
-| `settings:write` | `settings:*`
`settings:auth.saml:*`
`settings:auth.saml:enabled` (property level) | Update any Grafana configuration settings that can be [updated at runtime]({{< relref "../../enterprise/settings-updates/_index.md" >}}). |
-| `server.stats:read` | n/a | Read Grafana instance statistics. |
-| `datasources:explore` | n/a | Enable access to the **Explore** tab. |
-| `datasources:read` | n/a
`datasources:*`
`datasources:id:*`
`datasources:uid:*`
`datasources:name:*` | List data sources. |
-| `datasources:query` | n/a
`datasources:*`
`datasources:id:*` | Query data sources. |
-| `datasources.id:read` | `datasources:*`
`datasources:name:*` | Read data source IDs. |
-| `datasources:create` | n/a | Create data sources. |
-| `datasources:write` | `datasources:*`
`datasources:id:*` | Update data sources. |
-| `datasources:delete` | `datasources:id:*`
`datasources:uid:*`
`datasources:name:*` | Delete data sources. |
-| `datasources.permissions:read` | `datasources:*`
`datasources:id:*` | List data source permissions. |
-| `datasources.permissions:write` | `datasources:*`
`datasources:id:*` | Update data source permissions. |
-| `licensing:read` | n/a | Read licensing information. |
-| `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. |
-| `dashboards:read` | `dashboards:*`
`dashboards:id:*`
`folders:*`
`folders:id:*` | Read one or more dashboards. |
-| `dashboards:create` | `folders:*`
`folders:id:*` | Create dashboards in one or more folders. |
-| `dashboards:write` | `dashboards:*`
`dashboards:id:*`
`folders:*`
`folders:id:*` | Update one or more dashboards. |
-| `dashboards:edit` | `dashboards:*`
`dashboards:id:*`
`folders:*`
`folders:id:*` | Edit one or more dashboards (only in ui). |
-| `dashboards:delete` | `dashboards:*`
`dashboards:id:*`
`folders:*`
`folders:id:*` | Delete one or more dashboards. |
-| `dashboards.permissions:read` | `dashboards:*`
`dashboards:id:*`
`folders:*`
`folders:id:*` | Read permissions for one or more dashboards. |
-| `dashboards.permissions:write` | `dashboards:*`
`dashboards:id:*`
`folders:*`
`folders:id:*` | Update permissions for one or more dashboards. |
-| `folders:read` | `folders:*`
`folders:id:*` | Read one or more folders. |
-| `folders:create` | n/a | Create folders. |
-| `folders:write` | `folders:*`
`folders:id:*` | Update one or more folders. |
-| `folders:delete` | `folders:*`
`folders:id:*` | Delete one or more folders. |
-| `folers.permissions:read` | `folders:*`
`folders:id:*` | Read permissions for one or more folders. |
-| `folders.permissions:write` | `folders:*`
`folders:id:*` | Update permissions for one or more folders. |
-| `annotations.read` | `annotations:*`
`annotations:type:*` | Read annotations and annotation tags. |
-| `annotations.create` | `annotations:*`
`annotations:type:*` | Create annotations. |
-| `annotations.write` | `annotations:*`
`annotations:type:*` | Update annotations. |
-| `annotations.delete` | `annotations:*`
`annotations:type:*` | Delete annotations. |
-| `alert.rules:read` | `folders:*`
`folders:id:*` | Read Grafana alert rules in a folder. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
-| `alert.rules:create` | `folders:*`
`folders:id:*` | Create Grafana alert rules in a folder. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
-| `alert.rules:update` | `folders:*`
`folders:id:*` | Update Grafana alert rules in a folder. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
-| `alert.rules:delete` | `folders:*`
`folders:id:*` | Delete Grafana alert rules in a folder. Combine this permission with `folders:read` in a scope that includes the folder and `datasources:query` in the scope of data sources the user can query. |
-| `alert.rules.external:read` | `datasources:*`
`datasources:uid:*` | Read alert rules in data sources that support alerting (Prometheus, Mimir, and Loki) |
-| `alert.rules.external:write` | `datasources:*`
`datasources:uid:*` | Create, update, and delete alert rules in data sources that support alerting (Mimir and Loki). |
-| `alert.instances:read` | n/a | Read alerts and silences in the current organization. |
-| `alert.instances:create` | n/a | Create silences in the current organization. |
-| `alert.instances:update` | n/a | Update and expire silences in the current organization. |
-| `alert.instances.external:read` | `datasources:*`
`datasources:uid:*` | Read alerts and silences in data sources that support alerting. |
-| `alert.instances.external:write` | `datasources:*`
`datasources:uid:*` | Manage alerts and silences in data sources that support alerting. |
-| `alert.notifications:create` | n/a | Create templates, contact points, notification policies, and mute timings in the current organization. |
-| `alert.notifications:read` | n/a | Read all templates, contact points, notification policies, and mute timings in the current organization. |
-| `alert.notifications:update` | n/a | Update templates, contact points, notification policies, and mute timings in the current organization. |
-| `alert.notifications:delete` | n/a | Delete templates, contact points, notification policies, and mute timings in the current organization. |
-| `alert.notifications.external:read` | `datasources:*`
`datasources:uid:*` | Read templates, contact points, notification policies, and mute timings in data sources that support alerting. |
-| `alert.notifications.external:write` | `datasources:*`
`datasources:uid:*` | Manage templates, contact points, notification policies, and mute timings in data sources that support alerting. |
+| `users.teams:read` | `global.users:*`
`global.users:id:*` | Read a user’s teams. |
+| `users:create` | n/a | Create a user. |
+| `users:delete` | `global.users:*`
`global.users:id:*` | Delete a user. |
+| `users:disable` | `global.users:*`
`global.users:id:*` | Disable a user. |
+| `users:enable` | `globa.users:*`
`global.users:id:*` | Enable a user. |
+| `users:logout` | `global.users:*`
`global.users:id:*` | Sign out a user. |
+| `users:read` | `global.users:*` | Read or search user profiles. |
+| `users:write` | `global.users:*`
`global.users:id:*` | Update a user’s profile. |
## Scope definitions
-The following list contains fine-grained access control scopes.
+The following list contains role-based access control scopes.
| Scopes | Descriptions |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `permissions:delegate` | The scope is only applicable for roles associated with the Access Control itself and indicates that you can delegate your permissions only, or a subset of it, by creating a new role or making an assignment. |
-| `roles:*`
`roles:uid:*` | Restrict an action to a set of roles. For example, `roles:*` matches any role and `roles:uid:randomuid` matches only the role whose UID is `randomuid`. |
-| `reports:*`
`reports:id:*` | Restrict an action to a set of reports. For example, `reports:*` matches any report and `reports:id:1` matches the report whose ID is `1`. |
-| `services:accesscontrol` | Restrict an action to target only the fine-grained access control service. You can use this in conjunction with the `status:accesscontrol` actions. |
-| `global.users:*`
`global.users:id:*` | Restrict an action to a set of global users. For example, `global.users:*` matches any user and `global.users:id:1` matches the user whose ID is `1`. |
-| `teams:*`
`teams:id:*` | Restrict an action to a set of teams from an organization. For example, `teams:*` matches any team and `teams:id:1` matches the team whose ID is `1`. |
-| `users:*`
`users:id:*` | Restrict an action to a set of users from an organization. For example, `users:*` matches any user and `users:id:1` matches the user whose ID is `1`. |
-| `orgs:*`
`orgs:id:*` | Restrict an action to a set of organizations. For example, `orgs:*` matches any organization and `orgs:id:1` matches the organization whose ID is `1`. |
-| `settings:*` | Restrict an action to a subset of settings. For example, `settings:*` matches all settings, `settings:auth.saml:*` matches all SAML settings, and `settings:auth.saml:enabled` matches the enable property on the SAML settings. |
-| `provisioners:*` | Restrict an action to a set of provisioners. For example, `provisioners:*` matches any provisioner, and `provisioners:accesscontrol` matches the fine-grained access control [provisioner]({{< relref "./provisioning.md" >}}). |
+| `annotations:*`
`annotations:type:*` | Restrict an action to a set of annotations. For example, `annotations:*` matches any annotation, `annotations:type:dashboard` matches annotations associated with dashboards and `annotations:type:organization` matches organization annotations. |
+| `dashboards:*`
`dashboards:id:*` | Restrict an action to a set of dashboards. For example, `dashboards:*` matches any dashboard, and `dashboards:id:1` matches the dashboard whose ID is `1`. |
| `datasources:*`
`datasources:id:*`
`datasources:uid:*`
`datasources:name:*` | Restrict an action to a set of data sources. For example, `datasources:*` matches any data source, and `datasources:name:postgres` matches the data source named `postgres`. |
| `folders:*`
`folders:id:*` | Restrict an action to a set of folders. For example, `folders:*` matches any folder, and `folders:id:1` matches the folder whose ID is `1`. |
-| `dashboards:*`
`dashboards:id:*` | Restrict an action to a set of dashboards. For example, `dashboards:*` matches any dashboard, and `dashboards:id:1` matches the dashboard whose ID is `1`. |
-| `annotations:*`
`annotations:type:*` | Restrict an action to a set of annotations. For example, `annotations:*` matches any annotation, `annotations:type:dashboard` matches annotations associated with dashboards and `annotations:type:organization` matches organization annotations. |
+| `global.users:*`
`global.users:id:*` | Restrict an action to a set of global users. For example, `global.users:*` matches any user and `global.users:id:1` matches the user whose ID is `1`. |
+| `orgs:*`
`orgs:id:*` | Restrict an action to a set of organizations. For example, `orgs:*` matches any organization and `orgs:id:1` matches the organization whose ID is `1`. |
+| `permissions:delegate` | The scope is only applicable for roles associated with the Access Control itself and indicates that you can delegate your permissions only, or a subset of it, by creating a new role or making an assignment. |
+| `provisioners:*` | Restrict an action to a set of provisioners. For example, `provisioners:*` matches any provisioner, and `provisioners:accesscontrol` matches the role-based access control [provisioner]({{< relref "./custom-role-actions-scopes" >}}). |
+| `reports:*`
`reports:id:*` | Restrict an action to a set of reports. For example, `reports:*` matches any report and `reports:id:1` matches the report whose ID is `1`. |
+| `roles:*`
`roles:uid:*` | Restrict an action to a set of roles. For example, `roles:*` matches any role and `roles:uid:randomuid` matches only the role whose UID is `randomuid`. |
+| `services:accesscontrol` | Restrict an action to target only the role-based access control service. You can use this in conjunction with the `status:accesscontrol` actions. |
+| `settings:*` | Restrict an action to a subset of settings. For example, `settings:*` matches all settings, `settings:auth.saml:*` matches all SAML settings, and `settings:auth.saml:enabled` matches the enable property on the SAML settings. |
+| `teams:*`
`teams:id:*` | Restrict an action to a set of teams from an organization. For example, `teams:*` matches any team and `teams:id:1` matches the team whose ID is `1`. |
+| `users:*`
`users:id:*` | Restrict an action to a set of users from an organization. For example, `users:*` matches any user and `users:id:1` matches the user whose ID is `1`. |
diff --git a/docs/sources/enterprise/access-control/enable-rbac-and-provisioning.md b/docs/sources/enterprise/access-control/enable-rbac-and-provisioning.md
new file mode 100644
index 00000000000..1cc8c79efbd
--- /dev/null
+++ b/docs/sources/enterprise/access-control/enable-rbac-and-provisioning.md
@@ -0,0 +1,92 @@
+---
+title: 'Enable RBAC and provisioning in Grafana'
+menuTitle: 'Enable RBAC and provisioning'
+description: 'Learn how to enable RBAC and provisioning in Grafana.'
+aliases: []
+weight: 30
+---
+
+# Enable RBAC and provisioning
+
+Before you assign RBAC roles to Grafana users and teams, you must enable it by:
+
+- Adding a feature toggle to the Grafana configuration file, or
+- Adding an environment variable to the Grafana configuration file
+
+If you use provisioning to assign and manage roles, in addition to enabling RBAC, you must enable provisioning.
+
+This topic includes instructions for both methods of enabling role-based access control, and steps for enabling provisioning.
+
+## Enable RBAC
+
+This section describes how to enable RBAC by setting a feature flag or adding an environment variable to the Grafana configuration file. You choose one method to enable RBAC. You are not required to use both methods to enable RBAC.
+
+> **Note:** The environment variable overrides access control settings in the configuration file, if any exist.
+
+
+
+**Before you begin:**
+
+- Ensure that you have administration privileges to the Grafana server.
+
+
+
+**To enable RBAC:**
+
+1. Open the Grafana configuration file.
+
+ For more information about the location of the Grafana configuration file, refer to [config file]({{< relref "../../administration/configuration.md#config-file-locations" >}}).
+
+1. To enable RBAC using the feature toggle:
+
+ a. Locate the `[feature toggles]` section in the configuration file.
+
+ b. Add the following feature toggle parameter:
+
+ ```
+ [feature_toggles]
+ # enable features, separated by spaces
+ enable = accesscontrol
+ ```
+
+1. To enable RBAC by setting an environment variable, add the following environment variable to the configuration file:
+
+ `GF_FEATURE_TOGGLES_ENABLE = accesscontrol`
+
+ For more information about using environment variables in Grafana, refer to [Configuring with environment variables]({{< relref "../../administration/configuration.md#configure-with-environment-variables" >}}).
+
+1. Save your changes and restart the Grafana server.
+
+1. To verify that RBAC is enabled, send an HTTP request to the check endpoint.
+
+ For more information about sending an HTTP request to the check endpoint, refer to [Check endpoint]({{< relref "../../http_api/access_control.md#check-if-enabled" >}}).
+
+## Enable role provisioning
+
+You can create, change or remove [Custom roles]({{< relref "./manage-rbac-roles.md#create-custom-roles-using-provisioning" >}}) and create or remove [basic role assignments]({{< relref "./assign-rbac-roles.md#assign-a-fixed-role-to-a-basic-role-using-provisioning" >}}), by adding one or more YAML configuration files in the `provisioning/access-control/` directory.
+
+If you choose to use provisioning to assign and manage role, you must first enable it.
+
+Grafana performs provisioning during startup. After you make a change to the configuration file, you can reload it during runtime. You do not need to restart the Grafana server for your changes to take effect.
+
+
+
+**Before you begin:**
+
+- Ensure that you have access to files on the server where Grafana is running.
+
+
+
+**To manage and assign RBAC roles using provisioning:**
+
+1. Sign in to the Grafana server.
+
+2. Locate the Grafana provisioning folder.
+
+3. Create a new YAML in the following folder: **provisioning/access-control**. For example, `provisioning/access-control/custom-roles.yml`
+
+4. Add RBAC provisioning details to the configuration file. See [manage RBAC roles]({{< relref "manage-rbac-roles.md" >}}) and [assign RBAC roles]({{< relref "assign-rbac-roles.md" >}}) for instructions, and see this [example role provisioning file]({{< relref "provisioning-roles-example.md" >}}) for a complete example of a provisioning file.
+
+5. Reload the provisioning configuration file.
+
+ For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}).
diff --git a/docs/sources/enterprise/access-control/manage-rbac-roles.md b/docs/sources/enterprise/access-control/manage-rbac-roles.md
new file mode 100644
index 00000000000..cbefc79171d
--- /dev/null
+++ b/docs/sources/enterprise/access-control/manage-rbac-roles.md
@@ -0,0 +1,365 @@
+---
+title: 'Manage RBAC roles'
+menuTitle: 'Manage RBAC roles'
+description: 'Learn how to view permissions associated with roles, create custom roles, and update and delete roles in Grafana.'
+aliases:
+ [
+ docs/grafana/latest/enterprise/access-control/manage-role-assignments/,
+ docs/grafana/latest/enterprise/access-control/provisioning/,
+ ]
+weight: 50
+---
+
+# Manage RBAC roles
+
+This section includes instructions for how to view permissions associated with roles, create custom roles, and update and delete roles.
+
+## View basic role assignments using the HTTP API
+
+You can use the [RBAC HTTP API]({{< relref "../../http_api/access_control.md#get-all-built-in-role-assignments" >}}) to see all available basic role assignments.
+The response contains a mapping between one of the organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin` to the custom or fixed roles.
+
+**Before you begin:**
+
+- [Enable role-based access control]({{< relref "./enable-rbac-and-provisioning#enable-rback" >}}).
+
+The following example includes the base64 username:password Basic Authorization. You cannot use authorization tokens in the request.
+
+**Example request**
+
+```
+curl --location --request GET '/api/access-control/builtin-roles' --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ='
+```
+
+**Example response**
+
+```
+{
+ "Admin": [
+ ...
+ {
+ "version": 2,
+ "uid": "qQui_LCMk",
+ "name": "fixed:users:org:writer",
+ "displayName": "Users Organization writer",
+ "description": "Within a single organization, add a user, invite a user, read information about a user and their role, remove a user from that organization, or change the role of a user.",
+ "global": true,
+ "updated": "2021-05-17T20:49:18+02:00",
+ "created": "2021-05-13T16:24:26+02:00"
+ },
+ {
+ "version": 1,
+ "uid": "Kz9m_YjGz",
+ "name": "fixed:reports:writer",
+ "displayName": "Report writer",
+ "description": "Create, read, update, or delete all reports and shared report settings.",
+ "global": true,
+ "updated": "2021-05-13T16:24:26+02:00",
+ "created": "2021-05-13T16:24:26+02:00"
+ }
+ ...
+ ],
+ "Grafana Admin": [
+ ...
+ {
+ "version": 2,
+ "uid": "qQui_LCMk",
+ "name": "fixed:users:writer",
+ "displayName": "User writer",
+ "description": "Read and update all attributes and settings for all users in Grafana: update user information, read user information, create or enable or disable a user, make a user a Grafana administrator, sign out a user, update a user’s authentication token, or update quotas for all users.",
+ "global": true,
+ "updated": "2021-05-17T20:49:18+02:00",
+ "created": "2021-05-13T16:24:26+02:00"
+ },
+ {
+ "version": 2,
+ "uid": "ajum_YjGk",
+ "name": "fixed:users:reader",
+ "displayName": "User reader",
+ "description": "Allows every read action for user organizations and in addition allows to administer user organizations.",
+ "global": true,
+ "updated": "2021-05-17T20:49:17+02:00",
+ "created": "2021-05-13T16:24:26+02:00"
+ },
+ ...
+ ]
+}
+```
+
+### List permissions associated with roles
+
+Use a `GET` command to see the actions and scopes associated with a role. For more information about seeing a list of permissions for each role, refer to [Get a role]({{< relref "../../http_api/access_control.md#get-a-role" >}}).
+
+**Example request**
+
+```
+curl --location --request GET '/api/access-control/roles/qQui_LCMk' --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ='
+```
+
+**Example response**
+
+```
+{
+ "version": 2,
+ "uid": "qQui_LCMk",
+ "name": "fixed:users:writer",
+ "displayName": "User writer",
+ "description": "Read and update all attributes and settings for all users in Grafana: update user information, read user information, create or enable or disable a user, make a user a Grafana administrator, sign out a user, update a user’s authentication token, or update quotas for all users.",
+ "global": true,
+ "permissions": [
+ {
+ "action": "org.users:add",
+ "scope": "users:*",
+ "updated": "2021-05-17T20:49:18+02:00",
+ "created": "2021-05-17T20:49:18+02:00"
+ },
+ {
+ "action": "org.users:read",
+ "scope": "users:*",
+ "updated": "2021-05-17T20:49:18+02:00",
+ "created": "2021-05-17T20:49:18+02:00"
+ },
+ {
+ "action": "org.users:remove",
+ "scope": "users:*",
+ "updated": "2021-05-17T20:49:18+02:00",
+ "created": "2021-05-17T20:49:18+02:00"
+ },
+ {
+ "action": "org.users.role:update",
+ "scope": "users:*",
+ "updated": "2021-05-17T20:49:18+02:00",
+ "created": "2021-05-17T20:49:18+02:00"
+ }
+ ],
+ "updated": "2021-05-17T20:49:18+02:00",
+ "created": "2021-05-13T16:24:26+02:00"
+}
+```
+
+Refer to the [RBAC HTTP API]({{< relref "../../http_api/access_control.md#get-a-role" >}}) for more details.
+
+## Create custom roles
+
+This section shows you how to create a custom RBAC role using Grafana provisioning and the HTTP API.
+
+Create a custom role when basic roles and fixed roles do not meet your permissions requirements.
+
+**Before you begin:**
+
+- [Plan your RBAC rollout strategy]({{< relref "./plan-rbac-rollout-strategy" >}}).
+- Determine which permissions you want to add to the custom role. To see a list of actions and scope, refer to [RBAC permissions actions and scopes]({{< relref "./custom-role-actions-scopes.md" >}}).
+- [Enable role provisioning]({{< relref "./enable-rbac-and-provisioning#enable-rbac" >}}).
+- Ensure that you have permissions to create a custom role.
+ - By default, the Grafana Admin role has permission to create custom roles.
+ - A Grafana Admin can delegate the custom role privilege to another user by creating a custom role with the relevant permissions and adding the `permissions:delegate` scope.
+
+### Create custom roles using provisioning
+
+File-based provisioning is one method you can use to create custom roles.
+
+1. Open the YAML configuration file and locate the `roles` section.
+
+1. Refer to the following table to add attributes and values.
+
+ | Attribute | Description |
+ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+ | `name` | A human-friendly identifier for the role that helps administrators understand the purpose of a role. `name` is required and cannot be longer than 190 characters. We recommend that you use ASCII characters. Role names must be unique within an organization. |
+ | `Role display name` | Human-friendly text that is displayed in the UI. Role display name cannot be longer than 190 ASCII-based characters. For fixed roles, the display name is shown as specified. If you do not set a display name the display name replaces a `:` (a colon) with ` ` (a space). |
+ | `Display name` | A human-friendly identifier that appears in the role picker UI. `Display name` helps the user to understand the purpose of the role. |
+ | `Group` | Organizes roles in the role picker. |
+ | `version` | A positive integer that defines the current version of the role. When you update a role, you can either omit the version field to increment the previous value by 1, or set a new version which must be larger than the previous version. |
+ | `permissions` | Provides users access to Grafana resources. For a list of permissions, refer to [RBAC permissions actions and scopes]({{< relref "./rbac-fixed-basic-role-definitions.md" >}}). If you do not know which permissions to assign, you can create and assign roles without any permissions as a placeholder. |
+ | `Role UID` | A unique identifier associated with the role. The UID enables you to change or delete the role. You can either generate a UID yourself, or let Grafana generate one for you. You cannot use the same UID within the same Grafana instance. |
+ | `orgId` | Identifies the organization to which the role belongs. If you do not specify `orgId`, the `orgId` is inherited from `role`. For global roles, the default `orgId` is used. `orgId` in the `role` and in the assignment must be the same for non-global roles. The [default org ID]({{< relref "../../administration/configuration#auto_assign_org_id" >}}) is used if you do not specify `orgId`. |
+ | `global` | Global roles are not associated with any specific organization, which means that you can reuse them across all organizations. This setting overrides `orgId`. |
+ | `hidden` | Hidden roles do not appear in the role picker. |
+
+1. Reload the provisioning configuration file.
+
+ For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}).
+
+The following example creates a local role:
+
+```yaml
+# config file version
+apiVersion: 1
+
+# Roles to insert into the database, or roles to update in the database
+roles:
+ - name: custom:users:editor
+ description: 'This role allows users to list, create, or update other users within the organization.'
+ version: 1
+ orgId: 1
+ permissions:
+ - action: 'users:read'
+ scope: 'users:*'
+ - action: 'users:write'
+ scope: 'users:*'
+ - action: 'users:create'
+ scope: 'users:*'
+```
+
+The following example creates a hidden global role. The `global:true` option creates a global role, and the `hidden:true` option hides the role from the role picker.
+
+```yaml
+# config file version
+apiVersion: 1
+
+# Roles to insert into the database, or roles to update in the database
+roles:
+ - name: custom:users:editor
+ description: 'This role allows users to list, create, or update other users within the organization.'
+ version: 1
+ global: true
+ hidden: true
+ permissions:
+ - action: 'users:read'
+ scope: 'users:*'
+ - action: 'users:write'
+ scope: 'users:*'
+ - action: 'users:create'
+ scope: 'users:*'
+```
+
+### Create custom roles using the HTTP API
+
+The following examples show you how to create a custom role using the Grafana HTTP API. For more information about the HTTP API, refer to [Create a new custom role]({{< relref "../../http_api/access_control.md#create-a-new-custom-role" >}}).
+
+> **Note:** You cannot create a custom role with permissions that you do not have. For example, if you only have `users:create` permissions, then you cannot create a role that includes other permissions.
+
+The following example creates a `custom:users:admin` role and assigns the `users:create` action to it.
+
+**Example request**
+
+```
+curl --location --request POST '/api/access-control/roles/' \
+--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+ "version": 1,
+ "uid": "jZrmlLCkGksdka",
+ "name": "custom:users:admin",
+ "displayName": "custom users admin",
+ "description": "My custom role which gives users permissions to create users",
+ "global": true,
+ "permissions": [
+ {
+ "action": "users:create"
+ }
+ ]
+}'
+```
+
+
+
+**Example response**
+
+```
+{
+ "version": 1,
+ "uid": "jZrmlLCkGksdka",
+ "name": "custom:users:admin",
+ "displayName": "custom users admin",
+ "description": "My custom role which gives users permissions to create users",
+ "global": true,
+ "permissions": [
+ {
+ "action": "users:create"
+ "updated": "2021-05-17T22:07:31.569936+02:00",
+ "created": "2021-05-17T22:07:31.569935+02:00"
+ }
+ ],
+ "updated": "2021-05-17T22:07:31.564403+02:00",
+ "created": "2021-05-17T22:07:31.564403+02:00"
+}
+```
+
+Refer to the [RBAC HTTP API]({{< relref "../../http_api/access_control.md#create-a-new-custom-role" >}}) for more details.
+
+## Remove a fixed role from a basic role
+
+If the basic role definitions that are available by default do not meet your requirements, you can change them by removing fixed role permissions from basic roles.
+
+
+
+**Before you begin:**
+
+- Determine the fixed roles you want to remove from a basic role. For more information about the fixed roles associated with basic roles, refer to [RBAC role definitions]({{< relref "./rbac-fixed-basic-role-definitions#basic-role-assignments" >}}).
+
+
+
+**To remove a fixed role from a basic role:**
+
+1. Open the YAML configuration file and locate the `removeDefaultAssignments` section.
+
+1. Refer to the following table to add attributes and values.
+
+ | Attribute | Description |
+ | ------------- | --------------------------------- |
+ | `builtInRole` | Enter the name of the basic role. |
+ | `fixedRole` | Enter the name of the fixed role. |
+
+1. Reload the provisioning configuration file.
+
+ For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}).
+
+The following example removes the `fixed:permissions:admin` from the `Grafana Admin` basic role.
+
+```yaml
+# config file version
+apiVersion: 1
+
+# list of default basic role assignments that should be removed
+removeDefaultAssignments:
+ - builtInRole: 'Grafana Admin'
+ fixedRole: 'fixed:permissions:admin'
+```
+
+You can also remove fixed roles from basic roles using the API. Refer to the [RBAC HTTP API]({{< relref "../../http_api/access_control.md#remove-a-built-in-role-assignment" >}}) for more details.
+
+## Delete a custom role using Grafana provisioning
+
+Delete a custom role when you no longer need it. When you delete a custom role, the custom role is removed from users and teams to which it is assigned.
+
+> **Note:** If you use the same configuration file to both add and remove roles, the system deletes roles identified in the `deleteRoles` section before it adds roles identified in the `roles` section.
+
+
+
+**Before you begin:**
+
+- Identify the role or roles that you want to delete.
+- Ensure that you have access to the YAML configuration file.
+
+
+
+**To delete a custom role:**
+
+1. Open the YAML configuration file and locate the `deleteRoles` section.
+
+1. Refer to the following table to add attributes and values.
+
+ | Attribute | Description |
+ | --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+ | `name` | The name of the custom role you want to delete. You can add a `uid` instead of a role name. The role `name` or the `uid` are required. |
+ | `orgId` | Identifies the organization to which the role belongs. |
+ | `force` | Sets the force parameter. |
+
+1. Reload the provisioning configuration file.
+
+ For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}).
+
+The following example deletes a custom role:
+
+```yaml
+# config file version
+apiVersion: 1
+
+# list of roles that should be deleted
+deleteRoles:
+ - name: custom:reports:editor
+ orgId: 1
+ force: true
+```
+
+You can also delete a custom role using the API. Refer to the [RBAC HTTP API]({{< relref "../../http_api/access_control.md#delete-a-custom-role" >}}) for more details.
diff --git a/docs/sources/enterprise/access-control/manage-role-assignments/_index.md b/docs/sources/enterprise/access-control/manage-role-assignments/_index.md
deleted file mode 100644
index d8d6b61c7cc..00000000000
--- a/docs/sources/enterprise/access-control/manage-role-assignments/_index.md
+++ /dev/null
@@ -1,16 +0,0 @@
-+++
-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 and teams, or to [Organization roles]({{< relref "../../../administration/manage-users-and-permissions/about-users-and-permissions.md#organization-users-and-permissions" >}}) and the [Grafana Server Admin]({{< relref "../../../administration/manage-users-and-permissions/about-users-and-permissions.md#grafana-server-administrators" >}}) role.
-
-The following pages provide more information on how to manage role assignments:
-
-- [Manage user role assignments]({{< relref "manage-user-role-assignments.md" >}}).
-- [Manage team role assignments]({{< relref "manage-team-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
deleted file mode 100644
index 2cf6c56b413..00000000000
--- a/docs/sources/enterprise/access-control/manage-role-assignments/manage-built-in-role-assignments.md
+++ /dev/null
@@ -1,20 +0,0 @@
-+++
-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 "../../../administration/manage-users-and-permissions/about-users-and-permissions.md#organization-users-and-permissions" >}}) or to the [Grafana Server Admin]({{< relref "../../../administration/manage-users-and-permissions/about-users-and-permissions.md#grafana-server-administrators" >}}) 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-team-role-assignments.md b/docs/sources/enterprise/access-control/manage-role-assignments/manage-team-role-assignments.md
deleted file mode 100644
index 57808939368..00000000000
--- a/docs/sources/enterprise/access-control/manage-role-assignments/manage-team-role-assignments.md
+++ /dev/null
@@ -1,38 +0,0 @@
-+++
-title = "Manage team role assignments"
-description = "Manage team role assignments"
-keywords = ["grafana", "fine-grained-access-control", "roles", "permissions", "fine-grained-access-control-usage", "enterprise"]
-weight = 200
-+++
-
-# Manage team role assignments
-
-There are two ways to assign roles directly to teams: in the UI using the role picker, and using the API.
-
-## Manage teams' roles within a specific Organization using the role picker
-
-In order to assign roles to a team within a specific Organization using the role picker, you must have an account with one of the following:
-
-- The Admin built-in role.
-- The Server Admin role.
-- The fixed role `fixed:roles:writer`, [assigned for the given Organization]({{< relref "../roles/#scope-of-assignments" >}}).
-- A custom role with `teams.roles:add` and `teams.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 Teams page by hovering over **Configuration** (the gear icon) in the left navigation menu and selecting **Teams**.
-1. Click on the **Roles** column in the row for the team whose roles you would like to edit.
-1. Deselect one or more selected roles that you would like to remove from that team.
-1. Select one or more roles that you would like to assign to that team.
-1. Click the **Update** button to apply the selected roles to that team.
-
-
-
-
-The team's permissions will update immediately, and the UI will reflect its new permissions.
-
-## Manage teams' roles via API
-
-To manage team role assignments via API, refer to the [fine-grained access control HTTP API docs]({{< relref "../../../http_api/access_control.md#create-and-remove-team-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
deleted file mode 100644
index 70c1193a97b..00000000000
--- a/docs/sources/enterprise/access-control/manage-role-assignments/manage-user-role-assignments.md
+++ /dev/null
@@ -1,64 +0,0 @@
-+++
-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:roles: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 **Update** button to apply the selected roles to that user.
-
-
-
-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.
-
-
-
-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/plan-rbac-rollout-strategy.md b/docs/sources/enterprise/access-control/plan-rbac-rollout-strategy.md
new file mode 100644
index 00000000000..f721d837334
--- /dev/null
+++ b/docs/sources/enterprise/access-control/plan-rbac-rollout-strategy.md
@@ -0,0 +1,175 @@
+---
+title: 'Plan your Grafana RBAC rollout strategy'
+menuTitle: 'Plan your RBAC rollout strategy'
+description: 'Plan your RBAC rollout strategy before you begin assigning roles to users and teams.'
+aliases: [docs/grafana/latest/enterprise/access-control/usage-scenarios/]
+weight: 20
+---
+
+# Plan your RBAC rollout strategy
+
+An RBAC rollout strategy helps you determine _how_ you want to implement RBAC prior to assigning RBAC roles to users and teams.
+
+Your rollout strategy should help you answer the following questions:
+
+- Should I assign basic roles to users, or should I assign fixed roles or custom roles to users?
+- When should I create custom roles?
+- To which entities should I apply fixed and custom roles? Should I apply them to users, teams, or to basic roles?
+- How do I roll out permissions in a way that makes them easy to manage?
+- Which approach should I use when assigning roles? Should I use the Grafana UI, provisioning, or the API?
+
+## Review basic role and fixed role definitions
+
+As a first step in determining your permissions rollout strategy, we recommend that you become familiar with basic role and fixed role definitions. In addition to assigning fixed roles to any user and team, you can also assign fixed roles to basic roles, which changes what a Viewer, Editor, or Admin can do. This flexibility means that there are many combinations of role assignments for you to consider. If you have a large number of Grafana users and teams, we recommend that you make a list of which fixed roles you might want to use.
+
+To learn more about basic roles and fixed roles, refer to the following documentation:
+
+- [Basic role definitions]({{< relref "./rbac-fixed-basic-role-definitions#basic-role-assignments" >}})
+- [Fixed role definitions]({{< relref "./rbac-fixed-basic-role-definitions#fixed-role-definitions" >}})
+
+## User and team considerations
+
+RBAC is a flexible and powerful feature with many possible permissions assignment combinations available. Consider the follow guidelines when assigning permissions to users and teams.
+
+- **Assign roles to users** when you have a one-off scenario where a small number of users require access to a resource or when you want to assign temporary access. If you have a large number of users, this approach can be difficult to manage as you scale your use of Grafana. For example, a member of your IT department might need the `fixed:licensing:reader` and `fixed:licensing:writer` roles so that they can manage your Grafana Enterprise license.
+
+- **Assign roles to teams** when you have a subset of users that align to your organizational structure, and you want all members of the team to have the same level of access. For example, all members of a particular engineering team might need the `fixed:reports:reader` and `fixed:reports:writer` roles to be able to manage reports.
+
+ When you assign additional users to a team, the system automatically assigns permissions to those users.
+
+### Authentication provider considerations
+
+You can take advantage of your current authentication provider to manage user and team permissions in Grafana. When you map users and teams to SAML and LDAP groups, you can synchronize those assignments with Grafana.
+
+For example:
+
+1. Map SAML, LDAP, or Oauth roles to Grafana basic roles (viewer, editor, or admin).
+2. Use the Grafana Enterprise team sync feature to synchronize teams from your SAML, LDAP, or Oauth provider to Grafana.
+
+ - If a team does not exist in Grafana, team sync creates it.
+ - If a team exists in Grafana, team sync updates its membership.
+
+ For more information about team sync, refer to [Team sync]({{< relref "../team-sync.md" >}}).
+
+3. Within Grafana, assign RBAC permissions to roles and teams.
+
+## When to modify basic roles or create custom roles
+
+Consider the following guidelines when you determine if you should modify basic roles or create custom roles.
+
+- **Modify basic roles** when Grafana's definitions of what viewers, editors, and admins can do does not match your definition of these roles. You can add or remove fixed roles from any basic role.
+
+ > **Note:** Changes that you make to basic roles impact the role definition for all [organizations]({{< relref "../../administration/manage-organizations/_index.md" >}}) in the Grafana instance. For example, when you assign the `fixed:users:writer` role to the viewer basic role, all viewers in any org in the Grafana instance can create users within that org.
+
+- **Create custom roles** when fixed role definitions don't meet you permissions requirements. For example, the `fixed:dashboards:writer` role allows users to delete dashboards. If you want some users or teams to be able to create and update but not delete dashboards, you can create a custom role with a name like `custom:dashboards:creator` that lacks the `dashboards:delete` permission.
+
+## How to assign RBAC roles
+
+Use any of the following methods to assign RBAC roles to users and teams.
+
+- **Grafana UI:** Use the Grafana UI when you want to assign a limited number of RBAC roles to users and teams. The UI contains a role picker that you can use to select roles.
+- **Grafana HTTP API:** Use the Grafana HTTP API if you would like to automate role assignment.
+- **Terraform:** Use Terraform to assign and manage user and team role assignments if you use Terraform for provisioning.
+- **Grafana provisioning:** Grafana provisioning provides a robust approach to assigning, removing, and deleting roles. Within a single YAML file you can include multiple role assignment and removal entries.
+
+## Permissions scenarios
+
+We've compiled the following permissions rollout scenarios based on current Grafana implementations.
+
+> **Note:** If you have a use case that you'd like to share, feel free to contribute to this docs page. We'd love to hear from you!
+
+### Provide internal viewer employees with the ability to use Explore, but prevent external viewer contractors from using Explore
+
+1. In Grafana, create a team with the name `Internal employees`.
+1. Assign the `fixed:datasources:querier` role to the `Internal employees` team.
+1. Add internal employees to the `Internal employees` team, or map them from a SAML, LDAP, or Oauth team using [Team Sync]({{< relref "../team-sync.md" >}}).
+1. Assign the viewer role to both internal employees and contractors.
+
+### Limit viewer, editor, or admin permissions
+
+1. Review the list of fixed roles associated with the basic role.
+1. [Remove the fixed roles from the basic role]({{< relref "manage-rbac-roles.md#remove-a-fixed-role-from-a-basic-role" >}}).
+
+### Allow only members of one team to manage Alerts
+
+1. Remove all fixed roles starting with `fixed:alerts` from the Viewer, Editor, and Admin basic roles.
+2. Create an `Alert Managers` team, and assign that team all applicable Alerting fixed roles.
+3. Add users to the `Alert Managers` team.
+
+### Provide dashboards to users in two or more geographies
+
+1. Create a folder for each geography, for example, create a `US` folder and an `EU` folder.
+1. Add dashboards to each folder.
+1. Use folder permissions to add US-based users as Editors to the `US` folder and assign EU-based users as Editors to the `EU` folder.
+
+### Create a custom role to access alerts in a specific folder
+
+To see an alert rule in Grafana, the user must have read access to the folder that stores the alert rule, permission to read alerts in the folder, and permission to query all data sources that the rule uses.
+
+The API command in this example is based on the following:
+
+- A `Test-Folder` with ID `92`
+- Two data sources: `DS1` with UID `_oAfGYUnk`, and `DS2` with UID `YYcBGYUnk`
+- An alert rule that is stored in `Test-Folder` and queries the two data sources.
+
+The following request creates a custom role that includes permissions to access the alert rule:
+
+```
+curl --location --request POST '/api/access-control/roles/' \
+--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+ "version": 1,
+ "name": "custom:alerts.reader.in.folder.123",
+ "displayName": "Read-only access to alerts in folder Test-Folder",
+ "description": "Let user query DS1 and DS2, and read alerts in folder Test-Folders",
+ "group":"Custom",
+ "global": true,
+ "permissions": [
+ {
+ "action": "folders:read",
+ "scope": "folders:id:92"
+ },
+ {
+ "action": "alert.rules:read",
+ "scope": "folders:id:92"
+ },
+ {
+ "action": "datasources:query",
+ "scope": "datasources:uid:_oAfGYUnk"
+ },
+ {
+ "action": "datasources:query",
+ "scope": "datasources:uid:YYcBGYUnk"
+ }
+ ]
+}'
+```
+
+### Enable an editor to create custom roles
+
+By default, the Grafana Server Admin is the only user who can create and manage custom roles. If you want your users to do the same, you have two options:
+
+1. Create a basic role assignment and map `fixed:permissions:admin:edit` and `fixed:permissions:admin:read` fixed roles to the `Editor` basic role.
+1. [Create a custom role]({{< ref "./manage-rbac-roles#create-custom-roles" >}}) with `roles.builtin:add` and `roles:write` permissions, then create a basic role assignment for `Editor` organization role.
+
+ > **Note:** any user or service account with the ability to modify roles can only create, update or delete roles with permissions they themselves have been granted. For example, a user with the `Editor` role would be able to create and manage roles only with the permissions they have, or with a subset of them.
+
+### Enable viewers to create reports
+
+This section describes two ways that you can enable viewers to create reports.
+
+- Assign the `fixed:reporting:admin:edit` role to the `Viewer` basic role. For more information about assigning a fixed role to a basic role, refer to [Assign a fixed role to a basic role using provisioning]({{< relref "./assign-rbac-roles#assign-a-fixed-role-to-a-basic-role-using-provisioning" >}}).
+
+ > **Note:** The `fixed:reporting:admin:edit` role assigns more permissions than just creating reports. For more information about fixed role permission assignments, refer to [Fixed role definitions]({{< relref "./rbac-fixed-basic-role-definitions#fixed-role-definitions" >}}).
+
+- [Create a custom role]({{< ref "./manage-rbac-roles#create-custom-roles" >}}) that includes the `reports.admin:write` permission, and add the custom role to the `Viewer` basic role.
+ - For more information about assigning a custom role to a basic role, refer to [Assign a custom role to a basic role using provisioning]({{< relref "./assign-rbac-roles#assign-a-custom-role-to-a-basic-role-using-provisioning" >}}) or [Assign a custom role to a basic role using the HTTP API]({{< relref "./assign-rbac-roles#assign-a-custom-role-to-a-basic-role-using-the-http-api" >}}).
+
+### Prevent a Grafana Admin from creating and inviting users
+
+This topic describes how to remove the `users:create` permissions from the Grafana Admin role, which prevents the Grafana Admin from creating users and inviting them to join an organization.
+
+1. [View basic role assignments]({{< relref "./rbac-fixed-basic-role-definitions#basic-role-assignments" >}}) to determine which basic role assignments are available.
+1. To determine which role provides `users:create` permission, refer to [Fixed role definitions]({{< relref "./rbac-fixed-basic-role-definitions#fixed-role-definitions" >}}).
+1. Use the [Role-based access control HTTP API]({{< relref "../../http_api/access_control.md" >}}) or Grafana provisioning to [Remove a fixed role from a basic role]({{< relref "./manage-rbac-roles#remove-a-fixed-role-from-a-basic-role" >}}).
diff --git a/docs/sources/enterprise/access-control/provisioning-roles-example.md b/docs/sources/enterprise/access-control/provisioning-roles-example.md
new file mode 100644
index 00000000000..0b9e24cb03f
--- /dev/null
+++ b/docs/sources/enterprise/access-control/provisioning-roles-example.md
@@ -0,0 +1,104 @@
+---
+title: 'Example role configuration file using Grafana provisioning'
+menuTitle: 'Provisioning roles example'
+description: 'View an example YAML provisioning file that configures Grafana role assignments.'
+aliases: []
+weight: 60
+---
+
+# Example role configuration file using Grafana provisioning
+
+The following example shows a complete YAML configuration file that:
+
+- Removes a default role assignment
+- Adds a default role assignment
+- Deletes custom roles
+- Adds custom roles to basic roles
+- Adds a custom role to a fixed role
+
+## Example
+
+```yaml
+# config file version
+apiVersion: 1
+
+# list of default basic role assignments that should be removed
+removeDefaultAssignments:
+ # , must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
+ - builtInRole: 'Grafana Admin'
+ # , must be one of the existing fixed roles
+ fixedRole: 'fixed:permissions:admin'
+
+# list of default basic role assignments that should be added back
+addDefaultAssignments:
+ # , must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
+ - builtInRole: 'Admin'
+ # , must be one of the existing fixed roles
+ fixedRole: 'fixed:reporting:admin:read'
+
+# list of roles that should be deleted
+deleteRoles:
+ # name of the role you want to create. Required if no uid is set
+ - name: 'custom:reports:editor'
+ # uid of the role. Required if no name
+ uid: 'customreportseditor1'
+ # org id. will default to Grafana's default if not specified
+ orgId: 1
+ # force deletion revoking all grants of the role
+ force: true
+ - name: 'custom:global:reports:reader'
+ uid: 'customglobalreportsreader1'
+ # overwrite org id and removes a global role
+ global: true
+ force: true
+
+# list of roles to insert/update depending on what is available in the database
+roles:
+ # name of the role you want to create. Required
+ - name: 'custom:users:editor'
+ # uid of the role. Has to be unique for all orgs.
+ uid: customuserseditor1
+ # description of the role, informative purpose only.
+ description: 'Role for our custom user editors'
+ # version of the role, Grafana will update the role when increased
+ version: 2
+ # org id. will default to Grafana's default if not specified
+ orgId: 1
+ # list of the permissions granted by this role
+ permissions:
+ # action allowed
+ - action: 'users:read'
+ # scope it applies to
+ scope: 'users:*'
+ - action: 'users:write'
+ scope: 'users:*'
+ - action: 'users:create'
+ scope: 'users:*'
+ # list of basic roles the role should be assigned to
+ builtInRoles:
+ # name of the basic role you want to assign the role to
+ - name: 'Editor'
+ # org id. will default to the role org id
+ orgId: 1
+ - name: 'custom:global:users:reader'
+ uid: 'customglobalusersreader1'
+ description: 'Global Role for custom user readers'
+ version: 1
+ # overwrite org id and creates a global role
+ global: true
+ permissions:
+ - action: 'users:read'
+ scope: 'users:*'
+ builtInRoles:
+ - name: 'Viewer'
+ orgId: 1
+ - name: 'Editor'
+ # overwrite org id and assign role globally
+ global: true
+ - name: fixed:users:writer
+ global: true
+ # list of teams the role should be assigned to
+ teams:
+ - name: 'user editors'
+ orgId: 1
+```
diff --git a/docs/sources/enterprise/access-control/provisioning.md b/docs/sources/enterprise/access-control/provisioning.md
deleted file mode 100644
index 8280b0828d1..00000000000
--- a/docs/sources/enterprise/access-control/provisioning.md
+++ /dev/null
@@ -1,338 +0,0 @@
-+++
-title = "Provisioning roles and assignments"
-description = "Understand how to provision roles and assignments in fine-grained access control"
-keywords = ["grafana", "fine-grained-access-control", "roles", "provisioning", "assignments", "permissions", "enterprise"]
-weight = 120
-+++
-
-# Provisioning
-
-You can create, change or remove [Custom roles]({{< relref "./roles.md#custom-roles" >}}) and create or remove [built-in role assignments]({{< relref "./roles.md#built-in-role-assignments" >}}), by adding one or more YAML configuration files in the [`provisioning/access-control/`]({{< relref "../../administration/configuration/#provisioning" >}}) directory.
-Refer to [Grafana provisioning]({{< relref "../../administration/configuration/#provisioning" >}}) to learn more about provisioning.
-
-If you want to manage roles and built-in role assignments by API, refer to the [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control/" >}}).
-
-## Configuration
-
-The configuration files must be placed in [`provisioning/access-control/`]({{< relref "../../administration/configuration/#provisioning" >}}).
-Grafana performs provisioning during the startup. Refer to the [Reload provisioning configurations]({{< relref "../../http_api/admin/#reload-provisioning-configurations" >}}) to understand how you can reload configuration at runtime.
-
-## Manage custom roles
-
-You can create, update, and delete custom roles, as well as create and remove built-in role assignments.
-
-### Create or update roles
-
-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 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.
-
-Here is an example YAML file to create a local role with a set of permissions:
-
-```yaml
-# config file version
-apiVersion: 1
-
-# Roles to insert into the database, or roles to update in the database
-roles:
- - name: custom:users:editor
- description: 'This role allows users to list, create, or update other users within the organization.'
- version: 1
- orgId: 1
- permissions:
- - action: 'users:read'
- scope: 'users:*'
- - action: 'users:write'
- scope: 'users:*'
- - action: 'users:create'
- scope: 'users:*'
-```
-
-Here is an example YAML file to create a hidden global role with a set of permissions.
-`global:true` option makes a role global, and `hidden:true` option hides the role from the role picker:
-
-```yaml
-# config file version
-apiVersion: 1
-
-# Roles to insert into the database, or roles to update in the database
-roles:
- - name: custom:users:editor
- description: 'This role allows users to list, create, or update other users within the organization.'
- version: 1
- global: true
- hidden: true
- permissions:
- - action: 'users:read'
- scope: 'users:*'
- - action: 'users:write'
- scope: 'users:*'
- - action: 'users:create'
- scope: 'users:*'
-```
-
-The `orgId` is lost when the role is set to global.
-
-### Delete roles
-
-To delete a role, add a list of roles under the `deleteRoles` section in the configuration file.
-
-> **Note:** Any role in the `deleteRoles` section is deleted before any role in the `roles` section is saved.
-
-Here is an example YAML file to delete a role:
-
-```yaml
-# config file version
-apiVersion: 1
-
-# list of roles that should be deleted
-deleteRoles:
- - name: custom:reports:editor
- orgId: 1
- force: true
-```
-
-### Assign your custom role to specific built-in roles
-
-To assign roles to built-in roles, add said built-in roles to the `builtInRoles` section of your roles. To remove a specific assignment, remove it from the list.
-
-> **Note:** Assignments are updated if the version of the role is greater or equal to the one stored internally. You don’t need to increment the version number of the role to update its assignments.
-
-For example, the following role is assigned to an organization editor or an organization administrator:
-
-```yaml
-# config file version
-apiVersion: 1
-
-# Roles to insert/update in the database
-roles:
- - name: custom:users:editor
- description: 'This role allows users to list/create/update other users in the organization'
- version: 1
- orgId: 1
- permissions:
- - action: 'users:read'
- scope: 'users:*'
- - action: 'users:write'
- scope: 'users:*'
- - action: 'users:create'
- scope: 'users:*'
- builtInRoles:
- - name: 'Editor'
- - name: 'Admin'
-```
-
-### Assign your custom role to specific teams
-
-To assign roles to teams, add said teams to the `teams` section of your roles. To remove a specific assignment, remove it from the list.
-
-> **Note:** Assignments are updated if the version of the role is greater or equal to the one stored internally.
-> You don’t need to increment the version number of the role to update its assignments.
-> Assignments to built-in roles will be ignored. Use `addDefaultAssignments` and `removeDefaultAssignments` instead.
-
-In order for provisioning to succeed, specified teams must already exist. Additionally, since teams are local to an organization, the organization has to be specified in the assignment.
-
-For example, the following role is assigned to the `user editors` team and `user admins` team:
-
-```yaml
-# config file version
-apiVersion: 1
-
-# Roles to insert/update in the database
-roles:
- - name: custom:users:writer
- description: 'List/update other users in the organization'
- version: 1
- global: true
- permissions:
- - action: 'org.users:read'
- scope: 'users:*'
- - action: 'org.users:write'
- scope: 'users:*'
- teams:
- - name: 'user editors'
- orgId: 1
- - name: 'user admins'
- orgId: 1
-```
-
-### Assign fixed roles to specific teams
-
-To assign a fixed role to teams, add said teams to the `teams` section of the associated entry. To remove a specific assignment, remove it from the list.
-
-> **Note:** Since fixed roles are global, the Global attribute has to be specified. A fixed role will never be updated through provisioning.
-
-In order for provisioning to succeed, specified teams must already exist. Additionally, since teams are local to an organization, the organization has to be specified in the assignment.
-
-For example, the following fixed role is assigned to the `user editors` team and `user admins` team:
-
-```yaml
-# config file version
-apiVersion: 1
-
-# Roles to insert/update in the database
-roles:
- - name: fixed:users:writer
- global: true
- teams:
- - name: 'user editors'
- orgId: 1
- - name: 'user admins'
- orgId: 1
-```
-
-## Manage default built-in role assignments
-
-During startup, Grafana creates [default built-in role assignments]({{< relref "./roles#default-built-in-role-assignments" >}}) with [fixed roles]({{< relref "./roles#fixed-roles" >}}). You can remove and later restore those assignments with provisioning.
-
-### Remove default assignment
-
-To remove default built-in role assignments, use the `removeDefaultAssignments` element in the configuration file. You need to provide the built-in role name and fixed role name.
-
-Here is an example:
-
-```yaml
-# config file version
-apiVersion: 1
-
-# list of default built-in role assignments that should be removed
-removeDefaultAssignments:
- - builtInRole: 'Grafana Admin'
- fixedRole: 'fixed:permissions:admin'
-```
-
-### Restore default assignment
-
-To restore the default built-in role assignment, use the `addDefaultAssignments` element in the configuration file. You need to provide the built-in role name and the fixed-role name.
-
-Here is an example:
-
-```yaml
-# config file version
-apiVersion: 1
-
-# list of default built-in role assignments that should be added back
-addDefaultAssignments:
- - builtInRole: 'Admin'
- fixedRole: 'fixed:reporting:admin:read'
-```
-
-## Full example of a role configuration file
-
-```yaml
-# config file version
-apiVersion: 1
-
-# list of default built-in role assignments that should be removed
-removeDefaultAssignments:
- # , must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
- - builtInRole: 'Grafana Admin'
- # , must be one of the existing fixed roles
- fixedRole: 'fixed:permissions:admin'
-
-# list of default built-in role assignments that should be added back
-addDefaultAssignments:
- # , must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
- - builtInRole: 'Admin'
- # , must be one of the existing fixed roles
- fixedRole: 'fixed:reporting:admin:read'
-
-# list of roles that should be deleted
-deleteRoles:
- # name of the role you want to create. Required if no uid is set
- - name: 'custom:reports:editor'
- # uid of the role. Required if no name
- uid: 'customreportseditor1'
- # org id. will default to Grafana's default if not specified
- orgId: 1
- # force deletion revoking all grants of the role
- force: true
- - name: 'custom:global:reports:reader'
- uid: 'customglobalreportsreader1'
- # overwrite org id and removes a global role
- global: true
- force: true
-
-# list of roles to insert/update depending on what is available in the database
-roles:
- # name of the role you want to create. Required
- - name: 'custom:users:editor'
- # uid of the role. Has to be unique for all orgs.
- uid: customuserseditor1
- # description of the role, informative purpose only.
- description: 'Role for our custom user editors'
- # version of the role, Grafana will update the role when increased
- version: 2
- # org id. will default to Grafana's default if not specified
- orgId: 1
- # list of the permissions granted by this role
- permissions:
- # action allowed
- - action: 'users:read'
- # scope it applies to
- scope: 'users:*'
- - action: 'users:write'
- scope: 'users:*'
- - action: 'users:create'
- scope: 'users:*'
- # list of builtIn roles the role should be assigned to
- builtInRoles:
- # name of the builtin role you want to assign the role to
- - name: 'Editor'
- # org id. will default to the role org id
- orgId: 1
- - name: 'custom:global:users:reader'
- uid: 'customglobalusersreader1'
- description: 'Global Role for custom user readers'
- version: 1
- # overwrite org id and creates a global role
- global: true
- permissions:
- - action: 'users:read'
- scope: 'users:*'
- builtInRoles:
- - name: 'Viewer'
- orgId: 1
- - name: 'Editor'
- # overwrite org id and assign role globally
- global: true
- - name: fixed:users:writer
- global: true
- # list of teams the role should be assigned to
- teams:
- - name: 'user editors'
- orgId: 1
-```
-
-## Supported settings
-
-The following sections detail the supported settings for roles and built-in role assignments.
-
-- Refer to [Permissions]({{< relref "./permissions.md#action-definitions" >}}) for full list of valid permissions.
-- Check [Custom roles]({{< relref "./roles.md#custom-roles" >}}) to understand attributes for roles.
-- The [default org ID]({{< relref "../../administration/configuration#auto_assign_org_id" >}}) is used if `orgId` is not specified in any of the configuration blocks.
-
-## Validation rules
-
-A basic set of validation rules are applied to the input `yaml` files.
-
-### Roles
-
-- `name` must not be empty
-- `name` must not have `fixed:` prefix.
-
-### Permissions
-
-- `name` must not be empty
-
-### Built-in role assignments
-
-- `name` must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`.
-- When `orgId` is not specified, it inherits the `orgId` from `role`. For global roles the default `orgId` is used.
-- `orgId` in the `role` and in the assignment must be the same for none global roles.
-
-### Role deletion
-
-- Either the role `name` or `uid` must be provided
diff --git a/docs/sources/enterprise/access-control/fine-grained-access-control-references.md b/docs/sources/enterprise/access-control/rbac-fixed-basic-role-definitions.md
similarity index 86%
rename from docs/sources/enterprise/access-control/fine-grained-access-control-references.md
rename to docs/sources/enterprise/access-control/rbac-fixed-basic-role-definitions.md
index e2222cffb6a..c4f5e1db44a 100644
--- a/docs/sources/enterprise/access-control/fine-grained-access-control-references.md
+++ b/docs/sources/enterprise/access-control/rbac-fixed-basic-role-definitions.md
@@ -1,58 +1,76 @@
-+++
-title = "Fine-grained access control references"
-description = "Refer to fine-grained access control references"
-keywords = ["grafana", "fine-grained-access-control", "roles", "fixed-roles", "built-in-role-assignments", "permissions", "enterprise"]
-weight = 130
-+++
+---
+title: 'RBAC role definitions'
+menuTitle: 'RBAC role definitions'
+description: 'This topic includes a table that lists permission associated with Grafana fixed and basic roles.'
+aliases: [docs/grafana/latest/enterprise/access-control/fine-grained-access-control-references/]
+weight: 70
+---
-# Fine-grained access control references
+# RBAC role definitions
-The reference information that follows complements conceptual information about [Roles]({{< relref "./roles.md" >}}).
+The following tables list permissions associated with basic and fixed roles.
-## Fine-grained access fixed roles
+## Basic role assignments
-| Fixed roles | Permissions | Descriptions |
+| Basic role | Associated fixed roles | 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 "../../administration/manage-users-and-permissions/about-users-and-permissions.md#grafana-server-administrators" >}}) 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`
`fixed:dashboards:reader`
`fixed:dashboards:writer`
`fixed:dashboards.permissions:reader`
`fixed:dashboards.permissions:writer`
`fixed:folders:reader`
`fixes:folders:writer`
`fixed:folders.permissions:reader`
`fixed:folders.permissions:writer`
`fixed:alerting:editor` | Default [Grafana organization administrator]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md#organization-users-and-permissions" >}}) assignments. |
+| Editor | `fixed:datasources:explorer`
`fixed:dashboards:creator`
`fixed:folders:creator`
`fixed:annotations:writer`
`fixed:teams:creator` if the `editors_can_admin` configuration flag is enabled
`fixed:alerting:editor` | Default [Editor]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md#organization-users-and-permissions" >}}) assignments. |
+| Viewer | `fixed:datasources:id:reader`
`fixed:organization:reader`
`fixed:annotations:reader`
`fixed:annotations.dashboard:writer`
`fixed:alerting:reader` | Default [Viewer]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md#organization-users-and-permissions" >}}) assignments. |
+
+## Fixed role definitions
+
+| Fixed role | Permissions | Description |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fixed:roles:reader` | `roles:read`
`roles:list`
`teams.roles:list`
`users.roles:list`
`users.permissions:list`
`roles.builtin:list` | Read all access control roles, roles and permissions assigned to users, teams and built-in role assignments. |
-| `fixed:roles:writer` | All permissions from `fixed:roles:reader` and
`roles:write`
`roles:delete`
`teams.roles:add`
`teams.roles:remove`
`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, teams 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. |
-| `fixed:users:writer` | All permissions from `fixed:users:reader` and
`users:write`
`users:create`
`users:delete`
`users:enable`
`users:disable`
`users.password:update`
`users.permissions:update`
`users:logout`
`users.authtoken:update`
`users.quotas:update` | Read and update all attributes and settings for all users in Grafana: update user information, read user information, create or enable or disable a user, make a user a Grafana administrator, sign out a user, update a user’s authentication token, or update quotas for all users. |
-| `fixed:org.users:reader` | `org.users:read` | Read users within a single organization. |
-| `fixed:org.users:writer` | All permissions from `fixed:org.users:reader` and
`org.users:add`
`org.users:remove`
`org.users.role:update` | Within a single organization, add a user, invite a user, read information about a user and their role, remove a user from that organization, or change the role of a user. |
-| `fixed:ldap:reader` | `ldap.user:read`
`ldap.status:read` | Read the LDAP configuration and LDAP status information. |
-| `fixed:ldap:writer` | All permissions from `fixed:ldap:reader` and
`ldap.user:sync`
`ldap.config:reload` | Read and update the LDAP configuration, and read LDAP status information. |
-| `fixed:stats:reader` | `server.stats:read` | Read Grafana instance statistics. |
-| `fixed:settings:reader` | `settings:read` | Read Grafana instance settings. |
-| `fixed:settings:writer` | All permissions from `fixed:settings:reader` and
`settings:write` | Read and update Grafana instance settings. |
-| `fixed:datasources:explorer` | `datasources:explore` | Enable the Explore feature. Data source permissions still apply, you can only query data sources for which you have query permissions. |
-| `fixed:datasources:reader` | `datasources:read`
`datasources:query` | Read and query data sources. |
-| `fixed:datasources:writer` | All permissions from `fixed:datasources:reader` and
`datasources:create`
`datasources:write`
`datasources:delete` | Read, query, create, delete, or update a data source. |
-| `fixed:datasources:id:reader` | `datasources.id:read` | Read the ID of a data source based on its name. |
-| `fixed:datasources.permissions:reader` | `datasources.permissions:read` | Read data source permissions. |
-| `fixed:datasources.permissions:writer` | All permissions from `fixed:datasources.permissions:reader` and
`datasources.permissions:write` | Create, read, or delete permissions of a data source. |
-| `fixed:licensing:reader` | `licensing:read`
`licensing.reports:read` | Read licensing information and licensing reports. |
-| `fixed:licensing:writer` | All permissions from `fixed:licensing:viewer` and
`licensing:update`
`licensing:delete` | Read licensing information and licensing reports, update and delete the license token. |
-| `fixed:provisioning:writer` | `provisioning:reload` | Reload provisioning. |
-| `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. |
+| `fixed:alerting.instances:editor` | All permissions from `fixed:alerting.instances:reader` and
`alert.instances:create`
`alert.instances:update` for organization scope
`alert.instances.external:write` for scope `datasources:*` | Create, update and expire all silences in the organization produced by Grafana, Mimir, and Loki.[\*](#alerting-roles) |
+| `fixed:alerting.instances:reader` | `alert.instances:read` for organization scope
`alert.instances.external:read` for scope `datasources:*` | Read all alerts and silences in the organization produced by Grafana Alerts and Mimir and Loki alerts and silences.[\*](#alerting-roles) |
+| `fixed:alerting.notifications:editor` | All permissions from `fixed:alerting.notifications:reader` and
`alert.notifications:create`
`alert.notifications:update`
`alert.notifications:delete` for organization scope
`alert.notifications.external:read` for scope `datasources:*` | Create, update, and delete contact points, templates, mute timings and notification policies for Grafana and external Alertmanager.[\*](#alerting-roles) |
+| `fixed:alerting.notifications:reader` | `alert.notifications:read` for organization scope
`alert.notifications.external:read` for scope `datasources:*` | Read all Grafana and Alertmanager contact points, templates, and notification policies.[\*](#alerting-roles) |
+| `fixed:alerting.rules:editor` | All permissions from `fixed:alerting.rules:reader` and
`alert.rule:create`
`alert.rule:update`
`alert.rule:delete` for scope `folders:*`
`alert.rules.external:write` for scope `datasources:*` | Create, update, and delete all\* Grafana, Mimir, and Loki alert rules.[\*](#alerting-roles) |
+| `fixed:alerting.rules:reader` | `alert.rule:read` for scope `folders:*`
`alert.rules.external:read` for scope `datasources:*` | Read all\* Grafana, Mimir, and Loki alert rules.[\*](#alerting-roles) |
+| `fixed:alerting:editor` | All permissions from `fixed:alerting.rules:editor`
`fixed:alerting.instances:editor`
`fixed:alerting.notifications:editor` | Create, update, and delete Grafana, Mimir, Loki and Alertmanager alert rules\*, silences, contact points, templates, mute timings, and notification policies.[\*](#alerting-roles) |
+| `fixed:alerting:reader` | All permissions from `fixed:alerting.rules:reader`
`fixed:alerting.instances:reader`
`fixed:alerting.notifications:reader` | Read-only permissions for all Grafana, Mimir, Loki and Alertmanager alert rules\*, alerts, contact points, and notification policies.[\*](#alerting-roles) |
+| `fixed:annotations.dashboard:writer` | `annotations:write`
`annotations.create`
`annotations:delete` for scope `annotations:type:dashboard` | Create, update and delete dashboard annotations and annotation tags. |
+| `fixed:annotations:reader` | `annotations:read` | Read all annotations and annotation tags. |
+| `fixed:annotations:writer` | `annotations:write`
`annotations.create`
`annotations:delete` for scope `annotations:type:*` | Create, update and delete all annotations and annotation tags. |
+| `fixed:dashboards.permissions:reader` | `dashboards.permissions:read` | Read all dashboard permissions. |
+| `fixed:dashboards.permissions:writer` | All permissions from `fixed:dashboards.permissions:reader` and
`dashboards.permissions:write` | Read and update all dashboard permissions. |
| `fixed:dashboards:creator` | `dashboards:create`
`folders:read` | Create dashboards. |
| `fixed:dashboards:reader` | `dashboards:read` | Read all dashboards. |
| `fixed:dashboards:writer` | All permissions from `fixed:dashboards:reader` and
`dashboards:write`
`dashboards:edit`
`dashboards:delete`
`dashboards:create`
`dashboards.permissions:read`
`dashboards.permissions:write` | Read, create, update, and delete all dashboards. |
-| `fixed:dashboards.permissions:reader` | `dashboards.permissions:read` | Read all dashboard permissions. |
-| `fixed:dashboards.permissions:writer` | All permissions from `fixed:dashboards.permissions:reader` and
`dashboards.permissions:write` | Read and update all dashboard permissions. |
+| `fixed:datasources.permissions:reader` | `datasources.permissions:read` | Read data source permissions. |
+| `fixed:datasources.permissions:writer` | All permissions from `fixed:datasources.permissions:reader` and
`datasources.permissions:write` | Create, read, or delete permissions of a data source. |
+| `fixed:datasources:explorer` | `datasources:explore` | Enable the Explore feature. Data source permissions still apply, you can only query data sources for which you have query permissions. |
+| `fixed:datasources:id:reader` | `datasources.id:read` | Read the ID of a data source based on its name. |
+| `fixed:datasources:reader` | `datasources:read`
`datasources:query` | Read and query data sources. |
+| `fixed:datasources:writer` | All permissions from `fixed:datasources:reader` and
`datasources:create`
`datasources:write`
`datasources:delete` | Read, query, create, delete, or update a data source. |
+| `fixed:folders.permissions:reader` | `folders.permissions:read` | Read all folder permissions. |
+| `fixed:folders.permissions:writer` | All permissions from `fixed:folders.permissions:reader` and
`folders.permissions:write` | Read and update all folder permissions. |
| `fixed:folders:creator` | `folders:create` | Create folders. |
| `fixed:folders:reader` | `folders:read`
`dashboards:read` | Read all folders and dashboards. |
| `fixed:folders:writer` | All permissions from `fixed:dashboards:writer` and
`folders:read`
`folders:write`
`folders:create`
`folders:delete`
`folders.permissions:read`
`folders.permissions:write` | Read, create, update, and delete all folders and dashboards. |
-| `fixed:folders.permissions:reader` | `folders.permissions:read` | Read all folder permissions. |
-| `fixed:folders.permissions:writer` | All permissions from `fixed:folders.permissions:reader` and
`folders.permissions:write` | Read and update all folder permissions. |
-| `fixed:annotations:reader` | `annotations:read` | Read all annotations and annotation tags. |
-| `fixed:annotations.dashboard:writer` | `annotations:write`
`annotations.create`
`annotations:delete` for scope `annotations:type:dashboard` | Create, update and delete dashboard annotations and annotation tags. |
-| `fixed:annotations:writer` | `annotations:write`
`annotations.create`
`annotations:delete` for scope `annotations:type:*` | Create, update and delete all annotations and annotation tags. |
+| `fixed:ldap:reader` | `ldap.user:read`
`ldap.status:read` | Read the LDAP configuration and LDAP status information. |
+| `fixed:ldap:writer` | All permissions from `fixed:ldap:reader` and
`ldap.user:sync`
`ldap.config:reload` | Read and update the LDAP configuration, and read LDAP status information. |
+| `fixed:licensing:reader` | `licensing:read`
`licensing.reports:read` | Read licensing information and licensing reports. |
+| `fixed:licensing:writer` | All permissions from `fixed:licensing:viewer` and
`licensing:update`
`licensing:delete` | Read licensing information and licensing reports, update and delete the license token. |
+| `fixed:org.users:reader` | `org.users:read` | Read users within a single organization. |
+| `fixed:org.users:writer` | All permissions from `fixed:org.users:reader` and
`org.users:add`
`org.users:remove`
`org.users.role:update` | Within a single organization, add a user, invite a user, read information about a user and their role, remove a user from that organization, or change the role of a user. |
+| `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: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:provisioning:writer` | `provisioning:reload` | Reload provisioning. |
+| `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:roles:reader` | `roles:read`
`roles:list`
`teams.roles:list`
`users.roles:list`
`users.permissions:list`
`roles.builtin:list` | Read all access control roles, roles and permissions assigned to users, teams and built-in role assignments. |
+| `fixed:roles:writer` | All permissions from `fixed:roles:reader` and
`roles:write`
`roles:delete`
`teams.roles:add`
`teams.roles:remove`
`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, teams and built-in role assignments. |
+| `fixed:settings:reader` | `settings:read` | Read Grafana instance settings. |
+| `fixed:settings:writer` | All permissions from `fixed:settings:reader` and
`settings:write` | Read and update Grafana instance settings. |
+| `fixed:stats:reader` | `server.stats:read` | Read Grafana instance statistics. |
+| `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. |
+| `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. |
+| `fixed:users:writer` | All permissions from `fixed:users:reader` and
`users:write`
`users:create`
`users:delete`
`users:enable`
`users:disable`
`users.password:update`
`users.permissions:update`
`users:logout`
`users.authtoken:update`
`users.quotas:update` | Read and update all attributes and settings for all users in Grafana: update user information, read user information, create or enable or disable a user, make a user a Grafana administrator, sign out a user, update a user’s authentication token, or update quotas for all users. |
### Alerting roles
@@ -60,28 +78,7 @@ If you [enable]({{< relref "../../alerting/unified-alerting/opt-in.md" >}}) Graf
Access to Grafana alert rules is an intersection of many permissions:
-- Permission to read a folder, for example, the fixed role `fixed:folders:reader` or action `folders:read` in the scope of a folder `folders:id:`
-- Permission to manage alerts. The following table contains information about alerting fixed roles.
-- Permission to query **all** data sources that the rule uses, for example, the fixed role `fixed:datasources:reader` or action `datasources:query` in the scope of `datasources:uid:`.
+- Permission to read a folder. For example, the fixed role `fixed:folders:reader` includes the action `folders:read` and a folder scope `folders:id:`.
+- Permission to query **all** data sources that a given alert rule uses. If a user cannot query a given data source, they cannot see any alert rules that query that data source.
-For more information about the permissions required to access alert rules, refer to [Create a custom role to access alerts in a folder]({{< relref "./usage-scenarios.md#create-a-custom-role-to-access-alerts-in-a-folder" >}}).
-
-| Fixed roles | Permissions | Descriptions |
-| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fixed:alerting.rules:reader` | `alert.rule:read` for scope `folders:*`
`alert.rules.external:read` for scope `datasources:*` | Read all\* Grafana, Mimir, and Loki alert rules |
-| `fixed:alerting.rules:editor` | All permissions from `fixed:alerting.rules:reader` and
`alert.rule:create`
`alert.rule:update`
`alert.rule:delete` for scope `folders:*`
`alert.rules.external:write` for scope `datasources:*` | Create, update, and delete all\* Grafana, Mimir, and Loki alert rules. |
-| `fixed:alerting.instances:reader` | `alert.instances:read` for organization scope
`alert.instances.external:read` for scope `datasources:*` | Read all alerts and silences in the organization produced by Grafana Alerts and Mimir and Loki alerts and silences. |
-| `fixed:alerting.instances:editor` | All permissions from `fixed:alerting.instances:reader` and
`alert.instances:create`
`alert.instances:update` for organization scope
`alert.instances.external:write` for scope `datasources:*` | Create, update and expire all silences in the organization produced by Grafana, Mimir, and Loki. |
-| `fixed:alerting.notifications:reader` | `alert.notifications:read` for organization scope
`alert.notifications.external:read` for scope `datasources:*` | Read all Grafana and Alertmanager contact points, templates, and notification policies. |
-| `fixed:alerting.notifications:editor` | All permissions from `fixed:alerting.notifications:reader` and
`alert.notifications:create`
`alert.notifications:update`
`alert.notifications:delete` for organization scope
`alert.notifications.external:read` for scope `datasources:*` | Create, update, and delete contact points, templates, mute timings and notification policies for Grafana and external Alertmanager. |
-| `fixed:alerting:reader` | All permissions from `fixed:alerting.rules:reader`
`fixed:alerting.instances:reader`
`fixed:alerting.notifications:reader` | Read-only permissions for all Grafana, Mimir, Loki and Alertmanager alert rules\*, alerts, contact points, and notification policies. |
-| `fixed:alerting:editor` | All permissions from `fixed:alerting.rules:editor`
`fixed:alerting.instances:editor`
`fixed:alerting.notifications:editor` | Create, update, and delete Grafana, Mimir, Loki and Alertmanager alert rules\*, silences, contact points, templates, mute timings, and notification policies. |
-
-## 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 "../../administration/manage-users-and-permissions/about-users-and-permissions.md#grafana-server-administrators" >}}) 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`
`fixed:dashboards:reader`
`fixed:dashboards:writer`
`fixed:dashboards.permissions:reader`
`fixed:dashboards.permissions:writer`
`fixed:folders:reader`
`fixes:folders:writer`
`fixed:folders.permissions:reader`
`fixed:folders.permissions:writer`
`fixed:alerting:editor` | Default [Grafana organization administrator]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md#organization-users-and-permissions" >}}) assignments. |
-| Editor | `fixed:datasources:explorer`
`fixed:dashboards:creator`
`fixed:folders:creator`
`fixed:annotations:writer`
`fixed:teams:creator` if the `editors_can_admin` configuration flag is enabled
`fixed:alerting:editor` | Default [Editor]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md#organization-users-and-permissions" >}}) assignments. |
-| Viewer | `fixed:datasources:id:reader`
`fixed:organization:reader`
`fixed:annotations:reader`
`fixed:annotations.dashboard:writer`
`fixed:alerting:reader` | Default [Viewer]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md#organization-users-and-permissions" >}}) assignments. |
+For more information about the permissions required to access alert rules, refer to [Create a custom role to access alerts in a folder]({{< relref "./plan-rbac-rollout-strategy#create-a-custom-role-to-access-alerts-in-a-folder" >}}).
diff --git a/docs/sources/enterprise/access-control/roles.md b/docs/sources/enterprise/access-control/roles.md
deleted file mode 100644
index 77d865f8618..00000000000
--- a/docs/sources/enterprise/access-control/roles.md
+++ /dev/null
@@ -1,91 +0,0 @@
-+++
-title = "Roles"
-description = "Understand roles in fine-grained access control"
-keywords = ["grafana", "fine-grained-access-control", "roles", "fixed-roles", "built-in-role-assignments", "permissions", "enterprise"]
-weight = 105
-+++
-
-# Roles
-
-A role represents set of permissions that allow you to perform specific actions on Grafana resources. Refer to [About users and permissions]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md" >}}) to understand how permissions work.
-
-There are two types of roles:
-
-- [Fixed roles]({{< relref "./roles.md#fixed-roles" >}}), which provide granular access for specific resources within Grafana and are managed by the Grafana itself.
-- [Custom roles]({{< relref "./roles.md#custom-roles.md" >}}), which provide granular access based on the user specified set of permissions.
-
-You can use [Fine-grained access control API]({{< relref "../../http_api/access_control.md" >}}) to list available roles and permissions.
-
-## Role scopes
-
-A role can be either _global_ or _organization local_. _Global_ roles are not mapped to any specific organization and can be reused across multiple organizations, whereas _organization local_ roles are only available for that specific organization.
-
-## Fixed roles
-
-Fixed roles provide convenience and guarantee of consistent behaviour by combining relevant [permissions]({{< relref "./permissions.md" >}}) together. Fixed roles are created and updated by Grafana during startup.
-There are few basic rules for fixed roles:
-
-- All fixed roles are _global_.
-- All fixed roles have a `fixed:` prefix.
-- You can’t change or delete a fixed role.
-
-For more information, refer to [Fine-grained access control references]({{< relref "./fine-grained-access-control-references.md#fine-grained-access-fixed-roles" >}}).
-
-## Custom roles
-
-Custom roles allow you to manage access to your users the way you want, by mapping [fine-grained permissions]({{< relref "./permissions.md" >}}) to it and creating [built-in role assignments]({{< ref "#built-in-role-assignments.md" >}}).
-
-To create, update or delete a custom role, you can use the [Fine-grained access control API]({{< relref "../../http_api/access_control.md" >}}) or [Grafana Provisioning]({{< relref "./provisioning.md" >}}).
-
-### Role name
-
-A role's name is intended as a human friendly identifier for the role, helping administrators understand the purpose of a role. The name cannot be longer than 190 characters, and we recommend using ASCII characters.
-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.
-
-### Role display name
-
-A role’s display name is human friendly text that is displayed in the UI. When you create a display name for a role, use up to 190 ASCII-based characters. For fixed roles, the display name is shown as specified. If the display name has not been set the display name replace any `:` (a colon) with ` ` (a space).
-
-### Display name
-
-A role’s display name is a human-friendly identifier for the role, so that users more easily understand the purpose of a role. You can see the display name in the role picker in the UI.
-
-### Group
-
-A role’s group organizes 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.
-
-### Permissions
-
-You manage access to Grafana resources by mapping [permissions]({{< relref "./permissions.md" >}}) to roles. You can create and assign roles without any permissions as placeholders.
-
-### Role UID
-
-Each custom role has a UID defined which is a unique identifier associated with the role allowing you to change or delete the role. You can either generate UID yourself, or let Grafana generate one for you.
-
-The same UID cannot be used for roles in different organizations within the same Grafana instance.
-
-## Create, update and delete roles
-
-You can create, update and delete custom roles by using the [Access Control HTTP API]({{< relref "../../http_api/access_control.md" >}}) or by using [Grafana Provisioning]({{< relref "./provisioning.md" >}}).
-
-By default, Grafana Server Admin has a [built-in role assignment]({{< ref "#built-in-role-assignments" >}}) which allows a user to create, update or delete custom roles.
-If a Grafana Server Admin wants to delegate that privilege to other users, they can create a custom role with relevant [permissions]({{< relref "./permissions.md" >}}) and `permissions:delegate` scope will allow those users to manage roles themselves.
-
-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.
-
-## Assign roles
-
-[Custom roles]({{< ref "#custom-roles" >}}) and [Fixed roles]({{< ref "#fixed-roles" >}}) can be assigned to users, the existing [Organization roles]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md#organization-users-and-permissions" >}}) and to the [Grafana Server Admin]({{< relref "../../administration/manage-users-and-permissions/about-users-and-permissions.md#grafana-server-administrators" >}}) role.
-
-Visit [Manage role assignments]({{< relref "manage-role-assignments/_index.md" >}}) page for more details.
-
-### Scope of assignments
-
-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
deleted file mode 100644
index 5f44c447eeb..00000000000
--- a/docs/sources/enterprise/access-control/usage-scenarios.md
+++ /dev/null
@@ -1,276 +0,0 @@
-+++
-title = "Fine-grained access control usage scenarios"
-description = "Fine-grained access control usage scenarios"
-keywords = ["grafana", "fine-grained-access-control", "roles", "permissions", "fine-grained-access-control-usage", "enterprise"]
-weight = 125
-+++
-
-# Fine-grained access control usage scenarios
-
-This guide contains several examples and usage scenarios of using fine-grained roles and permissions for controlling access to Grafana resources.
-
-Before you get started, make sure to [enable fine-grained access control]({{< relref "./_index.md#enable-fine-grained-access-control" >}}).
-
-## Check all built-in role assignments
-
-You can use the [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control.md#get-all-built-in-role-assignments" >}}) to see all available built-in role assignments.
-The response contains a mapping between one of the organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin` to the custom or fixed roles.
-
-Example request:
-
-```
-curl --location --request GET '/api/access-control/builtin-roles' --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ='
-```
-
-You must use the base64 username:password Basic Authorization here. Auth tokens are not applicable here.
-
-Example response:
-
-```
-{
- "Admin": [
- ...
- {
- "version": 2,
- "uid": "qQui_LCMk",
- "name": "fixed:users:org:writer",
- "displayName": "Users Organization writer",
- "description": "Within a single organization, add a user, invite a user, read information about a user and their role, remove a user from that organization, or change the role of a user.",
- "global": true,
- "updated": "2021-05-17T20:49:18+02:00",
- "created": "2021-05-13T16:24:26+02:00"
- },
- {
- "version": 1,
- "uid": "Kz9m_YjGz",
- "name": "fixed:reports:writer",
- "displayName": "Report writer",
- "description": "Create, read, update, or delete all reports and shared report settings.",
- "global": true,
- "updated": "2021-05-13T16:24:26+02:00",
- "created": "2021-05-13T16:24:26+02:00"
- }
- ...
- ],
- "Grafana Admin": [
- ...
- {
- "version": 2,
- "uid": "qQui_LCMk",
- "name": "fixed:users:writer",
- "displayName": "User writer",
- "description": "Read and update all attributes and settings for all users in Grafana: update user information, read user information, create or enable or disable a user, make a user a Grafana administrator, sign out a user, update a user’s authentication token, or update quotas for all users.",
- "global": true,
- "updated": "2021-05-17T20:49:18+02:00",
- "created": "2021-05-13T16:24:26+02:00"
- },
- {
- "version": 2,
- "uid": "ajum_YjGk",
- "name": "fixed:users:reader",
- "displayName": "User reader",
- "description": "Allows every read action for user organizations and in addition allows to administer user organizations.",
- "global": true,
- "updated": "2021-05-17T20:49:17+02:00",
- "created": "2021-05-13T16:24:26+02:00"
- },
- ...
- ]
-}
-```
-
-To see what permissions each of the assigned roles have, you can a [Get a role]({{< relref "../../http_api/access_control.md#get-a-role" >}}) by using an HTTP API.
-
-Example request:
-
-```
-curl --location --request GET '/api/access-control/roles/qQui_LCMk' --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ='
-```
-
-Example response:
-
-```
-{
- "version": 2,
- "uid": "qQui_LCMk",
- "name": "fixed:users:writer",
- "displayName": "User writer",
- "description": "Read and update all attributes and settings for all users in Grafana: update user information, read user information, create or enable or disable a user, make a user a Grafana administrator, sign out a user, update a user’s authentication token, or update quotas for all users.",
- "global": true,
- "permissions": [
- {
- "action": "org.users:add",
- "scope": "users:*",
- "updated": "2021-05-17T20:49:18+02:00",
- "created": "2021-05-17T20:49:18+02:00"
- },
- {
- "action": "org.users:read",
- "scope": "users:*",
- "updated": "2021-05-17T20:49:18+02:00",
- "created": "2021-05-17T20:49:18+02:00"
- },
- {
- "action": "org.users:remove",
- "scope": "users:*",
- "updated": "2021-05-17T20:49:18+02:00",
- "created": "2021-05-17T20:49:18+02:00"
- },
- {
- "action": "org.users.role:update",
- "scope": "users:*",
- "updated": "2021-05-17T20:49:18+02:00",
- "created": "2021-05-17T20:49:18+02:00"
- }
- ],
- "updated": "2021-05-17T20:49:18+02:00",
- "created": "2021-05-13T16:24:26+02:00"
-}
-```
-
-## 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" >}}).
-You can take a look at [actions and scopes]({{< relref "./provisioning.md#action-definitions" >}}) to decide what permissions would you like to map to your role.
-
-Example HTTP request:
-
-```
-curl --location --request POST '/api/access-control/roles/' \
---header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
---header 'Content-Type: application/json' \
---data-raw '{
- "version": 1,
- "uid": "jZrmlLCkGksdka",
- "name": "custom:users:admin",
- "displayName": "custom users admin",
- "description": "My custom role which gives users permissions to create users",
- "global": true,
- "permissions": [
- {
- "action": "users:create"
- }
- ]
-}'
-```
-
-Example response:
-
-```
-{
- "version": 1,
- "uid": "jZrmlLCkGksdka",
- "name": "custom:users:admin",
- "displayName": "custom users admin",
- "description": "My custom role which gives users permissions to create users",
- "global": true,
- "permissions": [
- {
- "action": "users:create"
- "updated": "2021-05-17T22:07:31.569936+02:00",
- "created": "2021-05-17T22:07:31.569935+02:00"
- }
- ],
- "updated": "2021-05-17T22:07:31.564403+02:00",
- "created": "2021-05-17T22:07:31.564403+02:00"
-}
-```
-
-Once the custom role is created, you can create a built-in role assignment by using an [HTTP API]({{< relref "../../http_api/access_control.md#create-a-built-in-role-assignment" >}}).
-If you created your role using [Grafana provisioning]({{< relref "./provisioning.md" >}}), you can also create the assignment with it.
-
-Example HTTP request:
-
-```
-curl --location --request POST '/api/access-control/builtin-roles' \
---header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
---header 'Content-Type: application/json' \
---data-raw '{
- "roleUid": "jZrmlLCkGksdka",
- "builtinRole": "Viewer",
- "global": true
-}'
-```
-
-Example response:
-
-```
-{
- "message": "Built-in role grant added"
-}
-```
-
-## Allow Viewers to create reports
-
-In order to create reports, you need to have `reports.admin:write` permission. By default, a Grafana Admin or organization Admin can create reports as there is a [built-in role assignment]({{< relref "./roles#built-in-role-assignments" >}}) which comes with `reports.admin:write` permission.
-
-If you want your users who have the `Viewer` organization role to create reports, you have two options:
-
-1. Create a built-in role assignment and map the `fixed:reporting:admin:edit` fixed role to the `Viewer` built-in role. Note that the `fixed:reporting:admin:edit` fixed role allows doing more than creating reports. Refer to [fixed roles]({{< relref "./roles.md#fixed-roles" >}}) for full list of permission assignments.
-1. [Create a custom role]({{< ref "#create-your-custom-role" >}}) with `reports.admin:write` permission, and create a built-in role assignment for `Viewer` organization role.
-
-## Prevent Grafana Admin from creating and inviting users
-
-In order to create users, you need to have `users:create` permission. By default, a user with the Grafana Admin role can create users as there is a [built-in role assignment]({{< relref "./roles#built-in-role-assignments" >}}) which comes with `users:create` permission.
-
-If you want to prevent Grafana Admin from creating users, you can do the following:
-
-1. [Check all built-in role assignments]({{< ref "#check-all-built-in-role-assignments" >}}) to see what built-in role assignments are available.
-1. From built-in role assignments, find the role which gives `users:create` permission. Refer to [fixed roles]({{< relref "./roles.md#fixed-roles" >}}) for full list of permission assignments.
-1. Remove the built-in role assignment by using an [Fine-grained access control HTTP API]({{< relref "../../http_api/access_control.md" >}}) or by using [Grafana provisioning]({{< relref "./provisioning" >}}).
-
-## Allow Editors to create new custom roles
-
-By default, the Grafana Server Admin is the only user who can create and manage custom roles. If you want your users to do the same, you have two options:
-
-1. Create a built-in role assignment and map `fixed:permissions:admin:edit` and `fixed:permissions:admin:read` fixed roles to the `Editor` built-in role.
-1. [Create a custom role]({{< ref "#create-your-custom-role" >}}) with `roles.builtin:add` and `roles:write` permissions, then create a built-in role assignment for `Editor` organization role.
-
-Note that any user with the ability to modify roles can only create, update or delete roles with permissions they themselves have been granted. For example, a user with the `Editor` role would be able to create and manage roles only with the permissions they have, or with a subset of them.
-
-## Create a custom role to access alerts in a folder
-
-To see an alert rule in Grafana, the user must have read access to the folder that stores the alert rule, permission to read alerts in the folder, and permission to query all data sources that the rule uses.
-
-The API command in this example is based on the following:
-
-- A `Test-Folder` with ID `92`
-- Two data sources: `DS1` with UID `_oAfGYUnk`, and `DS2` with UID `YYcBGYUnk`
-- An alert rule that is stored in `Test-Folder` and queries the two data sources.
- The following request creates a custom role that includes permissions to access the alert rule:
-
-```
-curl --location --request POST '/api/access-control/roles/' \
---header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
---header 'Content-Type: application/json' \
---data-raw '{
- "version": 1,
- "name": "custom:alerts.reader.in.folder.123",
- "displayName": "Read-only access to alerts in folder Test-Folder",
- "description": "Let user query DS1 and DS2, and read alerts in folder Test-Folders",
- "group":"Custom",
- "global": true,
- "permissions": [
- {
- "action": "folders:read",
- "scope": "folders:id:92"
- },
- {
- "action": "alert.rules:read",
- "scope": "folders:id:92"
- },
- {
- "action": "datasources:query",
- "scope": "datasources:uid:_oAfGYUnk"
- },
- {
- "action": "datasources:query",
- "scope": "datasources:uid:YYcBGYUnk"
- }
- ]
-}'
-```
diff --git a/docs/sources/enterprise/enhanced_ldap.md b/docs/sources/enterprise/enhanced_ldap.md
index d07f1b37750..9b760f94b71 100644
--- a/docs/sources/enterprise/enhanced_ldap.md
+++ b/docs/sources/enterprise/enhanced_ldap.md
@@ -11,7 +11,7 @@ The enhanced LDAP integration adds additional functionality on top of the [LDAP
> Enhanced LDAP integration is only available in [Grafana Cloud Advanced](https://grafana.com/docs/grafana-cloud/) and in [Grafana Enterprise]({{< relref "../enterprise" >}}).
-> Refer to [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how you can control access with fine-grained permissions.
+> Refer to [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how you can control access with role-based permissions.
## LDAP group synchronization for teams
diff --git a/docs/sources/enterprise/license/_index.md b/docs/sources/enterprise/license/_index.md
index f3595fbfc04..449a3be211e 100644
--- a/docs/sources/enterprise/license/_index.md
+++ b/docs/sources/enterprise/license/_index.md
@@ -7,7 +7,7 @@ weight = 10
# Grafana Enterprise license
-When you become a Grafana Enterprise customer, you gain access to Grafana's premium observability features, including enterprise data source plugins, reporting, and fine-grained access control. In order to use these [enhanced features of Grafana Enterprise]({{< relref "../_index.md" >}}), you must purchase and activate a Grafana Enterprise license.
+When you become a Grafana Enterprise customer, you gain access to Grafana's premium observability features, including enterprise data source plugins, reporting, and role-based access control. In order to use these [enhanced features of Grafana Enterprise]({{< relref "../_index.md" >}}), you must purchase and activate a Grafana Enterprise license.
To purchase a license directly from Grafana Labs, [Contact a Grafana Labs representative](https://grafana.com/contact?about=grafana-enterprise). To activate an Enterprise license purchased from Grafana Labs, refer to [Activate an Enterprise license]({{< relref "./activate-license.md" >}}).
diff --git a/docs/sources/enterprise/reporting.md b/docs/sources/enterprise/reporting.md
index d38d3c8b492..f1404c4afc7 100644
--- a/docs/sources/enterprise/reporting.md
+++ b/docs/sources/enterprise/reporting.md
@@ -10,7 +10,7 @@ weight = 800
Reporting allows you to automatically generate PDFs from any of your dashboards and have Grafana email them to interested parties on a schedule. This is available in Grafana Cloud Pro and Advanced and in Grafana Enterprise.
-> If you have [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some actions you would need to have relevant permissions.
+> If you have [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some actions you would need to have relevant permissions.
> Refer to specific guides to understand what permissions are required.
{{< figure src="/static/img/docs/enterprise/reports_list_8.1.png" max-width="500px" class="docs-image--no-shadow" >}}
@@ -24,11 +24,11 @@ Any changes you make to a dashboard used in a report are reflected the next time
## Access control
-When [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) is enabled, you need to have the relevant [Permissions]({{< relref "../enterprise/access-control/permissions.md" >}}) to create and manage reports.
+When [RBAC]({{< relref "../enterprise/access-control/_index.md" >}}) is enabled, you need to have the relevant [Permissions]({{< relref "../enterprise/access-control/rbac-fixed-basic-role-definitions" >}}) to create and manage reports.
## Create or update a report
-Only organization admins can create reports by default. You can customize who can create reports with [fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}).
+Only organization admins can create reports by default. You can customize who can create reports with [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}).
1. Click on the reports icon in the side menu. The Reports tab allows you to view, create, and update your reports.
1. Enter report information. All fields are required unless otherwise indicated.
diff --git a/docs/sources/enterprise/settings-updates.md b/docs/sources/enterprise/settings-updates.md
index 37155eef489..2a9a91d1173 100644
--- a/docs/sources/enterprise/settings-updates.md
+++ b/docs/sources/enterprise/settings-updates.md
@@ -85,7 +85,7 @@ settings updates. If there are updates, it reloads the Grafana services affected
The background job synchronizes settings between instances in high availability set-ups. So, after you perform some changes through the
HTTP API, then the other instances are synchronized through the database and the background job.
-## Control access with fine-grained access control
+## Control access with role-based access control
-If you have [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, you can control who can read or update settings.
+If you have [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, you can control who can read or update settings.
Refer to the [Admin API]({{< relref "../http_api/admin.md#update-settings" >}}) for more information.
diff --git a/docs/sources/explore/_index.md b/docs/sources/explore/_index.md
index b9552d5bc3b..bfd472da63c 100644
--- a/docs/sources/explore/_index.md
+++ b/docs/sources/explore/_index.md
@@ -9,7 +9,7 @@ weight = 90
Grafana's dashboard UI is all about building dashboards for visualization. Explore strips away the dashboard and panel options so that you can focus on the query. It helps you iterate until you have a working query and then think about building a dashboard.
-> Refer to [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how you can control access with fine-grained permissions.
+> Refer to [Role-based access control]({{< relref "../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how you can control access with role-based permissions.
If you just want to explore your data and do not want to create a dashboard, then Explore makes this much easier. If your data source supports graph and table data, then Explore shows the results both as a graph and a table. This allows you to see trends in the data and more details at the same time. See also:
@@ -20,7 +20,7 @@ If you just want to explore your data and do not want to create a dashboard, the
## Start exploring
-> Refer to [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how you can manage Explore with fine-grained permissions.
+> Refer to [Role-based access Control]({{< relref "../enterprise/access-control/_index.md" >}}) in Grafana Enterprise to understand how you can manage Explore with role-based permissions.
In order to access Explore, you must have an editor or an administrator role, unless the [viewers_can_edit option]({{< relref "../administration/configuration/#viewers_can_edit" >}}) is enabled. Refer to [About users and permissions]({{< relref "../administration/manage-users-and-permissions/about-users-and-permissions.md" >}}) for more information on what each role has access to.
diff --git a/docs/sources/http_api/_index.md b/docs/sources/http_api/_index.md
index 6efe8f5126b..2242964cec9 100644
--- a/docs/sources/http_api/_index.md
+++ b/docs/sources/http_api/_index.md
@@ -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" >}})
diff --git a/docs/sources/http_api/access_control.md b/docs/sources/http_api/access_control.md
index c33b727698b..bd32d8355c2 100644
--- a/docs/sources/http_api/access_control.md
+++ b/docs/sources/http_api/access_control.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
diff --git a/docs/sources/http_api/admin.md b/docs/sources/http_api/admin.md
index b7d0f854711..58aaf0847c6 100644
--- a/docs/sources/http_api/admin.md
+++ b/docs/sources/http_api/admin.md
@@ -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
diff --git a/docs/sources/http_api/annotations.md b/docs/sources/http_api/annotations.md
index a925a6d6b53..67d31126a5f 100644
--- a/docs/sources/http_api/annotations.md
+++ b/docs/sources/http_api/annotations.md
@@ -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
diff --git a/docs/sources/http_api/data_source.md b/docs/sources/http_api/data_source.md
index a46ef3b2774..15c78d89d99 100644
--- a/docs/sources/http_api/data_source.md
+++ b/docs/sources/http_api/data_source.md
@@ -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
diff --git a/docs/sources/http_api/datasource_permissions.md b/docs/sources/http_api/datasource_permissions.md
index bc8acd8dd4a..c82a8f90661 100644
--- a/docs/sources/http_api/datasource_permissions.md
+++ b/docs/sources/http_api/datasource_permissions.md
@@ -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.
diff --git a/docs/sources/http_api/external_group_sync.md b/docs/sources/http_api/external_group_sync.md
index 095739bd7e1..a6b999a08c2 100644
--- a/docs/sources/http_api/external_group_sync.md
+++ b/docs/sources/http_api/external_group_sync.md
@@ -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
diff --git a/docs/sources/http_api/licensing.md b/docs/sources/http_api/licensing.md
index aa7bd6272e9..eb1ff062b10 100644
--- a/docs/sources/http_api/licensing.md
+++ b/docs/sources/http_api/licensing.md
@@ -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
diff --git a/docs/sources/http_api/org.md b/docs/sources/http_api/org.md
index f2d963d7bac..d43a5e1a772 100644
--- a/docs/sources/http_api/org.md
+++ b/docs/sources/http_api/org.md
@@ -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
diff --git a/docs/sources/http_api/reporting.md b/docs/sources/http_api/reporting.md
index 09c721532ff..6ec0ae33967 100644
--- a/docs/sources/http_api/reporting.md
+++ b/docs/sources/http_api/reporting.md
@@ -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
diff --git a/docs/sources/http_api/team.md b/docs/sources/http_api/team.md
index 0a49dd99528..6cc424da599 100644
--- a/docs/sources/http_api/team.md
+++ b/docs/sources/http_api/team.md
@@ -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
diff --git a/docs/sources/http_api/user.md b/docs/sources/http_api/user.md
index 3ad19641377..1dac9150b23 100644
--- a/docs/sources/http_api/user.md
+++ b/docs/sources/http_api/user.md
@@ -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
diff --git a/docs/sources/release-notes/release-notes-8-3-0-beta1.md b/docs/sources/release-notes/release-notes-8-3-0-beta1.md
index 7e74c6d0cf8..f403070971f 100644
--- a/docs/sources/release-notes/release-notes-8-3-0-beta1.md
+++ b/docs/sources/release-notes/release-notes-8-3-0-beta1.md
@@ -10,7 +10,7 @@ list = false
### Features and enhancements
-- **AccessControl:** Apply fine-grained access control to licensing. (Enterprise)
+- **AccessControl:** Apply role-based access control to licensing. (Enterprise)
- **Alerting:** Add UI for contact point testing with custom annotations and labels. [#40491](https://github.com/grafana/grafana/pull/40491), [@nathanrodman](https://github.com/nathanrodman)
- **Alerting:** Make alert state indicator in panel header work with Grafana 8 alerts. [#38713](https://github.com/grafana/grafana/pull/38713), [@domasx2](https://github.com/domasx2)
- **Alerting:** Option for Discord notifier to use webhook name. [#40463](https://github.com/grafana/grafana/pull/40463), [@Skyebold](https://github.com/Skyebold)
diff --git a/docs/sources/whatsnew/whats-new-in-v8-0.md b/docs/sources/whatsnew/whats-new-in-v8-0.md
index 8ea19a76e9e..568699193a0 100644
--- a/docs/sources/whatsnew/whats-new-in-v8-0.md
+++ b/docs/sources/whatsnew/whats-new-in-v8-0.md
@@ -283,11 +283,11 @@ Grafana has updated its license from Apache 2.0 to the GNU Affero General Public
These features are included in the Grafana Enterprise edition.
-### Fine-grained access control
+### Role-based access control
You can now add or remove detailed permissions from Viewer, Editor, and Admin org roles, to grant users just the right amount of access within Grafana. Available permissions include the ability to view and manage Users, Reports, and the Access Control API itself. Grafana will support more and more permissions over the coming months.
-[Fine-grained access control docs]({{< relref "../enterprise/access-control/_index.md" >}}) were added as a result of this feature.
+[Role-based access control docs]({{< relref "../enterprise/access-control/_index.md" >}}) were added as a result of this feature.
### Data source query caching
diff --git a/docs/sources/whatsnew/whats-new-in-v8-1.md b/docs/sources/whatsnew/whats-new-in-v8-1.md
index 9bfcd828c2a..bd6300fbc66 100644
--- a/docs/sources/whatsnew/whats-new-in-v8-1.md
+++ b/docs/sources/whatsnew/whats-new-in-v8-1.md
@@ -135,11 +135,11 @@ We have added an experimental HA setup support for Grafana Live with Redis. This
These features are included in the Grafana Enterprise edition.
-### New permissions for fine-grained access control
+### New permissions for role-based access control
-Fine-grained access control remains in beta. You can now grant or revoke permissions for Viewers, Editors, or Admins to use Explore mode, configure LDAP or SAML settings, or view the admin/stats page. These new permissions enhance the existing permissions that can be customized, namely permissions to access Users, Orgs, LDAP settings, and Reports in Grafana.
+Role-based access control remains in beta. You can now grant or revoke permissions for Viewers, Editors, or Admins to use Explore mode, configure LDAP or SAML settings, or view the admin/stats page. These new permissions enhance the existing permissions that can be customized, namely permissions to access Users, Orgs, LDAP settings, and Reports in Grafana.
-Fine grained access control allows you to customize roles and permissions in Grafana beyond the built-in Viewer, Editor, and Admin roles. As of 8.1, you can modify some of the permissions for any of these built-in roles. This is helpful if you’d like users to have more or fewer access permissions than a given role allows for by default. For an overview of fine-grained access control and a complete list of available permissions, refer to the [Fine grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) documentation.
+Fine grained access control allows you to customize roles and permissions in Grafana beyond the built-in Viewer, Editor, and Admin roles. As of 8.1, you can modify some of the permissions for any of these built-in roles. This is helpful if you’d like users to have more or fewer access permissions than a given role allows for by default. For an overview of role-based access control and a complete list of available permissions, refer to the [Fine grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) documentation.
### New and improved reporting scheduler
diff --git a/docs/sources/whatsnew/whats-new-in-v8-2.md b/docs/sources/whatsnew/whats-new-in-v8-2.md
index 4a37020a09c..b1cd8c659cc 100644
--- a/docs/sources/whatsnew/whats-new-in-v8-2.md
+++ b/docs/sources/whatsnew/whats-new-in-v8-2.md
@@ -14,7 +14,7 @@ Grafana 8.2 continues to build on the foundation of Grafana 8.0 & 8.1. Grafana 8
The plugin catalog is now on by default in Grafana 8.2. Using the plugin catalog you can now find and install official and community plugins without having to leave or restart Grafana. We’ve also updated the time picker to include configurable fiscal quarters. This update makes it easier to use Grafana to produce reports more closely aligned with common review and forecasting cycles.
-Grafana Enterprise includes a revamped Stats and Licensing page, new fine-grained access control permissions, and improvements that make usage insights and reporting easier to access.
+Grafana Enterprise includes a revamped Stats and Licensing page, new role-based access control permissions, and improvements that make usage insights and reporting easier to access.
We’ve summarized what’s new in the release here, but you might also be interested in the announcement blog post. If you’d like all the details you can check out the [release notes](https://grafana.com/docs/grafana/next/release-notes/release-notes-8-2-0/) and complete [CHANGELOG.md](https://github.com/grafana/grafana/blob/master/CHANGELOG.md).
@@ -56,9 +56,9 @@ We’ve revamped the Stats and License sections of Grafana for administrators. T
{{< figure src="/static/img/docs/enterprise/8_2_stats_licensing_screen.png" max-width="1200px" caption="Stats and licensing" >}}
-## New fine-grained access control permissions
+## New role-based access control permissions
-Fine-grained access control now covers data source and provisioning permissions. You can decide which roles (Viewers, Editors, and Admins) can manage data sources and data source permissions in Grafana, and which roles can reload provisioning configuration for dashboards, data sources, and other provisioned resources. We’ll continue adding fine-grained access control to more Grafana services, like dashboards and API Keys, in upcoming releases. Learn more about fine-grained access control in our [release post](https://grafana.com/blog/2021/06/23/new-in-grafana-enterprise-8.0-fine-grained-access-control-for-reporting-and-user-management/) and our [docs](https://grafana.com/docs/grafana/latest/enterprise/access-control/).
+Role-based access control now covers data source and provisioning permissions. You can decide which roles (Viewers, Editors, and Admins) can manage data sources and data source permissions in Grafana, and which roles can reload provisioning configuration for dashboards, data sources, and other provisioned resources. We’ll continue adding role-based access control to more Grafana services, like dashboards and API Keys, in upcoming releases. Learn more about role-based access control in our [release post](https://grafana.com/blog/2021/06/23/new-in-grafana-enterprise-8.0-fine-grained-access-control-for-reporting-and-user-management/) and our [docs](https://grafana.com/docs/grafana/latest/enterprise/access-control/).
{{< figure src="/static/img/docs/enterprise/8_2_data_source_permissions.png" max-width="1200px" caption="Stats and licensing" >}}
@@ -70,6 +70,6 @@ Usage Insights Logs contain valuable information about user dashboard visits, qu
## Create a report from the dashboard Share dialogue
-Reports offer a powerful way to deliver insights directly to your email inboxes. Now you can create a report directly from any dashboard, using the Share button. This is especially useful when combined with fine-grained access control, which you can use to grant Editors or Viewers the ability to create reports in Grafana. To learn more, see the [reporting documentation](https://grafana.com/docs/grafana/latest/enterprise/reporting/).
+Reports offer a powerful way to deliver insights directly to your email inboxes. Now you can create a report directly from any dashboard, using the Share button. This is especially useful when combined with role-based access control, which you can use to grant Editors or Viewers the ability to create reports in Grafana. To learn more, see the [reporting documentation](https://grafana.com/docs/grafana/latest/enterprise/reporting/).
{{< figure src="/static/img/docs/enterprise/enterprise-report-from-share-8-2.png" max-width="1200px" caption="Create a report from the dashboard share dialogue" >}}
diff --git a/docs/sources/whatsnew/whats-new-in-v8-3.md b/docs/sources/whatsnew/whats-new-in-v8-3.md
index a8a15a30a5c..6d7b05e12b0 100644
--- a/docs/sources/whatsnew/whats-new-in-v8-3.md
+++ b/docs/sources/whatsnew/whats-new-in-v8-3.md
@@ -12,7 +12,7 @@ list = false
Grafana 8.3 is an exciting release for Grafana Labs. This release includes the new Candlestick Panel, a new visualization suggestions engine and, for enterprise users, Recorded Queries.
-For Open Source users it also marks the first time Grafana Alerting, formerly unified alerting, is enabled by default for new Grafana installations. Grafana Alerting in 8.3 is the flexible, single pane of glass for all your alerts. Included in this release is expanded provisioning support for notifiers, contact points, and alert rules, alongside auditing and fine-grained access control for our Enterprise customers.
+For Open Source users it also marks the first time Grafana Alerting, formerly unified alerting, is enabled by default for new Grafana installations. Grafana Alerting in 8.3 is the flexible, single pane of glass for all your alerts. Included in this release is expanded provisioning support for notifiers, contact points, and alert rules, alongside auditing and role-based access control for our Enterprise customers.
We’ve summarized what’s new in the release here, but you might also be interested in the announcement blog post as well. If you’d like all the details you can check out the complete [CHANGELOG.md](https://github.com/grafana/grafana/blob/master/CHANGELOG.md).
@@ -72,15 +72,15 @@ Recorded queries allow you to export the results of certain non-time series quer
This new feature is especially helpful for Enterprise customers using plugins because many new plugins, like ServiceNow and Jira, don’t return time series so customers weren’t able to plot historical data over time. With recorded queries, now they can! For more information
-## Assign fine-grained permissions directly to users with the new role picker (beta)
+## Assign role-based permissions directly to users with the new role picker (beta)
-Sometimes the Viewer, Editor, and Admin roles just don’t fit what a certain user needs to do in Grafana. Now you can assign fine-grained roles directly to users, so they can create reports, use Explore mode, create data sources, and perform other specific actions in Grafana. The role picker can be access from the Grafana Admin user management page.
+Sometimes the Viewer, Editor, and Admin roles just don’t fit what a certain user needs to do in Grafana. Now you can assign role-based roles directly to users, so they can create reports, use Explore mode, create data sources, and perform other specific actions in Grafana. The role picker can be access from the Grafana Admin user management page.
{{< figure src="/static/img/docs/enterprise/enterprise_role_picker_8_3.png" max-width="1200px" caption="Grafana Enterprise Role Picker" >}}
-## Use fine-grained access control for Organizations and Licensing (beta)
+## Use role-based access control for Organizations and Licensing (beta)
-We’ve added new permissions to fine-grained access control to help you specify actions that users can perform. Now you can assign permissions to manage Organizations and License functions in Grafana, in addition to Users, Data Sources, Reports, and other resources. Fine-grained access control remains in beta and we will continue to add new permissions until all of Grafana’s endpoints are covered. For a complete list of the actions you can permit using fine-grained access control, see the [reference](https://grafana.com/docs/grafana/next/enterprise/access-control/fine-grained-access-control-references/).
+We’ve added new permissions to role-based access control to help you specify actions that users can perform. Now you can assign permissions to manage Organizations and License functions in Grafana, in addition to Users, Data Sources, Reports, and other resources. Role-based access control remains in beta and we will continue to add new permissions until all of Grafana’s endpoints are covered. For a complete list of the actions you can permit using role-based access control, see the [reference](https://grafana.com/docs/grafana/next/enterprise/access-control/fine-grained-access-control-references/).
## Get your encryption key from a Key Management Service
diff --git a/docs/sources/whatsnew/whats-new-in-v8-4.md b/docs/sources/whatsnew/whats-new-in-v8-4.md
index c9d86fb8ac6..262c4729d62 100644
--- a/docs/sources/whatsnew/whats-new-in-v8-4.md
+++ b/docs/sources/whatsnew/whats-new-in-v8-4.md
@@ -105,15 +105,15 @@ The grafana server serves a [SwaggerUI](https://swagger.io/tools/swagger-ui/) ed
## Security improvements
-### Fine-grained access control works for teams
+### Role-based access control works for teams
-Occasionally, Viewer, Editor, and Admin roles don’t fit what a certain user needs to do in Grafana. Now you can assign fine-grained roles directly to users so they can create reports, use Explore mode, create data sources, and perform other specific actions in Grafana. Fine-grained access control is currently in beta.
+Occasionally, Viewer, Editor, and Admin roles don’t fit what a certain user needs to do in Grafana. Now you can assign role-based roles directly to users so they can create reports, use Explore mode, create data sources, and perform other specific actions in Grafana. Role-based access control is currently in beta.
In Grafana 8.4, you can assign roles to teams, which apply to all members of that team. This is a convenient way to grant certain permissions to a group of users all at once. It also makes permissions easier to manage when you synchronize groups from an SSO provider, like Google Oauth or Okta, to teams in Grafana.
In 8.4 you can also control access to Team and API key functionality itself, like viewing or editing API keys and adding members to certain teams.
-Enable fine-grained access control by adding the term `accesscontrol` to the list of feature toggles in your [Grafana configuration](https://grafana.com/docs/grafana/next/administration/configuration/#feature_toggles?mdm=email), or by sending a request to support if you use Grafana Cloud. Learn more about fine-grained access control in the [fine-grained access control section of the docs](https://grafana.com/docs/grafana/next/enterprise/access-control/).
+Enable role-based access control by adding the term `accesscontrol` to the list of feature toggles in your [Grafana configuration](https://grafana.com/docs/grafana/next/administration/configuration/#feature_toggles?mdm=email), or by sending a request to support if you use Grafana Cloud. Learn more about role-based access control in the [role-based access control section of the docs](https://grafana.com/docs/grafana/next/enterprise/access-control/).
{{< figure src="/static/img/docs/enterprise/8-4-fine-grain-access-control.png" max-width="1200px" caption="Assign SAML users role" >}}