Access control: allow hiding roles (#46358)

* allow hiding roles

* extend docs

* docs feedback

* extend provisioning docs

* formatting

Co-authored-by: Leonard Gram <leo@xlson.com>

docs/sources/enterprise/access-control/provisioning.md

@@ -50,7 +50,8 @@ roles:
         scope: 'users:*'
 ```
 
-Here is an example YAML file to create a global role with a set of permissions, where the `global:true` option makes a role global:
+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
@@ -62,6 +63,7 @@ roles:
     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:*'

docs/sources/http_api/access_control.md

@@ -64,6 +64,10 @@ Gets all existing roles. The response contains all global and organization local
 Query Parameters:
 
 - `includeHidden`: Optional. Set to `true` to include roles that are `hidden`.
+
+#### Required permissions
+
+| Action     | Scope    |
 | ---------- | -------- |
 | roles:list | roles:\* |
 
@@ -258,6 +262,7 @@ Content-Type: application/json
 | 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 | List of Permissions | No       | The full list of permissions for the role after the update.                                                                                                                      |
 
 **Permission**
 
@@ -350,13 +355,14 @@ Content-Type: application/json
 
 #### Example request
 
-#### Example response
+```http
 GET /api/access-control/users/1/roles
 Accept: application/json
 ```
 
 #### Example response
-```
+
+```http
 HTTP/1.1 200 OK
 Content-Type: application/json; charset=UTF-8
 
@@ -466,6 +472,10 @@ Content-Type: application/json; charset=UTF-8
 
 Revoke a role from a user.
 
+For bulk updates consider
+[Set user role assignments]({{< ref "#set-user-role-assignments" >}}).
+
+#### Required permissions
 
 `permission:delegate` scope ensures that users can only unassign roles which have same, or a subset of permissions which the user has.
 For example, if a user does not have required permissions for creating users, they won't be able to unassign a role which will allow to do that. This is done to prevent escalation of privileges.
@@ -703,9 +713,10 @@ Content-Type: application/json
 | 403  | Access denied.                                                       |
 | 500  | Unexpected error. Refer to body and/or server logs for more details. |
 
-This will remove any assigned roles that aren't in the request and add
+### Set team role assignments
 
 `PUT /api/access-control/teams/:teamId/roles`
+
 Update the team's role assignments to match the provided set of UIDs.
 This will remove any assigned roles that aren't in the request and add
 roles that are in the set but are not already assigned to the user.
@@ -735,6 +746,10 @@ Content-Type: application/json; charset=UTF-8
 {
     "roleUids": [
         "ZiHQJq5nk",
+        "GzNQ1357k"
+    ]
+}
+```
 
 #### JSON body schema
 
@@ -832,7 +847,7 @@ Content-Type: application/json; charset=UTF-8
             "created": "2021-05-13T16:24:26+02:00"
         }
     ]
-| Code | Description                                                          |
+}
 ```
 
 #### Status codes
@@ -916,8 +931,9 @@ Content-Type: application/json
 | -------------------- | -------------------- |
 | roles.builtin:remove | permissions:delegate |
 
-```
+#### Example request
 
+```http
 DELETE /api/access-control/builtin-roles/Grafana%20Admin/roles/LPMGN99Mk?global=false
 Accept: application/json
 ```
@@ -949,6 +965,10 @@ API set allows to create or remove [built-in role assignments]({{< relref "../en
 | 404  | Role not found.                                                                    |
 | 500  | Unexpected error. Refer to body and/or server logs for more details.               |
 
+Query Parameters:
+
+- `includeHidden`: Optional. Set to `true` to include roles that are `hidden`.
+
 #### Required permissions
 
 | Action             | Scope    |

pkg/services/accesscontrol/models.go

@@ -23,6 +23,7 @@ type Role struct {
 	DisplayName string `json:"displayName"`
 	Group       string `xorm:"group_name" json:"group"`
 	Description string `json:"description"`
+	Hidden      bool   `json:"hidden"`
 
 	Updated time.Time `json:"updated"`
 	Created time.Time `json:"created"`
@@ -65,6 +66,7 @@ type RoleDTO struct {
 	Group       string       `xorm:"group_name" json:"group"`
 	Permissions []Permission `json:"permissions,omitempty"`
 	Delegatable *bool        `json:"delegatable,omitempty"`
+	Hidden      bool         `json:"hidden,omitempty"`
 
 	ID    int64 `json:"-" xorm:"pk autoincr 'id'"`
 	OrgID int64 `json:"-" xorm:"org_id"`
@@ -82,6 +84,7 @@ func (r RoleDTO) Role() Role {
 		DisplayName: r.DisplayName,
 		Group:       r.Group,
 		Description: r.Description,
+		Hidden:      r.Hidden,
 		Updated:     r.Updated,
 		Created:     r.Created,
 	}

pkg/services/sqlstore/migrations/accesscontrol/migrations.go

@@ -162,4 +162,8 @@ func AddMigration(mg *migrator.Migrator) {
 
 	//-------  indexes ------------------
 	mg.AddMigration("add unique index builtin_role_role_name", migrator.NewAddIndexMigration(seedAssignmentV1, seedAssignmentV1.Indices[0]))
+
+	mg.AddMigration("add column hidden to role table", migrator.NewAddColumnMigration(roleV1, &migrator.Column{
+		Name: "hidden", Type: migrator.DB_Bool, Nullable: false, Default: "0",
+	}))
 }