DOCS Query Roles #110473
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,283 @@ | ||
| [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." | ||
| } | ||
| ] | ||
| } | ||
| ---- | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@albertzaharovits For completeness sake wondering if we should mention that you can't query reserved roles, only native ones somewhere.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@n1v0lg Does that look OK for you: 57675dd ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
👍 looks great