Add documentation for Query User API (#104255)

* Add documentation for Query User API

Co-authored-by: Nikolaj Volgushev <n1v0lg@users.noreply.github.com>

docs/build.gradle

@@ -1787,6 +1787,28 @@ setups['setup-snapshots'] = setups['setup-repository'] + '''
             "username": "jacknich",
             "password" : "l0ng-r4nd0m-p@ssw0rd"
           }
+'''
+  setups['sandrakn_user'] = '''
+  - do:
+      security.put_user:
+        username: "sandrakn"
+        body:  >
+          {
+            "password" : "l0ng-r4nd0m-p@ssw0rd",
+            "roles" : [ "admin", "other_role1" ],
+            "full_name" : "Sandra Knight",
+            "email" : "sandrakn@example.com",
+            "metadata" : { "intelligence" : 7 }
+          }
+  - do:
+      security.activate_user_profile:
+        body: >
+          {
+            "grant_type": "password",
+            "username": "sandrakn",
+            "password" : "l0ng-r4nd0m-p@ssw0rd"
+          }
+
 '''
   setups['app0102_privileges'] = '''
   - do:

docs/reference/rest-api/security.asciidoc

@@ -95,6 +95,7 @@ native realm:
 * <<security-api-disable-user,Disable users>>
 * <<security-api-enable-user,Enable users>>
 * <<security-api-get-user,Get users>>
+* <<security-api-query-user,Query users>>
 
 [discrete]
 [[security-service-account-apis]]
@@ -199,6 +200,7 @@ include::security/oidc-prepare-authentication-api.asciidoc[]
 include::security/oidc-authenticate-api.asciidoc[]
 include::security/oidc-logout-api.asciidoc[]
 include::security/query-api-key.asciidoc[]
+include::security/query-user.asciidoc[]
 include::security/update-api-key.asciidoc[]
 include::security/bulk-update-api-keys.asciidoc[]
 include::security/saml-prepare-authentication-api.asciidoc[]

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

@@ -0,0 +1,310 @@
+[role="xpack"]
+[[security-api-query-user]]
+=== Query User API
+
+++++
+<titleabbrev>Query User</titleabbrev>
+++++
+
+Retrieves <<native-realm,native users>> with <<query-dsl,Query DSL>> in a <<paginate-search-results,paginated>> fashion.
+
+NOTE: As opposed to the <<security-api-get-user,get user api>>, <<built-in-users,built-in users>> are excluded from the
+result. This API is only for <<native-realm,native users>>.
+
+[[security-api-query-user-request]]
+==== {api-request-title}
+
+`GET /_security/_query/user`
+
+`POST /_security/_query/user`
+
+[[security-api-query-user-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have at least the  `read_security` cluster privilege.
+
+[[security-api-query-user-desc]]
+==== {api-description-title}
+
+Use this API to retrieve users managed by the
+<<native-realm,native realm>> in a paginated manner.
+You can optionally filter the results with a query.
+
+[[security-api-query-user-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 users 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-prefix-query,`prefix`>>, <<query-dsl-wildcard-query,`wildcard`>> and <<query-dsl-exists-query,`exists`>>.
++
+You can query the following public values associated with a user.
++
+.Valid values for `query`
+[%collapsible%open]
+====
+`username`::
+An identifier for the user.
+
+`roles`::
+An array of the role names of the <<defining-roles, roles>> that are assigned to the user.
+
+`full_name`::
+Full name of the user.
+
+`email`::
+The email of the user.
+
+`enabled`::
+Specifies whether the user is enabled.
+
+====
+
+include::{es-repo-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-user-response-body]]
+==== {api-response-body-title}
+
+This API returns the following top level fields:
+
+`total`::
+The total number of users found.
+
+`count`::
+The number of users returned in the response.
+
+`users`::
+A list of users that match the query.
+
+[[security-api-query-user-example]]
+==== {api-examples-title}
+
+The following request lists all users, assuming you have the
+`read_security` privilege:
+
+[source,console]
+----
+GET /_security/_query/user
+----
+// TEST[setup:jacknich_user,sandrakn_user]
+
+A successful call returns a JSON structure that contains the information
+retrieved from one or more users:
+
+[source,console-result]
+----
+{
+    "total": 2,
+    "count": 2,
+    "users": [ <1>
+        {
+            "username": "jacknich",
+            "roles": [
+                "admin",
+                "other_role1"
+            ],
+            "full_name": "Jack Nicholson",
+            "email": "jacknich@example.com",
+            "metadata": {
+                "intelligence": 7
+            },
+            "enabled": true
+        },
+        {
+            "username": "sandrakn",
+            "roles": [
+                "admin",
+                "other_role1"
+            ],
+            "full_name": "Sandra Knight",
+            "email": "sandrakn@example.com",
+            "metadata": {
+                "intelligence": 7
+            },
+            "enabled": true
+        }
+    ]
+}
+----
+// NOTCONSOLE
+
+<1> The list of users that were retrieved for this request
+
+If you create a user with the following details:
+
+[source,console]
+----
+POST /_security/user/jacknich
+{
+  "password" : "l0ng-r4nd0m-p@ssw0rd",
+  "roles" : [ "admin", "other_role1" ],
+  "full_name" : "Jack Nicholson",
+  "email" : "jacknich@example.com",
+  "metadata" : {
+    "intelligence" : 7
+  }
+}
+----
+
+A successful call returns a JSON structure:
+
+[source,console-result]
+----
+{
+  "created": true
+}
+----
+
+Use the user information retrieve the user with a query:
+
+[source,console]
+----
+GET /_security/_query/user
+{
+    "query": {
+        "prefix": {
+            "roles": "other"
+        }
+    }
+}
+----
+// TEST[setup:jacknich_user]
+A successful call returns a JSON structure for a user:
+
+[source,console-result]
+--------------------------------------------------
+{
+    "total": 1,
+    "count": 1,
+    "users": [
+        {
+            "username": "jacknich",
+            "roles": [
+                "admin",
+                "other_role1"
+            ],
+            "full_name": "Jack Nicholson",
+            "email": "jacknich@example.com",
+            "metadata": {
+                "intelligence": 7
+            },
+            "enabled": true
+        }
+    ]
+}
+--------------------------------------------------
+// NOTCONSOLE
+
+Use a `bool` query to issue complex logical conditions and use
+`from`, `size`, `sort` to help paginate the result:
+
+[source,js]
+----
+GET /_security/_query/user
+{
+  "query": {
+    "bool": {
+      "must": [
+        {
+          "wildcard": {
+            "email": "*example.com" <1>
+          }
+        },
+        {
+          "term": {
+            "enabled": true <2>
+          }
+        }
+      ],
+      "filter": [
+        {
+          "wildcard": {
+            "roles": "*other*" <3>
+          }
+        }
+      ]
+    }
+  },
+  "from": 1, <4>
+  "size": 2, <5>
+  "sort": [
+    { "username": { "order": "desc"} } <6>
+  ]
+}
+----
+// NOTCONSOLE
+
+<1> The email must end with `example.com`
+<2> The user must be enabled
+<3> The result will be filtered to only contain users with at least one role that contains the substring `other`
+<4> The offset to begin the search result is the 2nd (zero-based index) user
+<5> The page size of the response is 2 users
+<6> The result is sorted by `username` in descending order
+
+The response contains a list of matched users along with their sort values:
+
+[source,js]
+----
+{
+    "total": 5,
+    "count": 2,
+    "users": [
+        {
+            "username": "ray",
+            "roles": [
+                "other_role3"
+            ],
+            "full_name": "Ray Nicholson",
+            "email": "rayn@example.com",
+            "metadata": {
+                "intelligence": 7
+            },
+            "enabled": true,
+            "_sort": [
+                "ray" <1>
+            ]
+        },
+        {
+            "username": "lorraine",
+            "roles": [
+                "other_role3"
+            ],
+            "full_name": "Lorraine Nicholson",
+            "email": "lorraine@example.com",
+            "metadata": {
+                "intelligence": 7
+            },
+            "enabled": true,
+            "_sort": [
+                "lorraine"
+            ]
+        }
+    ]
+}
+----
+// NOTCONSOLE
+
+<1> The sort value is `username`