Query User API

edit

Retrieves native users with Query DSL in a paginated fashion.

As opposed to the get user api, built-in users are excluded from the result. This API is only for native users.

Request

edit

GET /_security/_query/user

POST /_security/_query/user

Prerequisites

edit
  • To use this API, you must have at least the read_security cluster privilege.

Description

edit

Use this API to retrieve users managed by the native realm in a paginated manner. You can optionally filter the results with a query.

Request body

edit

You can specify the following parameters in the request body:

query

(Optional, string) A query to filter which users to return. The query supports a subset of query types, including match_all, bool, term, terms, match, ids, prefix, wildcard, exists, range, and simple query string.

You can query the following public values associated with a user.

Valid values for query
username
An identifier for the user.
roles
An array of the role names of the 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.
from

(Optional, integer) Starting document offset. Needs to be non-negative and defaults to 0.

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 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 parameter.

sort
(Optional, object) 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 definition.

Query parameters

edit
with_profile_uid
(Optional, boolean) Determines whether to retrieve the user profile uid, if exists, for the users. Defaults to false.

Response body

edit

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.

Examples

edit

The following request lists all users, assuming you have the read_security privilege:

resp = client.perform_request(
    "GET",
    "/_security/_query/user",
)
print(resp)
const response = await client.security.queryUser();
console.log(response);
GET /_security/_query/user

A successful call returns a JSON structure that contains the information retrieved from one or more users:

{
    "total": 2,
    "count": 2,
    "users": [ 
        {
            "username": "jacknich",
            "roles": [
                "admin",
                "other_role1"
            ],
            "full_name": "Jack Nicholson",
            "email": "[email protected]",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true
        },
        {
            "username": "sandrakn",
            "roles": [
                "admin",
                "other_role1"
            ],
            "full_name": "Sandra Knight",
            "email": "[email protected]",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true
        }
    ]
}

The list of users that were retrieved for this request

If you create a user with the following details:

resp = client.security.put_user(
    username="jacknich",
    password="l0ng-r4nd0m-p@ssw0rd",
    roles=[
        "admin",
        "other_role1"
    ],
    full_name="Jack Nicholson",
    email="[email protected]",
    metadata={
        "intelligence": 7
    },
)
print(resp)
const response = await client.security.putUser({
  username: "jacknich",
  password: "l0ng-r4nd0m-p@ssw0rd",
  roles: ["admin", "other_role1"],
  full_name: "Jack Nicholson",
  email: "[email protected]",
  metadata: {
    intelligence: 7,
  },
});
console.log(response);
POST /_security/user/jacknich
{
  "password" : "l0ng-r4nd0m-p@ssw0rd",
  "roles" : [ "admin", "other_role1" ],
  "full_name" : "Jack Nicholson",
  "email" : "[email protected]",
  "metadata" : {
    "intelligence" : 7
  }
}

A successful call returns a JSON structure:

{
  "created": true
}

Use the user information retrieve the user with a query:

resp = client.perform_request(
    "POST",
    "/_security/_query/user",
    headers={"Content-Type": "application/json"},
    body={
        "query": {
            "prefix": {
                "roles": "other"
            }
        }
    },
)
print(resp)
const response = await client.security.queryUser({
  query: {
    prefix: {
      roles: "other",
    },
  },
});
console.log(response);
POST /_security/_query/user
{
    "query": {
        "prefix": {
            "roles": "other"
        }
    }
}

A successful call returns a JSON structure for a user:

{
    "total": 1,
    "count": 1,
    "users": [
        {
            "username": "jacknich",
            "roles": [
                "admin",
                "other_role1"
            ],
            "full_name": "Jack Nicholson",
            "email": "[email protected]",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true
        }
    ]
}

To retrieve the user profile_uid as part of the response:

resp = client.perform_request(
    "POST",
    "/_security/_query/user",
    params={
        "with_profile_uid": "true"
    },
    headers={"Content-Type": "application/json"},
    body={
        "query": {
            "prefix": {
                "roles": "other"
            }
        }
    },
)
print(resp)
const response = await client.security.queryUser({
  with_profile_uid: "true",
  query: {
    prefix: {
      roles: "other",
    },
  },
});
console.log(response);
POST /_security/_query/user?with_profile_uid=true
{
    "query": {
        "prefix": {
            "roles": "other"
        }
    }
}
{
    "total": 1,
    "count": 1,
    "users": [
        {
            "username": "jacknich",
            "roles": [
                "admin",
                "other_role1"
            ],
            "full_name": "Jack Nicholson",
            "email": "[email protected]",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true,
            "profile_uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
        }
    ]
}

Use a bool query to issue complex logical conditions and use from, size, sort to help paginate the result:

POST /_security/_query/user
{
  "query": {
    "bool": {
      "must": [
        {
          "wildcard": {
            "email": "*example.com" 
          }
        },
        {
          "term": {
            "enabled": true 
          }
        }
      ],
      "filter": [
        {
          "wildcard": {
            "roles": "*other*" 
          }
        }
      ]
    }
  },
  "from": 1, 
  "size": 2, 
  "sort": [
    { "username": { "order": "desc"} } 
  ]
}

The email must end with example.com

The user must be enabled

The result will be filtered to only contain users with at least one role that contains the substring other

The offset to begin the search result is the 2nd (zero-based index) user

The page size of the response is 2 users

The result is sorted by username in descending order

The response contains a list of matched users along with their sort values:

{
    "total": 5,
    "count": 2,
    "users": [
        {
            "username": "ray",
            "roles": [
                "other_role3"
            ],
            "full_name": "Ray Nicholson",
            "email": "[email protected]",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true,
            "_sort": [
                "ray" 
            ]
        },
        {
            "username": "lorraine",
            "roles": [
                "other_role3"
            ],
            "full_name": "Lorraine Nicholson",
            "email": "[email protected]",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true,
            "_sort": [
                "lorraine"
            ]
        }
    ]
}

The sort value is username