Skip to content

Commit 666774a

Browse files
jfredenn1v0lg
jfreden
and
n1v0lg
authored
Add documentation for Query User API (#104255)
* Add documentation for Query User API Co-authored-by: Nikolaj Volgushev <[email protected]>
1 parent 5af58ed commit 666774a

File tree

3 files changed

+334
-0
lines changed

3 files changed

+334
-0
lines changed

‎docs/build.gradle

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1787,6 +1787,28 @@ setups['setup-snapshots'] = setups['setup-repository'] + '''
17871787
"username": "jacknich",
17881788
"password" : "l0ng-r4nd0m-p@ssw0rd"
17891789
}
1790+
'''
1791+
setups['sandrakn_user'] = '''
1792+
- do:
1793+
security.put_user:
1794+
username: "sandrakn"
1795+
body: >
1796+
{
1797+
"password" : "l0ng-r4nd0m-p@ssw0rd",
1798+
"roles" : [ "admin", "other_role1" ],
1799+
"full_name" : "Sandra Knight",
1800+
"email" : "[email protected]",
1801+
"metadata" : { "intelligence" : 7 }
1802+
}
1803+
- do:
1804+
security.activate_user_profile:
1805+
body: >
1806+
{
1807+
"grant_type": "password",
1808+
"username": "sandrakn",
1809+
"password" : "l0ng-r4nd0m-p@ssw0rd"
1810+
}
1811+
17901812
'''
17911813
setups['app0102_privileges'] = '''
17921814
- do:

‎docs/reference/rest-api/security.asciidoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@ native realm:
9595
* <<security-api-disable-user,Disable users>>
9696
* <<security-api-enable-user,Enable users>>
9797
* <<security-api-get-user,Get users>>
98+
* <<security-api-query-user,Query users>>
9899

99100
[discrete]
100101
[[security-service-account-apis]]
@@ -199,6 +200,7 @@ include::security/oidc-prepare-authentication-api.asciidoc[]
199200
include::security/oidc-authenticate-api.asciidoc[]
200201
include::security/oidc-logout-api.asciidoc[]
201202
include::security/query-api-key.asciidoc[]
203+
include::security/query-user.asciidoc[]
202204
include::security/update-api-key.asciidoc[]
203205
include::security/bulk-update-api-keys.asciidoc[]
204206
include::security/saml-prepare-authentication-api.asciidoc[]

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

Lines changed: 310 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,310 @@
1+
[role="xpack"]
2+
[[security-api-query-user]]
3+
=== Query User API
4+
5+
++++
6+
<titleabbrev>Query User</titleabbrev>
7+
++++
8+
9+
Retrieves <<native-realm,native users>> with <<query-dsl,Query DSL>> in a <<paginate-search-results,paginated>> fashion.
10+
11+
NOTE: As opposed to the <<security-api-get-user,get user api>>, <<built-in-users,built-in users>> are excluded from the
12+
result. This API is only for <<native-realm,native users>>.
13+
14+
[[security-api-query-user-request]]
15+
==== {api-request-title}
16+
17+
`GET /_security/_query/user`
18+
19+
`POST /_security/_query/user`
20+
21+
[[security-api-query-user-prereqs]]
22+
==== {api-prereq-title}
23+
24+
* To use this API, you must have at least the `read_security` cluster privilege.
25+
26+
[[security-api-query-user-desc]]
27+
==== {api-description-title}
28+
29+
Use this API to retrieve users managed by the
30+
<<native-realm,native realm>> in a paginated manner.
31+
You can optionally filter the results with a query.
32+
33+
[[security-api-query-user-request-body]]
34+
==== {api-request-body-title}
35+
36+
You can specify the following parameters in the request body:
37+
38+
`query`::
39+
(Optional, string) A <<query-dsl,query>> to filter which users to return.
40+
The query supports a subset of query types, including
41+
<<query-dsl-match-all-query,`match_all`>>, <<query-dsl-bool-query,`bool`>>,
42+
<<query-dsl-term-query,`term`>>, <<query-dsl-terms-query,`terms`>>,
43+
<<query-dsl-prefix-query,`prefix`>>, <<query-dsl-wildcard-query,`wildcard`>> and <<query-dsl-exists-query,`exists`>>.
44+
+
45+
You can query the following public values associated with a user.
46+
+
47+
.Valid values for `query`
48+
[%collapsible%open]
49+
====
50+
`username`::
51+
An identifier for the user.
52+
53+
`roles`::
54+
An array of the role names of the <<defining-roles, roles>> that are assigned to the user.
55+
56+
`full_name`::
57+
Full name of the user.
58+
59+
`email`::
60+
The email of the user.
61+
62+
`enabled`::
63+
Specifies whether the user is enabled.
64+
65+
====
66+
67+
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=from]
68+
+
69+
By default, you cannot page through more than 10,000 hits using the `from` and
70+
`size` parameters. To page through more hits, use the
71+
<<search-after,`search_after`>> parameter.
72+
73+
`size`::
74+
(Optional, integer) The number of hits to return. Must not be negative and defaults to `10`.
75+
+
76+
By default, you cannot page through more than 10,000 hits using the `from` and
77+
`size` parameters. To page through more hits, use the
78+
<<search-after,`search_after`>> parameter.
79+
80+
`sort`::
81+
(Optional, object) <<sort-search-results,Sort definition>>. You can sort on `username`, `roles` or `enabled`.
82+
In addition, sort can also be applied to the `_doc` field to sort by index order.
83+
84+
`search_after`::
85+
(Optional, array) <<search-after,Search after>> definition.
86+
87+
88+
[[security-api-query-user-response-body]]
89+
==== {api-response-body-title}
90+
91+
This API returns the following top level fields:
92+
93+
`total`::
94+
The total number of users found.
95+
96+
`count`::
97+
The number of users returned in the response.
98+
99+
`users`::
100+
A list of users that match the query.
101+
102+
[[security-api-query-user-example]]
103+
==== {api-examples-title}
104+
105+
The following request lists all users, assuming you have the
106+
`read_security` privilege:
107+
108+
[source,console]
109+
----
110+
GET /_security/_query/user
111+
----
112+
// TEST[setup:jacknich_user,sandrakn_user]
113+
114+
A successful call returns a JSON structure that contains the information
115+
retrieved from one or more users:
116+
117+
[source,console-result]
118+
----
119+
{
120+
"total": 2,
121+
"count": 2,
122+
"users": [ <1>
123+
{
124+
"username": "jacknich",
125+
"roles": [
126+
"admin",
127+
"other_role1"
128+
],
129+
"full_name": "Jack Nicholson",
130+
"email": "[email protected]",
131+
"metadata": {
132+
"intelligence": 7
133+
},
134+
"enabled": true
135+
},
136+
{
137+
"username": "sandrakn",
138+
"roles": [
139+
"admin",
140+
"other_role1"
141+
],
142+
"full_name": "Sandra Knight",
143+
"email": "[email protected]",
144+
"metadata": {
145+
"intelligence": 7
146+
},
147+
"enabled": true
148+
}
149+
]
150+
}
151+
----
152+
// NOTCONSOLE
153+
154+
<1> The list of users that were retrieved for this request
155+
156+
If you create a user with the following details:
157+
158+
[source,console]
159+
----
160+
POST /_security/user/jacknich
161+
{
162+
"password" : "l0ng-r4nd0m-p@ssw0rd",
163+
"roles" : [ "admin", "other_role1" ],
164+
"full_name" : "Jack Nicholson",
165+
"email" : "[email protected]",
166+
"metadata" : {
167+
"intelligence" : 7
168+
}
169+
}
170+
----
171+
172+
A successful call returns a JSON structure:
173+
174+
[source,console-result]
175+
----
176+
{
177+
"created": true
178+
}
179+
----
180+
181+
Use the user information retrieve the user with a query:
182+
183+
[source,console]
184+
----
185+
GET /_security/_query/user
186+
{
187+
"query": {
188+
"prefix": {
189+
"roles": "other"
190+
}
191+
}
192+
}
193+
----
194+
// TEST[setup:jacknich_user]
195+
A successful call returns a JSON structure for a user:
196+
197+
[source,console-result]
198+
--------------------------------------------------
199+
{
200+
"total": 1,
201+
"count": 1,
202+
"users": [
203+
{
204+
"username": "jacknich",
205+
"roles": [
206+
"admin",
207+
"other_role1"
208+
],
209+
"full_name": "Jack Nicholson",
210+
"email": "[email protected]",
211+
"metadata": {
212+
"intelligence": 7
213+
},
214+
"enabled": true
215+
}
216+
]
217+
}
218+
--------------------------------------------------
219+
// NOTCONSOLE
220+
221+
Use a `bool` query to issue complex logical conditions and use
222+
`from`, `size`, `sort` to help paginate the result:
223+
224+
[source,js]
225+
----
226+
GET /_security/_query/user
227+
{
228+
"query": {
229+
"bool": {
230+
"must": [
231+
{
232+
"wildcard": {
233+
"email": "*example.com" <1>
234+
}
235+
},
236+
{
237+
"term": {
238+
"enabled": true <2>
239+
}
240+
}
241+
],
242+
"filter": [
243+
{
244+
"wildcard": {
245+
"roles": "*other*" <3>
246+
}
247+
}
248+
]
249+
}
250+
},
251+
"from": 1, <4>
252+
"size": 2, <5>
253+
"sort": [
254+
{ "username": { "order": "desc"} } <6>
255+
]
256+
}
257+
----
258+
// NOTCONSOLE
259+
260+
<1> The email must end with `example.com`
261+
<2> The user must be enabled
262+
<3> The result will be filtered to only contain users with at least one role that contains the substring `other`
263+
<4> The offset to begin the search result is the 2nd (zero-based index) user
264+
<5> The page size of the response is 2 users
265+
<6> The result is sorted by `username` in descending order
266+
267+
The response contains a list of matched users along with their sort values:
268+
269+
[source,js]
270+
----
271+
{
272+
"total": 5,
273+
"count": 2,
274+
"users": [
275+
{
276+
"username": "ray",
277+
"roles": [
278+
"other_role3"
279+
],
280+
"full_name": "Ray Nicholson",
281+
"email": "[email protected]",
282+
"metadata": {
283+
"intelligence": 7
284+
},
285+
"enabled": true,
286+
"_sort": [
287+
"ray" <1>
288+
]
289+
},
290+
{
291+
"username": "lorraine",
292+
"roles": [
293+
"other_role3"
294+
],
295+
"full_name": "Lorraine Nicholson",
296+
"email": "[email protected]",
297+
"metadata": {
298+
"intelligence": 7
299+
},
300+
"enabled": true,
301+
"_sort": [
302+
"lorraine"
303+
]
304+
}
305+
]
306+
}
307+
----
308+
// NOTCONSOLE
309+
310+
<1> The sort value is `username`

0 commit comments

Comments
 (0)