mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 23:57:20 -04:00
747fa59a2c
These are the docs changes in relation to https://github.com/elastic/elasticsearch/pull/108733
358 lines
8.5 KiB
Text
358 lines
8.5 KiB
Text
[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-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 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-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-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}
|
|
|
|
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]
|
|
----
|
|
POST /_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
|
|
|
|
To retrieve the user `profile_uid` as part of the response:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /_security/_query/user?with_profile_uid=true
|
|
{
|
|
"query": {
|
|
"prefix": {
|
|
"roles": "other"
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[setup:jacknich_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,
|
|
"profile_uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
Use a `bool` query to issue complex logical conditions and use
|
|
`from`, `size`, `sort` to help paginate the result:
|
|
|
|
[source,js]
|
|
----
|
|
POST /_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`
|