DOCS Query Roles (#110473)

These are the docs changes in relation to
https://github.com/elastic/elasticsearch/pull/108733

docs/reference/rest-api/security.asciidoc

@@ -50,6 +50,7 @@ Use the following APIs to add, remove, update, and retrieve roles in the native
 * <<security-api-delete-role,Delete roles>>
 * <<security-api-bulk-delete-role, Bulk delete roles>>
 * <<security-api-get-role,Get roles>>
+* <<security-api-query-role,Query roles>>
 
 [discrete]
 [[security-token-apis]]
@@ -192,6 +193,7 @@ include::security/get-app-privileges.asciidoc[]
 include::security/get-builtin-privileges.asciidoc[]
 include::security/get-role-mappings.asciidoc[]
 include::security/get-roles.asciidoc[]
+include::security/query-role.asciidoc[]
 include::security/get-service-accounts.asciidoc[]
 include::security/get-service-credentials.asciidoc[]
 include::security/get-settings.asciidoc[]

docs/reference/rest-api/security/get-roles.asciidoc

@@ -38,7 +38,10 @@ API cannot retrieve roles that are defined in roles files.
 ==== {api-response-body-title}
 
 A successful call returns an array of roles with the JSON representation of the
-role.
+role. The returned role format is a simple extension of the <<defining-roles,role definition>> format,
+only adding an extra field `transient_metadata.enabled`.
+This field is `false` in case the role is automatically disabled, for example when the license
+level does not allow some permissions that the role grants.
 
 [[security-api-get-role-response-codes]]
 ==== {api-response-codes-title}

docs/reference/rest-api/security/query-role.asciidoc

@@ -0,0 +1,283 @@
+[role="xpack"]
+[[security-api-query-role]]
+=== Query Role API
+
+++++
+<titleabbrev>Query Role</titleabbrev>
+++++
+
+Retrieves roles with <<query-dsl,Query DSL>> in a <<paginate-search-results,paginated>> fashion.
+
+[[security-api-query-role-request]]
+==== {api-request-title}
+
+`GET /_security/_query/role`
+
+`POST /_security/_query/role`
+
+[[security-api-query-role-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have at least the  `read_security` cluster privilege.
+
+[[security-api-query-role-desc]]
+==== {api-description-title}
+
+The role management APIs are generally the preferred way to manage roles, rather than using
+<<roles-management-file,file-based role management>>.
+The query roles API does not retrieve roles that are defined in roles files, nor <<built-in-roles,built-in>> ones.
+You can optionally filter the results with a query. Also, the results can be paginated and sorted.
+
+[[security-api-query-role-request-body]]
+==== {api-request-body-title}
+
+You can specify the following parameters in the request body:
+
+`query`::
+(Optional, string) A <<query-dsl,query>> to filter which roles to return.
+The query supports a subset of query types, including
+<<query-dsl-match-all-query,`match_all`>>, <<query-dsl-bool-query,`bool`>>,
+<<query-dsl-term-query,`term`>>, <<query-dsl-terms-query,`terms`>>,
+<<query-dsl-match-query,`match`>>, <<query-dsl-ids-query,`ids`>>,
+<<query-dsl-prefix-query,`prefix`>>, <<query-dsl-wildcard-query,`wildcard`>>,
+<<query-dsl-exists-query,`exists`>>, <<query-dsl-range-query,`range`>>,
+and <<query-dsl-simple-query-string-query,`simple query string`>>.
++
+You can query the following values associated with a role.
++
+.Valid values for `query`
+[%collapsible%open]
+====
+`name`::
+(keyword) The <<security-api-put-role-path-params,name>> of the role.
+
+`description`::
+(text) The <<defining-roles,description>> of the role.
+
+`metadata`::
+(flattened) Metadata field associated with the <<defining-roles,role>>, such as `metadata.app_tag`.
+Note that metadata is internally indexed as a <<flattened,flattened>> field type.
+This means that all sub-fields act like `keyword` fields when querying and sorting.
+It also implies that it is not possible to refer to a subset of metadata fields using wildcard patterns,
+e.g. `metadata.field*`, even for query types that support field name patterns.
+Lastly, all the metadata fields can be searched together when simply mentioning the
+`metadata` field (i.e. not followed by any dot and sub-field name).
+
+`applications`::
+The list of <<roles-application-priv,application privileges>> that the role grants.
+
+`application`:::
+(keyword) The name of the application associated to the privileges and resources.
+
+`privileges`:::
+(keyword) The names of the privileges that the role grants.
+
+`resources`:::
+(keyword) The resources to which the privileges apply.
+
+====
+
+include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=from]
++
+By default, you cannot page through more than 10,000 hits using the `from` and
+`size` parameters. To page through more hits, use the
+<<search-after,`search_after`>> parameter.
+
+`size`::
+(Optional, integer) The number of hits to return. Must not be negative and defaults to `10`.
++
+By default, you cannot page through more than 10,000 hits using the `from` and
+`size` parameters. To page through more hits, use the
+<<search-after,`search_after`>> parameter.
+
+`sort`::
+(Optional, object) <<sort-search-results,Sort definition>>. You can sort on `username`, `roles` or `enabled`.
+In addition, sort can also be applied to the `_doc` field to sort by index order.
+
+`search_after`::
+(Optional, array) <<search-after,Search after>> definition.
+
+
+[[security-api-query-role-response-body]]
+==== {api-response-body-title}
+
+This API returns the following top level fields:
+
+`total`::
+The total number of roles found.
+
+`count`::
+The number of roles returned in the response.
+
+`roles`::
+A list of roles that match the query.
+The returned role format is an extension of the <<defining-roles,role definition>> format.
+It adds the `transient_metadata.enabled` and the `_sort` fields.
+`transient_metadata.enabled` is set to `false` in case the role is automatically disabled,
+for example when the role grants privileges that are not allowed by the installed license.
+`_sort` is present when the search query sorts on some field.
+It contains the array of values that have been used for sorting.
+
+[[security-api-query-role-example]]
+==== {api-examples-title}
+
+The following request lists all roles, sorted by the role name:
+
+[source,console]
+----
+POST /_security/_query/role
+{
+    "sort": ["name"]
+}
+----
+// TEST[setup:admin_role,user_role]
+
+A successful call returns a JSON structure that contains the information
+retrieved for one or more roles:
+
+[source,console-result]
+----
+{
+    "total": 2,
+    "count": 2,
+    "roles": [ <1>
+        {
+          "name" : "my_admin_role",
+          "cluster" : [
+            "all"
+          ],
+          "indices" : [
+            {
+              "names" : [
+                "index1",
+                "index2"
+              ],
+              "privileges" : [
+                "all"
+              ],
+              "field_security" : {
+                "grant" : [
+                  "title",
+                  "body"
+                ]
+              },
+              "allow_restricted_indices" : false
+            }
+          ],
+          "applications" : [ ],
+          "run_as" : [
+            "other_user"
+          ],
+          "metadata" : {
+            "version" : 1
+          },
+          "transient_metadata" : {
+            "enabled" : true
+          },
+          "description" : "Grants full access to all management features within the cluster.",
+          "_sort" : [
+            "my_admin_role"
+          ]
+        },
+        {
+          "name" : "my_user_role",
+          "cluster" : [ ],
+          "indices" : [
+            {
+              "names" : [
+                "index1",
+                "index2"
+              ],
+              "privileges" : [
+                "all"
+              ],
+              "field_security" : {
+                "grant" : [
+                  "title",
+                  "body"
+                ]
+              },
+              "allow_restricted_indices" : false
+            }
+          ],
+          "applications" : [ ],
+          "run_as" : [ ],
+          "metadata" : {
+            "version" : 1
+          },
+          "transient_metadata" : {
+            "enabled" : true
+          },
+          "description" : "Grants user access to some indicies.",
+          "_sort" : [
+            "my_user_role"
+          ]
+        }
+    ]
+}
+----
+// TEST[continued]
+
+<1> The list of roles that were retrieved for this request
+
+Similarly, the following request can be used to query only the user access role,
+given its description:
+
+[source,console]
+----
+POST /_security/_query/role
+{
+  "query": {
+    "match": {
+      "description": {
+        "query": "user access"
+      }
+    }
+  },
+  "size": 1 <1>
+}
+----
+// TEST[continued]
+
+<1> Return only the best matching role
+
+[source,console-result]
+----
+{
+    "total": 2,
+    "count": 1,
+    "roles": [
+        {
+          "name" : "my_user_role",
+          "cluster" : [ ],
+          "indices" : [
+            {
+              "names" : [
+                "index1",
+                "index2"
+              ],
+              "privileges" : [
+                "all"
+              ],
+              "field_security" : {
+                "grant" : [
+                  "title",
+                  "body"
+                ]
+              },
+              "allow_restricted_indices" : false
+            }
+          ],
+          "applications" : [ ],
+          "run_as" : [ ],
+          "metadata" : {
+            "version" : 1
+          },
+          "transient_metadata" : {
+            "enabled" : true
+          },
+          "description" : "Grants user access to some indicies."
+        }
+    ]
+}
+----

docs/reference/rest-api/security/query-user.asciidoc

@@ -66,13 +66,6 @@ The email of the user.
 Specifies whether the user is enabled.
 ====
 
-[[security-api-query-user-query-params]]
-==== {api-query-parms-title}
-
-`with_profile_uid`::
-(Optional, boolean) Determines whether to retrieve the <<user-profile,user profile>> `uid`,
-if exists, for the users. Defaults to `false`.
-
 include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=from]
 +
 By default, you cannot page through more than 10,000 hits using the `from` and
@@ -93,6 +86,12 @@ In addition, sort can also be applied to the `_doc` field to sort by index order
 `search_after`::
 (Optional, array) <<search-after,Search after>> definition.
 
+[[security-api-query-user-query-params]]
+==== {api-query-parms-title}
+
+`with_profile_uid`::
+(Optional, boolean) Determines whether to retrieve the <<user-profile,user profile>> `uid`,
+if exists, for the users. Defaults to `false`.
 
 [[security-api-query-user-response-body]]
 ==== {api-response-body-title}
@@ -191,7 +190,7 @@ Use the user information retrieve the user with a query:
 
 [source,console]
 ----
-GET /_security/_query/user
+POST /_security/_query/user
 {
     "query": {
         "prefix": {
@@ -231,7 +230,7 @@ To retrieve the user `profile_uid` as part of the response:
 
 [source,console]
 --------------------------------------------------
-GET /_security/_query/user?with_profile_uid=true
+POST /_security/_query/user?with_profile_uid=true
 {
     "query": {
         "prefix": {
@@ -272,7 +271,7 @@ Use a `bool` query to issue complex logical conditions and use
 
 [source,js]
 ----
-GET /_security/_query/user
+POST /_security/_query/user
 {
   "query": {
     "bool": {

docs/reference/security/authorization/managing-roles.asciidoc

@@ -13,7 +13,9 @@ A role is defined by the following JSON structure:
   "indices": [ ... ], <4>
   "applications": [ ... ], <5>
   "remote_indices": [ ... ], <6>
-  "remote_cluster": [ ... ] <7>
+  "remote_cluster": [ ... ], <7>
+  "metadata": { ... }, <8>
+  "description": "..." <9>
 }
 -----
 // NOTCONSOLE
@@ -40,6 +42,16 @@ A role is defined by the following JSON structure:
     <<remote-clusters-api-key,remote clusters configured with the API key based model>>.
     This field is optional (missing `remote_cluster` privileges effectively means
     no additional cluster permissions for any API key based remote clusters).
+<8> Metadata field associated with the role, such as `metadata.app_tag`.
+    Metadata is internally indexed as a <<flattened,flattened>> field type.
+    This means that all sub-fields act like `keyword` fields when querying and sorting.
+    Metadata values can be simple values, but also lists and maps.
+    This field is optional.
+<9> A string value with the description text of the role.
+    The maximum length of it is `1000` chars.
+    The field is internally indexed as a <<text-field-type,text>> field type
+    (with default values for all parameters).
+    This field is optional.
 
 [[valid-role-name]]
 NOTE: Role names must be at least 1 and no more than 507 characters. They can