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

[role="xpack"]
[[security-api-query-role]]
=== Query Role API

++++
<titleabbrev>Query Role</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-security[Security APIs].
--

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.yml` files.
You can optionally filter the results with a query. Also, the results can be paginated and sorted.

NOTE: This API automatically returns <<built-in-roles,built-in>> roles as well.
The built-in roles can be filtered out by using the `metadata._reserved` field in the query.
See <<security-api-query-role-example,example>> below.

[[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`::
(keyword) The <<security-api-put-role-path-params,name>> of the role.

`description`::
(text) The <<defining-roles,description>> of the role.

`metadata`::
(flattened) 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.

`application`:::
(keyword) The name of the application associated to the privileges and resources.

`privileges`:::
(keyword) The names of the privileges that the role grants.

`resources`:::
(keyword) 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.
The returned role format is an extension of the <<defining-roles,role definition>> format.
It adds the `transient_metadata.enabled` and the `_sort` fields.
`transient_metadata.enabled` is set to `false` in case the role is automatically disabled,
for example when the role grants privileges that are not allowed by the installed license.
`_sort` is present when the search query sorts on some field.
It contains the array of values that have been used for sorting.

[[security-api-query-role-example]]
==== {api-examples-title}

The following request lists all roles (except built-in ones), sorted by the role name:

[source,console]
----
POST /_security/_query/role
{
    "query": {
      "bool": {
        "must_not": {
          "term": {
            "metadata._reserved": true
          }
        }
      }
    },
    "sort": ["name"]
}
----
// TEST[setup:admin_role,user_role]

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

[source,console-result]
----
{
    "total": 2,
    "count": 2,
    "roles": [ <1>
        {
          "name" : "my_admin_role",
          "cluster" : [
            "all"
          ],
          "indices" : [
            {
              "names" : [
                "index1",
                "index2"
              ],
              "privileges" : [
                "all"
              ],
              "field_security" : {
                "grant" : [
                  "title",
                  "body"
                ]
              },
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [
            "other_user"
          ],
          "metadata" : {
            "version" : 1
          },
          "transient_metadata" : {
            "enabled" : true
          },
          "description" : "Grants full access to all management features within the cluster.",
          "_sort" : [
            "my_admin_role"
          ]
        },
        {
          "name" : "my_user_role",
          "cluster" : [ ],
          "indices" : [
            {
              "names" : [
                "index1",
                "index2"
              ],
              "privileges" : [
                "all"
              ],
              "field_security" : {
                "grant" : [
                  "title",
                  "body"
                ]
              },
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [ ],
          "metadata" : {
            "version" : 1
          },
          "transient_metadata" : {
            "enabled" : true
          },
          "description" : "Grants user access to some indicies.",
          "_sort" : [
            "my_user_role"
          ]
        }
    ]
}
----
// TESTRESPONSE[s/"total": 2/"total" : $body.total/]
// TEST[continued]

<1> The list of roles that were retrieved for this request

Similarly, the following request can be used to query only the user access role,
given its description:

[source,console]
----
POST /_security/_query/role
{
  "query": {
    "match": {
      "description": {
        "query": "user access"
      }
    }
  },
  "size": 1 <1>
}
----
// TEST[continued]

<1> Return only the best matching role

[source,console-result]
----
{
    "total": 2,
    "count": 1,
    "roles": [
        {
          "name" : "my_user_role",
          "cluster" : [ ],
          "indices" : [
            {
              "names" : [
                "index1",
                "index2"
              ],
              "privileges" : [
                "all"
              ],
              "field_security" : {
                "grant" : [
                  "title",
                  "body"
                ]
              },
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [ ],
          "metadata" : {
            "version" : 1
          },
          "transient_metadata" : {
            "enabled" : true
          },
          "description" : "Grants user access to some indicies."
        }
    ]
}
----
// TESTRESPONSE[s/"total": 2/"total" : $body.total/]