Query Roles docs

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

@@ -0,0 +1,114 @@
+[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.
+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`::
+The <<security-api-put-role-path-params,name>> of the role, which is internally indexed as a keyword.
+
+`description`::
+The <<defining-roles,description>> of the role, which is internally indexed as a text.
+
+`metadata`::
+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.
+These are all internally indexed as keywords.
+
+`application`:::
+The name of the application associated to the privileges and resources.
+
+`privileges`:::
+The names of the privileges that the role grants.
+
+`resources`:::
+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.

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}

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