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
283 lines
7.7 KiB
Text
283 lines
7.7 KiB
Text
[role="xpack"]
|
|
[[security-api-query-role]]
|
|
=== Query Role API
|
|
|
|
++++
|
|
<titleabbrev>Query Role</titleabbrev>
|
|
++++
|
|
|
|
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 files, nor <<built-in-roles,built-in>> ones.
|
|
You can optionally filter the results with a query. Also, the results can be paginated and sorted.
|
|
|
|
[[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, sorted by the role name:
|
|
|
|
[source,console]
|
|
----
|
|
POST /_security/_query/role
|
|
{
|
|
"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"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// 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."
|
|
}
|
|
]
|
|
}
|
|
----
|