From 576fcde4490b936a3d4fe284f3d1350f79631b94 Mon Sep 17 00:00:00 2001 From: Yang Wang Date: Fri, 6 Aug 2021 15:43:19 +1000 Subject: [PATCH 01/12] API key search API - documentation --- x-pack/docs/en/rest-api/security.asciidoc | 2 + .../rest-api/security/get-api-keys.asciidoc | 4 +- .../rest-api/security/query-api-key.asciidoc | 258 ++++++++++++++++++ 3 files changed, 262 insertions(+), 2 deletions(-) create mode 100644 x-pack/docs/en/rest-api/security/query-api-key.asciidoc diff --git a/x-pack/docs/en/rest-api/security.asciidoc b/x-pack/docs/en/rest-api/security.asciidoc index 09b244fe32d00..40f2ca568026f 100644 --- a/x-pack/docs/en/rest-api/security.asciidoc +++ b/x-pack/docs/en/rest-api/security.asciidoc @@ -69,6 +69,7 @@ without requiring basic authentication: * <> * <> * <> +* <> [discrete] [[security-user-apis]] @@ -172,6 +173,7 @@ include::security/invalidate-tokens.asciidoc[] include::security/oidc-prepare-authentication-api.asciidoc[] include::security/oidc-authenticate-api.asciidoc[] include::security/oidc-logout-api.asciidoc[] +include::security/query-api-key.asciidoc[] include::security/saml-prepare-authentication-api.asciidoc[] include::security/saml-authenticate-api.asciidoc[] include::security/saml-logout-api.asciidoc[] diff --git a/x-pack/docs/en/rest-api/security/get-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/get-api-keys.asciidoc index dce3f48370028..e0dcf8801536a 100644 --- a/x-pack/docs/en/rest-api/security/get-api-keys.asciidoc +++ b/x-pack/docs/en/rest-api/security/get-api-keys.asciidoc @@ -179,7 +179,7 @@ A successful call returns a JSON structure that contains the information of one { "api_keys": [ <1> { - "id": "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==", <2> + "id": "0GF5GXsBCXxz2eDxWwFN", <2> "name": "hadoop_myuser_key", <3> "creation": 1548550550158, <4> "expiration": 1548551550158, <5> @@ -191,7 +191,7 @@ A successful call returns a JSON structure that contains the information of one } }, { - "id": "api-key-id-2", + "id": "6wHJmcQpReKBa42EHV5SBw", "name": "api-key-name-2", "creation": 1548550550158, "invalidated": false, diff --git a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc new file mode 100644 index 0000000000000..ab6239082cd4f --- /dev/null +++ b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc @@ -0,0 +1,258 @@ +[role="xpack"] +[[security-api-query-api-key]] +=== Query API key information API +++++ +Query API key information +++++ + +Retrieves information for API keys with <> +in a <> fashion. + +[[security-api-query-api-key-request]] +==== {api-request-title} + +`GET /_security/_query/api_key` + +`POST /_security/_query/api_key` + +[[security-api-query-api-key-prereqs]] +==== {api-prereq-title} + +* To use this API, you must have at least the `manage_own_api_key` cluster privilege. + +[[security-api-query-api-key-desc]] +==== {api-description-title} + +The information for the API keys created by +<> can be retrieved using this API in +a paginated manner and optionally filtered with a query. + +[[security-api-query-api-key-request-body]] +==== {api-path-body-title} + +The following parameters can be specified in the body of a request and +pertain to retrieving api keys: + +`query`:: +(Optional, string) A <> to filter API keys to be returned. +Note it only support a subset of the query types including +<>, <>, +<>, <>, <>, +<>, <>, <>. + +include::{es-repo-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 +<> parameter. + +`size`:: +(Optional, integer) The number of hits to return. Needs to be non-negative. ++ +By default, you cannot page through more than 10,000 hits using the `from` and +`size` parameters. To page through more hits, use the +<> parameter. + +`sort`:: +(Optional, object) <>. Other than `id`, +all fields of an API key are eligible for sorting. In addition, sort can +also be applied to the `_doc` field, which is useful for tie-breaking. + +`search_after`:: +(Optional, array) <> definition. + +NOTE: If the user only has `manage_own_api_key` privilege, this API returns +only those API keys that are owned by the user. + +[[security-api-query-api-key-response-body]] +==== {api-response-body-title} + +This API returns the following top level fields: + +`total`:: +The total number of API keys found. + +`count`:: +The number of API keys returned in the response. + +`api_keys`:: +A list of API key information. + +[[security-api-query-api-key-example]] +==== {api-examples-title} + +The following example list all API keys (assuming user has the `manage_api_key` privilege): + +[source,console] +------------------------------------------------------------ +GET /_security/_query/api_key +------------------------------------------------------------ + +A successful call returns a JSON structure that contains the information of one or more API keys that were retrieved. + +[source,js] +-------------------------------------------------- +{ + "total": 3, + "count": 3, + "api_keys": [ <1> + { + "id": "nkvrGXsB8w290t56q3Rg", <2> + "name": "my-api-key-1", <3> + "creation": 1628227480421, <4> + "expiration": 1629091480421, <5> + "invalidated": false, <6> + "username": "elastic", <7> + "realm": "reserved", <8> + "metadata": { <9> + "letter": "a" + } + }, + { + "id": "oEvrGXsB8w290t5683TI", + "name": "my-api-key-2", + "creation": 1628227498953, + "expiration": 1628313898953, + "invalidated": false, + "username": "elastic", + "realm": "reserved", + "metadata": { + "letter": "b" + } + } + ] +} +-------------------------------------------------- +// NOTCONSOLE + +<1> The list of API keys that were retrieved for this request. +<2> Id for the API key +<3> Name of the API key +<4> Creation time for the API key in milliseconds +<5> Optional expiration time for the API key in milliseconds +<6> Invalidation status for the API key. If the key has been invalidated, it has +a value of `true`. Otherwise, it is `false`. +<7> Principal for which this API key was created +<8> Realm name of the principal for which this API key was created +<9> Metadata of the API key + + +If you create an API key as follows: + +[source,console] +------------------------------------------------------------ +POST /_security/api_key +{ + "name": "application-key-1", + "metadata": { "application": "my-application"} +} +------------------------------------------------------------ + +A successful call returns a JSON structure that provides +API key information. For example: + +[source,console-result] +-------------------------------------------------- +{ + "id": "VuaCfGcBCdbkQm-e5aOx", + "name": "application-key-1", + "api_key": "ui2lp2axTNmsyakw9tvNnw" +} +-------------------------------------------------- +// TESTRESPONSE[s/VuaCfGcBCdbkQm-e5aOx/$body.id/] +// TESTRESPONSE[s/ui2lp2axTNmsyakw9tvNnw/$body.api_key/] + +You can use the following example to retrieve the API key by ID: + +[source,console] +-------------------------------------------------- +GET /_security/_query/api_key +{ + "query": { + "ids": { + "values": [ + "VuaCfGcBCdbkQm-e5aOx" + ] + } + } +} +-------------------------------------------------- +// TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/] +// TEST[continued] + +You can also retrieve the API key by name: + +[source,console] +-------------------------------------------------- +GET /_security/_query/api_key +{ + "query": { + "term": { + "name": { + "value": "application-key-1" + } + } + } +} +-------------------------------------------------- +// TEST[continued] + +You can use bool query to issue complex logical conditions and use +`from`, `size`, `sort` to help paginate the result. + +[source,js] +-------------------------------------------------- +{ + "query": { + "bool": { + "must": [ + { + "prefix": { + "name": "app1-key-" <1> + } + }, + { + "term": { + "invalidated": "false" <2> + } + } + ], + "must_not": [ + { + "term": { + "name": "app1-key-01" <3> + } + } + ], + "filter": [ + { + "wildcard": { + "username": "org-*-user" <4> + } + }, + { + "term": { + "metadata.environment": "production" <5> + } + } + ] + } + }, + "from": 20, <6> + "size": 10, <7> + "sort": [ <8> + "creation": { "order": "desc" }, + "name" + ] +} +-------------------------------------------------- +// NOTCONSOLE + +<1> The API key name must begin with `app1-key-` +<2> The API key must still be valid +<3> The API key name must not be `app1-key-01` +<4> The API key must be owned by username of the <> pattern `org-*-user` +<5> The API key must have the metadata field `environment` that has the value of `production`. +<6> The offset to begin the search result is the 20th (zero-based index) API key +<7> The page size of the response is 10 API keys +<8> The result is first sorted by `creation` date in descending order, then by name in ascending order. From 2b41cfd3c82c5c0a17555eeda6e0a4d27327cceb Mon Sep 17 00:00:00 2001 From: Yang Wang Date: Tue, 17 Aug 2021 16:35:18 +1000 Subject: [PATCH 02/12] Update x-pack/docs/en/rest-api/security/query-api-key.asciidoc Co-authored-by: Tim Vernum --- x-pack/docs/en/rest-api/security/query-api-key.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc index ab6239082cd4f..c3974f2f8cd12 100644 --- a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc +++ b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc @@ -47,7 +47,7 @@ By default, you cannot page through more than 10,000 hits using the `from` and <> parameter. `size`:: -(Optional, integer) The number of hits to return. Needs to be non-negative. +(Optional, integer) The number of hits to return. Must not be negative. + By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters. To page through more hits, use the From 41a708a424092d506cedf70696b63f75389d0452 Mon Sep 17 00:00:00 2001 From: Yang Wang Date: Tue, 17 Aug 2021 16:55:35 +1000 Subject: [PATCH 03/12] address feedback --- .../en/rest-api/security/query-api-key.asciidoc | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc index c3974f2f8cd12..e3602c24dd3ce 100644 --- a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc +++ b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc @@ -39,6 +39,18 @@ Note it only support a subset of the query types including <>, <>, <>, <>, <>, <>, <>, <>. +All public information associated to an API key can be queried, including: + +* ID of the API key can be queried with the <> +* `name` - Name of the API key +* `creation` - Creation time of the API key +* `expiration` - Expiration time of the API key +* `invalidated` - Whether the API key is invalidated +* `username` - Username of the API key owner +* `realm` - Realm name of the API key owner +* Any metadata fields, e.g. `metadata.my_field`. Since metadata is saved as the + <>, all fields, including numerical ones, + behave essentially like keywords when it comes to query and sorting. include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=from] + @@ -62,7 +74,9 @@ also be applied to the `_doc` field, which is useful for tie-breaking. (Optional, array) <> definition. NOTE: If the user only has `manage_own_api_key` privilege, this API returns -only those API keys that are owned by the user. +only those API keys that are owned by the user. On the other hand, if the user +has `manage_api_key` or greater privilege (including `manage_security`), this +API returns API keys regardless of their owners. [[security-api-query-api-key-response-body]] ==== {api-response-body-title} From 274810aaa6c057d7501939f0ae212472b6beaa6b Mon Sep 17 00:00:00 2001 From: Yang Wang Date: Wed, 18 Aug 2021 10:13:44 +1000 Subject: [PATCH 04/12] Apply suggestions from code review Co-authored-by: Adam Locke --- .../rest-api/security/query-api-key.asciidoc | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc index e3602c24dd3ce..de6351aa8b829 100644 --- a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc +++ b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc @@ -6,7 +6,7 @@ ++++ Retrieves information for API keys with <> -in a <> fashion. +in a <> fashion. [[security-api-query-api-key-request]] ==== {api-request-title} @@ -23,22 +23,22 @@ in a <> fashion. [[security-api-query-api-key-desc]] ==== {api-description-title} -The information for the API keys created by -<> can be retrieved using this API in -a paginated manner and optionally filtered with a query. +Use this API to retrieve the API keys created with the +<> in a paginated manner. +You can optionally filter the results with a query. [[security-api-query-api-key-request-body]] -==== {api-path-body-title} +==== {api-path-parms-title} + +You can specify the following parameters in the request body: -The following parameters can be specified in the body of a request and -pertain to retrieving api keys: `query`:: -(Optional, string) A <> to filter API keys to be returned. -Note it only support a subset of the query types including -<>, <>, -<>, <>, <>, -<>, <>, <>. +(Optional, string) A <> to filter which API keys to return. +The query supports a subset of query types, including +<>, <>, +<>, <>, <>, +<>, <>, and <>. All public information associated to an API key can be queried, including: * ID of the API key can be queried with the <> From 55761b0d12bac0cedf0ef04aa317f8a7773b0b90 Mon Sep 17 00:00:00 2001 From: Yang Wang Date: Wed, 18 Aug 2021 10:17:15 +1000 Subject: [PATCH 05/12] address feedback --- x-pack/docs/en/rest-api/security/query-api-key.asciidoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc index de6351aa8b829..821b4036ee119 100644 --- a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc +++ b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc @@ -19,6 +19,10 @@ in a <> fashion. ==== {api-prereq-title} * To use this API, you must have at least the `manage_own_api_key` cluster privilege. +* If the user only has the `manage_own_api_key` privilege, this API returns +those API keys that are owned by the user. On the other hand, if the user +has the `manage_api_key` or greater privileges (including `manage_security`), this +API returns API keys regardless of their owners. [[security-api-query-api-key-desc]] ==== {api-description-title} @@ -73,10 +77,6 @@ also be applied to the `_doc` field, which is useful for tie-breaking. `search_after`:: (Optional, array) <> definition. -NOTE: If the user only has `manage_own_api_key` privilege, this API returns -only those API keys that are owned by the user. On the other hand, if the user -has `manage_api_key` or greater privilege (including `manage_security`), this -API returns API keys regardless of their owners. [[security-api-query-api-key-response-body]] ==== {api-response-body-title} From 4a8aa32e9960db5866442058a1da9f70c7fc1d18 Mon Sep 17 00:00:00 2001 From: Yang Wang Date: Wed, 18 Aug 2021 11:40:23 +1000 Subject: [PATCH 06/12] add _sort example --- .../rest-api/security/query-api-key.asciidoc | 51 ++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc index 821b4036ee119..300da5c857c34 100644 --- a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc +++ b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc @@ -255,7 +255,7 @@ You can use bool query to issue complex logical conditions and use "from": 20, <6> "size": 10, <7> "sort": [ <8> - "creation": { "order": "desc" }, + { "creation": { "order": "desc", "format": "date_time" } }, "name" ] } @@ -270,3 +270,52 @@ You can use bool query to issue complex logical conditions and use <6> The offset to begin the search result is the 20th (zero-based index) API key <7> The page size of the response is 10 API keys <8> The result is first sorted by `creation` date in descending order, then by name in ascending order. + +The response contains a list of matched API keys along with their sort values: + +[source,js] +-------------------------------------------------- +{ + "total": 100, + "count": 10, + "api_keys": [ + { + "id": "CLXgVnsBOGkf8IyjcXU7", + "name": "app1-key-79", + "creation": 1629250154811, + "invalidated": false, + "username": "org-admin-user", + "realm": "native1", + "metadata": { + "environment": "production" + }, + "_sort": [ <1> + "2021-08-18T01:29:14.811Z", <2> + "app1-key-79" <3> + ] + }, + { + "id": "BrXgVnsBOGkf8IyjbXVB", + "name": "app1-key-78", + "creation": 1629250153794, + "invalidated": false, + "username": "org-admin-user", + "realm": "native1", + "metadata": { + "environment": "production" + }, + "_sort": [ + "2021-08-18T01:29:13.794Z", + "app1-key-78" + ] + }, + ... + ] +} +-------------------------------------------------- +// NOTCONSOLE + +<1> Sort values associated to the API key +<2> The first sort value is creation time and it is displayed in `date_time` <> +as requested in the request +<3> The second sort value is API key name From eba62eb583b120fc935b6a45a54c5a2f32013060 Mon Sep 17 00:00:00 2001 From: Yang Wang Date: Wed, 18 Aug 2021 11:48:51 +1000 Subject: [PATCH 07/12] fix ref link --- x-pack/docs/en/rest-api/security/query-api-key.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc index 300da5c857c34..2574f28129d59 100644 --- a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc +++ b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc @@ -316,6 +316,6 @@ The response contains a list of matched API keys along with their sort values: // NOTCONSOLE <1> Sort values associated to the API key -<2> The first sort value is creation time and it is displayed in `date_time` <> +<2> The first sort value is creation time and it is displayed in `date_time` <> as requested in the request <3> The second sort value is API key name From 3b35e2fd12767bba91ceed8efb951385c62fcb85 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 18 Aug 2021 11:15:41 -0400 Subject: [PATCH 08/12] Add definition list plus other editorial changes --- .../rest-api/security/query-api-key.asciidoc | 137 ++++++++++-------- 1 file changed, 74 insertions(+), 63 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc index 2574f28129d59..ce94cdc2e9143 100644 --- a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc +++ b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc @@ -36,25 +36,46 @@ You can optionally filter the results with a query. You can specify the following parameters in the request body: - `query`:: (Optional, string) A <> to filter which API keys to return. The query supports a subset of query types, including <>, <>, <>, <>, <>, <>, <>, and <>. -All public information associated to an API key can be queried, including: - -* ID of the API key can be queried with the <> -* `name` - Name of the API key -* `creation` - Creation time of the API key -* `expiration` - Expiration time of the API key -* `invalidated` - Whether the API key is invalidated -* `username` - Username of the API key owner -* `realm` - Realm name of the API key owner -* Any metadata fields, e.g. `metadata.my_field`. Since metadata is saved as the - <>, all fields, including numerical ones, - behave essentially like keywords when it comes to query and sorting. ++ +You can query all public information associated with an API key, including the +following values. ++ +.Valid values for `query` +[%collapsible%open] +==== +`id`:: +ID of the API key. + +`name`:: +Name of the API key. + +`creation`:: +Creation time of the API key in milliseconds. + +`expiration`:: +Expiration time of the API key in milliseconds. + +`invalidated`:: +Indicates whether the API key is invalidated. If `true`, the key is invalidated. +Defaults to `false`. + +`username`:: +Username of the API key owner. + +`realm`:: +Realm name of the API key owner. + +`metadata`:: +Metadata field associated with the API key, such as `metadata.my_field`. Because +metadata is saved as a <> field type, all fields act like +`keyword` fields when querying and sorting. +==== include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=from] + @@ -95,30 +116,32 @@ A list of API key information. [[security-api-query-api-key-example]] ==== {api-examples-title} -The following example list all API keys (assuming user has the `manage_api_key` privilege): +The following example lists all API keys, assuming the user has the +`manage_api_key` privilege: [source,console] ------------------------------------------------------------- +---- GET /_security/_query/api_key ------------------------------------------------------------- +---- -A successful call returns a JSON structure that contains the information of one or more API keys that were retrieved. +A successful call returns a JSON structure that contains the information +retrieved from one or more API keys: [source,js] --------------------------------------------------- +---- { "total": 3, "count": 3, "api_keys": [ <1> { - "id": "nkvrGXsB8w290t56q3Rg", <2> - "name": "my-api-key-1", <3> - "creation": 1628227480421, <4> - "expiration": 1629091480421, <5> - "invalidated": false, <6> - "username": "elastic", <7> - "realm": "reserved", <8> - "metadata": { <9> + "id": "nkvrGXsB8w290t56q3Rg", + "name": "my-api-key-1", + "creation": 1628227480421, + "expiration": 1629091480421, + "invalidated": false, + "username": "elastic", + "realm": "reserved", + "metadata": { "letter": "a" } }, @@ -136,50 +159,40 @@ A successful call returns a JSON structure that contains the information of one } ] } --------------------------------------------------- +---- // NOTCONSOLE -<1> The list of API keys that were retrieved for this request. -<2> Id for the API key -<3> Name of the API key -<4> Creation time for the API key in milliseconds -<5> Optional expiration time for the API key in milliseconds -<6> Invalidation status for the API key. If the key has been invalidated, it has -a value of `true`. Otherwise, it is `false`. -<7> Principal for which this API key was created -<8> Realm name of the principal for which this API key was created -<9> Metadata of the API key - +<1> The list of API keys that were retrieved for this request If you create an API key as follows: [source,console] ------------------------------------------------------------- +---- POST /_security/api_key { "name": "application-key-1", "metadata": { "application": "my-application"} } ------------------------------------------------------------- +---- A successful call returns a JSON structure that provides API key information. For example: [source,console-result] --------------------------------------------------- +---- { "id": "VuaCfGcBCdbkQm-e5aOx", "name": "application-key-1", "api_key": "ui2lp2axTNmsyakw9tvNnw" } --------------------------------------------------- +---- // TESTRESPONSE[s/VuaCfGcBCdbkQm-e5aOx/$body.id/] // TESTRESPONSE[s/ui2lp2axTNmsyakw9tvNnw/$body.api_key/] -You can use the following example to retrieve the API key by ID: +You can use the returned information to retrieve the API key by ID: [source,console] --------------------------------------------------- +---- GET /_security/_query/api_key { "query": { @@ -190,14 +203,14 @@ GET /_security/_query/api_key } } } --------------------------------------------------- +---- // TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/] // TEST[continued] You can also retrieve the API key by name: [source,console] --------------------------------------------------- +---- GET /_security/_query/api_key { "query": { @@ -208,14 +221,14 @@ GET /_security/_query/api_key } } } --------------------------------------------------- +---- // TEST[continued] -You can use bool query to issue complex logical conditions and use -`from`, `size`, `sort` to help paginate the result. +Use a `bool` query to issue complex logical conditions and use +`from`, `size`, `sort` to help paginate the result: [source,js] --------------------------------------------------- +---- { "query": { "bool": { @@ -259,22 +272,22 @@ You can use bool query to issue complex logical conditions and use "name" ] } --------------------------------------------------- +---- // NOTCONSOLE <1> The API key name must begin with `app1-key-` <2> The API key must still be valid <3> The API key name must not be `app1-key-01` -<4> The API key must be owned by username of the <> pattern `org-*-user` -<5> The API key must have the metadata field `environment` that has the value of `production`. +<4> The API key must be owned by a username of the <> pattern `org-*-user` +<5> The API key must have the metadata field `environment` that has the value of `production` <6> The offset to begin the search result is the 20th (zero-based index) API key <7> The page size of the response is 10 API keys -<8> The result is first sorted by `creation` date in descending order, then by name in ascending order. +<8> The result is first sorted by `creation` date in descending order, then by name in ascending order The response contains a list of matched API keys along with their sort values: [source,js] --------------------------------------------------- +---- { "total": 100, "count": 10, @@ -289,9 +302,9 @@ The response contains a list of matched API keys along with their sort values: "metadata": { "environment": "production" }, - "_sort": [ <1> - "2021-08-18T01:29:14.811Z", <2> - "app1-key-79" <3> + "_sort": [ + "2021-08-18T01:29:14.811Z", <1> + "app1-key-79" <2> ] }, { @@ -312,10 +325,8 @@ The response contains a list of matched API keys along with their sort values: ... ] } --------------------------------------------------- +---- // NOTCONSOLE -<1> Sort values associated to the API key -<2> The first sort value is creation time and it is displayed in `date_time` <> -as requested in the request -<3> The second sort value is API key name +<1> The first sort value is creation time, which is displayed in `date_time` <> as defined in the request +<2> The second sort value is the API key name From 17628b7f1dd39460e8accaefc1448eb3e07df707 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 18 Aug 2021 13:22:27 -0400 Subject: [PATCH 09/12] Update request body title --- x-pack/docs/en/rest-api/security/query-api-key.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc index ce94cdc2e9143..911663057e742 100644 --- a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc +++ b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc @@ -32,7 +32,7 @@ Use this API to retrieve the API keys created with the You can optionally filter the results with a query. [[security-api-query-api-key-request-body]] -==== {api-path-parms-title} +==== {api-request-body-title} You can specify the following parameters in the request body: From 1d03e77740f1f8a5ff9cd7199c05c88a252a60c0 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 18 Aug 2021 15:20:00 -0400 Subject: [PATCH 10/12] Updating descriptions --- .../en/rest-api/security/query-api-key.asciidoc | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc index 509f1ac2aee4c..481f25dc69d66 100644 --- a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc +++ b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc @@ -19,11 +19,12 @@ in a <> fashion. [[security-api-query-api-key-prereqs]] ==== {api-prereq-title} -* To use this API, you must have at least the `manage_own_api_key` cluster privilege. -* If the user only has the `manage_own_api_key` privilege, this API returns -those API keys that are owned by the user. On the other hand, if the user -has the `manage_api_key` or greater privileges (including `manage_security`), this -API returns API keys regardless of their owners. +* To use this API, you must have at least the `manage_own_api_key` cluster +privilege. +* If you have only the `manage_own_api_key` privilege, this API returns only +the API keys that you own. If you have the `manage_api_key` or greater +privileges (including `manage_security`), this API returns all API keys +regardless of ownership. [[security-api-query-api-key-desc]] ==== {api-description-title} @@ -117,7 +118,7 @@ A list of API key information. [[security-api-query-api-key-example]] ==== {api-examples-title} -The following example lists all API keys, assuming the user has the +The following request lists all API keys, assuming you have the `manage_api_key` privilege: [source,console] @@ -165,7 +166,7 @@ retrieved from one or more API keys: <1> The list of API keys that were retrieved for this request -If you create an API key as follows: +If you create an API key with the following details: [source,console] ---- @@ -190,7 +191,7 @@ API key information. For example: // TESTRESPONSE[s/VuaCfGcBCdbkQm-e5aOx/$body.id/] // TESTRESPONSE[s/ui2lp2axTNmsyakw9tvNnw/$body.api_key/] -You can use the returned information to retrieve the API key by ID: +Use the information from the response to retrieve the API key by ID: [source,console] ---- From b2d59620f2062d413a5abc3bff0811430c2d5f45 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 18 Aug 2021 15:21:08 -0400 Subject: [PATCH 11/12] Remove leftover markup from merging --- x-pack/docs/en/rest-api/security/query-api-key.asciidoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc index 481f25dc69d66..7815a8d2d5941 100644 --- a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc +++ b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc @@ -331,5 +331,4 @@ The response contains a list of matched API keys along with their sort values: // NOTCONSOLE <1> The first sort value is creation time, which is displayed in `date_time` <> as defined in the request -<2> The second sort value is the API key name -======= +<2> The second sort value is the API key name \ No newline at end of file From 253791ac31b07d41393e49c65f67282859584e2c Mon Sep 17 00:00:00 2001 From: Yang Wang Date: Thu, 19 Aug 2021 08:33:17 +1000 Subject: [PATCH 12/12] tweaking --- .../rest-api/security/query-api-key.asciidoc | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc index 7815a8d2d5941..1a293c0f912bd 100644 --- a/x-pack/docs/en/rest-api/security/query-api-key.asciidoc +++ b/x-pack/docs/en/rest-api/security/query-api-key.asciidoc @@ -51,8 +51,8 @@ following values. .Valid values for `query` [%collapsible%open] ==== -`id`:: -ID of the API key. +`id`:: +ID of the API key. Note `id` must be queried with the <> query. `name`:: Name of the API key. @@ -75,7 +75,7 @@ Realm name of the API key owner. `metadata`:: Metadata field associated with the API key, such as `metadata.my_field`. Because -metadata is saved as a <> field type, all fields act like +metadata is stored as a <> field type, all fields act like `keyword` fields when querying and sorting. ==== @@ -86,7 +86,7 @@ By default, you cannot page through more than 10,000 hits using the `from` and <> parameter. `size`:: -(Optional, integer) The number of hits to return. Must not be negative. +(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 @@ -94,8 +94,8 @@ By default, you cannot page through more than 10,000 hits using the `from` and `sort`:: (Optional, object) <>. Other than `id`, -all fields of an API key are eligible for sorting. In addition, sort can -also be applied to the `_doc` field, which is useful for tie-breaking. +all public fields of an API key are eligible for sorting. In addition, sort can +also be applied to the `_doc` field to sort by index order. `search_after`:: (Optional, array) <> definition. @@ -138,9 +138,9 @@ retrieved from one or more API keys: { "id": "nkvrGXsB8w290t56q3Rg", "name": "my-api-key-1", - "creation": 1628227480421, + "creation": 1628227480421, "expiration": 1629091480421, - "invalidated": false, + "invalidated": false, "username": "elastic", "realm": "reserved", "metadata": { @@ -304,7 +304,7 @@ The response contains a list of matched API keys along with their sort values: "metadata": { "environment": "production" }, - "_sort": [ + "_sort": [ "2021-08-18T01:29:14.811Z", <1> "app1-key-79" <2> ] @@ -331,4 +331,4 @@ The response contains a list of matched API keys along with their sort values: // NOTCONSOLE <1> The first sort value is creation time, which is displayed in `date_time` <> as defined in the request -<2> The second sort value is the API key name \ No newline at end of file +<2> The second sort value is the API key name