Docs: Update Permissions documentation (#28144)

* removed overview.md

* content updates

* Update datasource_permissions.md

* update content

* content updates

* Update organization_roles.md

* Update docs/sources/enterprise/saml.md

Co-authored-by: Kyle Brandt <kyle@grafana.com>

* Update dashboard_folder_permissions.md

Co-authored-by: Kyle Brandt <kyle@grafana.com>

docs/sources/enterprise/saml.md

@@ -139,7 +139,7 @@ To use SAML Team sync, set [`assertion_attribute_groups`]({{< relref "./enterpri
 
 > Only available in Grafana v7.0+
 
-Role sync allows you to map user roles from an identity provider to Grafana. To enable role sync, configure role attribute and possible values for [Editor]({{< relref "../permissions/organization_roles.md#editor-role" >}}), [Admin]({{< relref "../permissions/organization_roles.md#admin-role" >}}) and [Grafana Admin]({{< relref "../permissions/overview.md#grafana-admin" >}}) roles.
+Role sync allows you to map user roles from an identity provider to Grafana. To enable role sync, configure role attribute and possible values for the [Editor]({{< relref "../permissions/organization_roles.md#editor-role" >}}), [Admin]({{< relref "../permissions/organization_roles.md#admin-role" >}}) and [Grafana Admin]({{< relref "../permissions/_index.md#grafana-admin" >}}) roles.
 
 1. In the configuration file, set [`assertion_attribute_role`]({{< relref "./enterprise-configuration.md#assertion-attribute-role" >}}) option to the attribute name where the role information will be extracted from.
 1. Set the [`role_values_editor`]({{< relref "./enterprise-configuration.md#role-values-editor" >}}) option to the values mapped to the `Editor` role.

docs/sources/getting-started/getting-started.md

@@ -56,6 +56,6 @@ Administrators might want to learn about:
 
 - [Grafana configuration]({{< relref "../administration/configuration.md" >}})
 - [Authentication]({{< relref "../auth/overview.md" >}})
-- [User permissions and roles]({{< relref "../permissions/overview.md" >}})
+- [User permissions and roles]({{< relref "../permissions/_index.md" >}})
 - [Provisioning]({{< relref "../administration/provisioning.md" >}})
 - [Grafana CLI]({{< relref "../administration/cli.md" >}})

docs/sources/getting-started/what-is-grafana.md

@@ -77,7 +77,7 @@ Refer to [Provisioning]({{< relref "../administration/provisioning.md" >}}) for
 
 ## Permissions
 
-When organizations have one Grafana and multiple teams, they often want the ability to both keep things separate and share dashboards. You can create a team of users and then set [permissions]({{< relref "../permissions/overview.md" >}}) on folders, dashboards, and down to the [data source level]({{< relref "../enterprise/datasource_permissions.md" >}}) if you're using [Grafana Enterprise]({{< relref "../enterprise/_index.md" >}}).
+When organizations have one Grafana and multiple teams, they often want the ability to both keep things separate and share dashboards. You can create a team of users and then set [permissions]({{< relref "../permissions/_index.md" >}}) on folders, dashboards, and down to the [data source level]({{< relref "../enterprise/datasource_permissions.md" >}}) if you're using [Grafana Enterprise]({{< relref "../enterprise/_index.md" >}}).
 
 ## Grafana Cloud
 

docs/sources/manage-users/_index.md

@@ -9,7 +9,7 @@ weight = 40
 
 # Manage users
 
-Create users and teams and configure [Permissions]({{< relref "../permissions/overview.md" >}}) to make sure that users only have access to the resources they need.
+Create users and teams and configure [Permissions]({{< relref "../permissions/_index.md" >}}) to make sure that users only have access to the resources they need.
 
 Only Administrators can manage users and teams.
 

docs/sources/menu.yaml

@@ -92,7 +92,7 @@
     - name: Permissions
       link: /permissions/
       children:
-        - link: /permissions/overview/
+        - link: /permissions/
           name: Overview
         - link: /permissions/organization_roles/
           name: Organization Roles

docs/sources/permissions/_index.md

@@ -3,54 +3,50 @@ title = "Permissions"
 description = "Permissions"
 keywords = ["grafana", "configuration", "documentation", "admin", "users", "datasources", "permissions"]
 type = "docs"
+aliases = ["/docs/grafana/latest/permissions/overview/"]
 [menu.docs]
 name = "Permissions"
 identifier = "permissions"
-parent = "admin"
+weight = 50
-weight = 3
 +++
 
-# Permissions overview
+# Permissions
 
-Grafana users have permissions that are determined by their:
+What you can do in Grafana is defined by the _permissions_ associated with your user account.
 
-- **Organization Role** (Admin, Editor, Viewer)
+There are three types of permissions:
-- Via **Team** memberships where the **Team** has been assigned specific permissions.
+- Permissions granted as a Grafana server admin
-- Via permissions assigned directly to user (on folders, dashboards, data sources)
+- Permissions associated with your role in an organization
-- The Grafana Admin (i.e. Super Admin) user flag.
+- Permissions granted to a specific folder or dashboard
 
-## Users
+You can be granted permissions based on:
+- Grafana server admin status
+- Organization role (Admin, Editor, or Viewer)
+- Folder or dashboard permissions assigned to your team (Admin, Editor, or Viewer)
+- Folder or dashboard permissions assigned to your user account (Admin, Editor, or Viewer)
+- (Grafana Enterprise) Data source permissions. For more information, refer to [Data source permissions]({{< relref "../enterprise/datasource_permissions.md" >}}) in [Grafana Enterprise]({{< relref "../enterprise" >}}).
 
-Grafana supports a wide variety of internal and external ways for users to authenticate themselves. These include from its own integrated database, from an external SQL server, or from an external LDAP server.
+## Grafana server admin
 
-## Grafana Admin
+Grafana server admins have the **Grafana Admin** flag enabled on their account. They can access the **Server Admin** menu and perform the following tasks:
 
-This admin flag makes user a `Super Admin`. This means they can access the `Server Admin` views where all users and organizations can be administrated.
+- Manage users and permissions.
+- Create, edit, and delete organizations.
+- View server-wide settings that are set in the [Configuration]({{< relref "../administration/configuration.md" >}}) file.
+- View Grafana server stats, including total users and active sessions.
+- Upgrade the server to Grafana Enterprise.
 
-## Organization Roles
+## Organization roles
 
-Users can belong to one or more organizations. A user's organization membership is tied to a role that defines what the user is allowed to do
+Users can belong to one or more organizations. A user's organization membership is tied to a role that defines what the user is allowed to do in that organization. For more information, refer to [Organization roles]({{< relref "../permissions/organization_roles.md" >}}).
-in that organization. Grafana supports multiple *organizations* in order to support a wide variety of deployment models, including using a single Grafana instance to provide service to multiple potentially untrusted organizations.
 
-In most cases, Grafana is deployed with a single organization.
+## Dashboard and folder permissions
 
-Each organization can have one or more data sources.
+Dashboard and folder permissions allow you to remove the default role based permissions for Editors and Viewers and assign permissions to specific users and teams. Learn more about [Dashboard and folder permissions]({{< relref "dashboard_folder_permissions.md" >}}).
-
-All dashboards are owned by a particular organization.
-
- > **Note:** Most metric databases do not provide per-user series authentication. This means that organization data sources and dashboards are available to all users in a particular organization.
-
-Refer to [Organization roles]({{< relref "../permissions/organization_roles.md" >}}) for more information.
-
-
-## Dashboard and Folder Permissions
-
-Dashboard and folder permissions allow you to remove the default role based permissions for Editors and Viewers and assign permissions to specific **Users** and **Teams**. Learn more about [Dashboard and Folder Permissions]({{< relref "dashboard_folder_permissions.md" >}}).
 
 ## Data source permissions
 
 Per default, a data source in an organization can be queried by any user in that organization. For example a user with `Viewer` role can still
 issue any possible query to a data source, not just those queries that exist on dashboards he/she has access to.
 
-Data source permissions allows you to change the default permissions for data sources and restrict query permissions to specific **Users** and **Teams**. Read more about [data source permissions]({{< relref "datasource_permissions.md" >}}).
+Data source permissions allows you to change the default permissions for data sources and restrict query permissions to specific **Users** and **Teams**. For more information, refer to [Data source permissions]({{< relref "../enterprise/datasource_permissions.md" >}}) in [Grafana Enterprise]({{< relref "../enterprise" >}}).
-

docs/sources/permissions/dashboard_folder_permissions.md

@@ -7,7 +7,7 @@ type = "docs"
 name = "Dashboard and Folder"
 identifier = "dashboard-folder-permissions"
 parent = "permissions"
-weight = 40
+weight = 200
 +++
 
 # Dashboard and Folder Permissions
@@ -25,11 +25,30 @@ Permission levels:
 - **Edit**: Can edit and create dashboards. **Cannot** edit folder/dashboard permissions, or add, edit, or delete folders.
 - **View**: Can only view existing dashboards/folders.
 
+## Grant folder permissions
+
+1. In the sidebar, hover your mouse over the **Dashboards** (squares) icon and then click **Manage**.
+1. Hover your mouse cursor over a folder and then click **Go to folder**.
+1. Go to the **Permissions** tab, and then click **Add Permission**.
+1. In the **Add Permission For** dialog, select **User**, **Team**, or one of the role options.
+1. In the second box, select the user or team to add permission for. Skip this step if you selected a role option in the previous step.
+1. In the third box, select the permission you want to add.
+1. Click **Save**.
+
+## Grant dashboard permissions
+
+1. In the top right corner of your dashboard, click the cog icon to go to **Dashboard settings**.
+1. Go to the **Permissions** tab, and then click **Add Permission**.
+1. In the **Add Permission For** dialog, select **User**, **Team**, or one of the role options.
+1. In the second box, select the user or team to add permission for. Skip this step if you selected a role option in the previous step.
+1. In the third box, select the permission you want to add.
+1. Click **Save**.
+
 ## Restricting Access
 
 The highest permission always wins so if you for example want to hide a folder or dashboard from others you need to remove the **Organization Role** based permission from the Access Control List (ACL).
 
-- You cannot override permissions for users with the **Org Admin Role**. Admins always have access to everything.
+- You cannot override permissions for users with the Organization Admin role. Admins always have access to everything.
 - A more specific permission with a lower permission level will not have any effect if a more general rule exists with higher permission level. You need to remove or lower the permission level of the more general rule.
 
 ### How Grafana Resolves Multiple Permissions - Examples
@@ -38,8 +57,8 @@ The highest permission always wins so if you for example want to hide a folder o
 
 Permissions for a dashboard:
 
-- `Everyone with Editor Role Can Edit`
+- Everyone with Editor role can edit
-- `user1 Can View`
+- user1 can view
 
 Result: `user1` has Edit permission as the highest permission always wins.
 
@@ -62,12 +81,9 @@ Permissions for a dashboard:
 
 Result: You cannot override to a lower permission. `user1` has Admin permission as the highest permission always wins.
 
-## Summary
+### Summary
 
 - **View**: Can only view existing dashboards/folders.
-- You cannot override permissions for users with **Org Admin Role**
 - A more specific permission with lower permission level will not have any effect if a more general rule exists with higher permission level.
 
 For example if "Everyone with Editor Role Can Edit" exists in the ACL list then **John Doe** will still have Edit permission even after you have specifically added a permission for this user with the permission set to **View**. You need to remove or lower the permission level of the more general rule.
-- You cannot override permissions for users with **Org Admin Role**
-- A more specific permission with lower permission level will not have any effect if a more general rule exists with higher permission level. For example if "Everyone with Editor Role Can Edit" exists in the ACL list then **John Doe** will still have Edit permission even after you have specifically added a permission for this user with the permission set to **View**. You need to remove or lower the permission level of the more general rule.

docs/sources/permissions/datasource_permissions.md

@@ -7,11 +7,11 @@ type = "docs"
 name = "Datasource"
 identifier = "datasource-permissions"
 parent = "permissions"
-weight = 50
+weight = 900
 +++
 
 # Data source permissions
 
-Data source permissions allow you to restrict access for users to query a data source. For each data source there is a permission page that allows you to enable permissions and restrict query permissions to specific **Users** and **Teams**.
+Data source permissions allow you to restrict access for users to query a data source. For each data source there is a permission page that allows you to enable permissions and restrict query permissions to specific users and teams.
 
-> Data source permissions are only available in Grafana Enterprise. For more information, refer to [Data source permissions]({{< relref "../enterprise/datasource_permissions.md" >}}) in [Grafana Enterprise]({{< relref "../enterprise" >}}).
+> **Note:** Data source permissions are only available in Grafana Enterprise. For more information, refer to [Data source permissions]({{< relref "../enterprise/datasource_permissions.md" >}}) in [Grafana Enterprise]({{< relref "../enterprise" >}}).

docs/sources/permissions/grant-dashboard-and-folder-permissions.md

@@ -1,32 +0,0 @@
-+++
-title = "Grant dashboard and folder permissions"
-keywords = ["grafana", "configuration", "documentation", "dashboard", "folder", "permissions", "teams"]
-type = "docs"
-[menu.docs]
-identifier = "grant-dashboard-and-folder-permissions"
-parent = "permissions"
-weight = 10
-+++
-
-# Grant dashboard and folder permissions
-
-Grant permission to dashboards and folders to control who can access them.
-
-## Grant folder permissions
-
-1. In the sidebar, hover your mouse over the **Dashboards** (squares) icon and then click **Manage**.
-1. Hover your mouse cursor over a folder and click the gear icon to the right.
-1. Go to the **Permissions** tab, and then click **Add Permission**.
-1. In the **Add Permission For** dialog, select **User** or **Team**.
-1. In the second box, select the user or team to add permission for.
-1. In the third box, select the permission you want to add.
-1. Click **Save**.
-
-## Grant dashboard permissions
-
-1. In the top right corner of your dashboard, click the cog icon to go to **Dashboard settings**.
-1. Go to the **Permissions** tab, and click **Add Permission**.
-1. In the **Add Permission For** dialog, select **User** or **Team**.
-1. In the second box, select the user or team to add permission for.
-1. In the third box, select the permission you want to add.
-1. Click **Save**.

docs/sources/permissions/organization_roles.md

@@ -7,21 +7,28 @@ type = "docs"
 name = "Organization Roles"
 identifier = "organization-roles"
 parent = "permissions"
-weight = 30
+weight = 100
 +++
 
 # Organization roles
 
-Users can belong to one or more organizations. A user's organization membership is tied to a role that defines what the user is allowed to do
+Users can belong to one or more organizations. A user's organization membership is tied to a role that defines what the user is allowed to do in that organization. Grafana supports multiple _organizations_ in order to support a wide variety of deployment models, including using a single Grafana instance to provide service to multiple potentially untrusted organizations.
-in that organization.
 
-## Admin role
+In most cases, Grafana is deployed with a single organization.
+
+Each organization can have one or more data sources.
+
+All dashboards are owned by a particular organization.
+
+ > **Note:** Most metric databases do not provide per-user series authentication. This means that organization data sources and dashboards are available to all users in a particular organization.
+
+## Organization admin role
 
 Can do everything scoped to the organization. For example:
 
 - Can add, edit, and delete data sources.
-- Can add and edit users and teams in organizations.
+- Can add and edit users and teams in their organization.
-- Can add, edit, and delete folders.
+- Can add, edit, and delete folders containing dashboards for data sources associated with their organization.
 - Can configure app plugins and organization settings.
 - Can do everything allowed by the Editor role.
 
@@ -34,8 +41,7 @@ Can do everything scoped to the organization. For example:
 - Cannot add, edit, or delete alert notification channels.
 - Cannot manage other organizations, users, and teams.
 
-This role can be tweaked via Grafana server setting [editors_can_admin]({{< relref "../administration/configuration.md#editors_can_admin" >}}). If you set this to `true`, then users
+This role can be changed with the Grafana server setting [editors_can_admin]({{< relref "../administration/configuration.md#editors_can_admin" >}}). If you set this to `true`, then users with the Editor role can also administrate dashboards, folders and teams they create. This is especially useful for enabling self-organizing teams to administer their own dashboards.
-with the Editor role can also administrate dashboards, folders and teams they create. This is especially useful for enabling self-organizing teams to administer their own dashboards.
 
 ## Viewer role
 
@@ -47,6 +53,5 @@ with the Editor role can also administrate dashboards, folders and teams they cr
 - Cannot access Explore.
 - Cannot manage other organizations, users, and teams.
 
-This role can be tweaked via Grafana server setting [viewers_can_edit]({{< relref "../administration/configuration.md#viewers-can-edit" >}}). If you set this to `true`, then users
+This role can be changed with the Grafana server setting [viewers_can_edit]({{< relref "../administration/configuration.md#viewers-can-edit" >}}). If you set this to `true`, then users with the Viewer role can also make transient dashboard edits, meaning they can modify panels and queries but not save the changes (nor create new dashboards).
-with the Viewer role can also make transient dashboard edits, meaning they can modify panels and queries but not save the changes (nor create new dashboards).
 This is especially useful for public Grafana installations where you want anonymous users to be able to edit panels and queries but not save or create new dashboards.

docs/sources/permissions/overview.md

@@ -1,56 +0,0 @@
-+++
-title = "Overview"
-description = "Overview for permissions"
-keywords = ["grafana", "configuration", "documentation", "admin", "users", "datasources", "permissions"]
-type = "docs"
-aliases = ["/docs/grafana/latest/reference/admin", "/docs/grafana/latest/administration/permissions/"]
-[menu.docs]
-name = "Overview"
-identifier = "overview-permissions"
-parent = "permissions"
-weight = 1
-+++
-
-# Permissions Overview
-
-Grafana users have permissions that are determined by their:
-
-- **Organization Role** (Admin, Editor, Viewer)
-- Via **Team** memberships where the **Team** has been assigned specific permissions.
-- Via permissions assigned directly to user (on folders, dashboards, data sources)
-- The Grafana Admin (i.e. Super Admin) user flag.
-
-## Users
-
-Grafana supports a wide variety of internal and external ways for users to authenticate themselves. These include from its own integrated database, from an external SQL server, or from an external LDAP server.
-
-## Grafana Admin
-
-This admin flag makes user a `Super Admin`. This means they can access the `Server Admin` views where all users and organizations can be administrated.
-
-## Organization Roles
-
-Users can belong to one or more organizations. A user's organization membership is tied to a role that defines what the user is allowed to do
-in that organization. Grafana supports multiple *organizations* in order to support a wide variety of deployment models, including using a single Grafana instance to provide service to multiple potentially untrusted organizations.
-
-In most cases, Grafana is deployed with a single organization.
-
-Each organization can have one or more data sources.
-
-All dashboards are owned by a particular organization.
-
- > **Note:** Most metric databases do not provide per-user series authentication. This means that organization data sources and dashboards are available to all users in a particular organization.
-
-Refer to [Organization roles]({{< relref "../permissions/organization_roles.md" >}}) for more information.
-
-
-## Dashboard and Folder Permissions
-
-Dashboard and folder permissions allow you to remove the default role based permissions for Editors and Viewers and assign permissions to specific **Users** and **Teams**. Learn more about [Dashboard and Folder Permissions]({{< relref "dashboard_folder_permissions.md" >}}).
-
-## Data source permissions
-
-Per default, a data source in an organization can be queried by any user in that organization. For example a user with `Viewer` role can still
-issue any possible query to a data source, not just those queries that exist on dashboards he/she has access to.
-
-Data source permissions allows you to change the default permissions for data sources and restrict query permissions to specific **Users** and **Teams**. Read more about [data source permissions]({{< relref "../enterprise/datasource_permissions.md" >}}).