From 94117bd64e2cb851e4692d2dc883e39fcc55e668 Mon Sep 17 00:00:00 2001 From: Yogesh Gaikwad Date: Mon, 19 Aug 2019 23:49:13 +1000 Subject: [PATCH 1/3] Document API key API changes for `owner` flag This commit adds documentation for `owner` flag for API key APIs. By default this flag is `false` and when set to `true` restricts the API key operations to the API keys owned by the currently authenticated user. --- .../rest-api/security/get-api-keys.asciidoc | 32 +++++++++++++-- .../security/invalidate-api-keys.asciidoc | 40 +++++++++++++++++-- 2 files changed, 66 insertions(+), 6 deletions(-) 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 7201a3f324d0e..4deaef411db3b 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 @@ -39,13 +39,20 @@ pertain to retrieving api keys: `realm_name`:: (Optional, string) The name of an authentication realm. This parameter cannot be -used with either `id` or `name`. +used with either `id` or `name` or when `owner` flag is set to `true`. `username`:: (Optional, string) The username of a user. This parameter cannot be used with -either `id` or `name`. +either `id` or `name` or when `owner` flag is set to `true`. -NOTE: While all parameters are optional, at least one of them is required. +`owner`:: +((Optional, boolean) A boolean flag that can be used to query API keys owned +by the currently authenticated user. Defaults to false. If this parameter is set to +`true` then `realm_name` or `username` parameters cannot be specified as +they default to the authenticated users name and realm name. + +NOTE: While all parameters are optional, at least one of them is required when `owner` +flag is set to `false`. [[security-api-get-api-key-example]] ==== {api-examples-title} @@ -114,6 +121,25 @@ GET /_security/api_key?username=myuser // CONSOLE // TEST[continued] +The following example retrieves the API key identified by the specified `id` if +it is owned by the currently authenticated user: + +[source,js] +-------------------------------------------------- +GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx&owner=true +-------------------------------------------------- +// CONSOLE +// TEST[continued] + +The following example retrieves all API keys owned by the currently authenticated user: + +[source,js] +-------------------------------------------------- +GET /_security/api_key?owner=true +-------------------------------------------------- +// CONSOLE +// TEST[continued] + Finally, the following example retrieves all API keys for the user `myuser` in the `native1` realm immediately: diff --git a/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc index a5cdcb1821e81..ead1f3cdcfa35 100644 --- a/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc +++ b/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc @@ -40,13 +40,20 @@ pertain to invalidating api keys: `realm_name`:: (Optional, string) The name of an authentication realm. This parameter cannot be -used with either `id` or `name`. +used with either `id` or `name` or when `owner` flag is set to `true`. `username`:: (Optional, string) The username of a user. This parameter cannot be used with -either `id` or `name`. +either `id` or `name` or when `owner` flag is set to `true`. -NOTE: While all parameters are optional, at least one of them is required. +`owner`:: +((Optional, boolean) A boolean flag that can be used to query API keys owned +by the currently authenticated user. Defaults to false. If this parameter is set to +`true` then `realm_name` or `username` parameters cannot be specified as +they default to the authenticated users name and realm name. + +NOTE: While all parameters are optional, at least one of them is required when `owner` +flag is set to `false`. [[security-api-invalidate-api-key-response-body]] ==== {api-response-body-title} @@ -138,6 +145,33 @@ DELETE /_security/api_key // CONSOLE // TEST +The following example invalidates the API key identified by the specified `id` if + it is owned by the currently authenticated user immediately: + +[source,js] +-------------------------------------------------- +DELETE /_security/api_key +{ + "id" : "VuaCfGcBCdbkQm-e5aOx", + "owner" : "true" +} +-------------------------------------------------- +// CONSOLE +// TEST + +The following example invalidates all API keys owned by the currently authenticated + user immediately: + +[source,js] +-------------------------------------------------- +DELETE /_security/api_key +{ + "owner" : "true" +} +-------------------------------------------------- +// CONSOLE +// TEST + Finally, the following example invalidates all API keys for the user `myuser` in the `native1` realm immediately: From 141008cb2a16601f9fe182be8d8464aee8d890fe Mon Sep 17 00:00:00 2001 From: Yogesh Gaikwad Date: Tue, 20 Aug 2019 11:23:44 +1000 Subject: [PATCH 2/3] fix test --- .../rest-api/security/get-api-keys.asciidoc | 24 ++++++++++++++----- .../security/invalidate-api-keys.asciidoc | 3 +-- 2 files changed, 19 insertions(+), 8 deletions(-) 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 4deaef411db3b..8b60485bb9477 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 @@ -46,7 +46,7 @@ used with either `id` or `name` or when `owner` flag is set to `true`. either `id` or `name` or when `owner` flag is set to `true`. `owner`:: -((Optional, boolean) A boolean flag that can be used to query API keys owned +(Optional, boolean) A boolean flag that can be used to query API keys owned by the currently authenticated user. Defaults to false. If this parameter is set to `true` then `realm_name` or `username` parameters cannot be specified as they default to the authenticated users name and realm name. @@ -121,23 +121,35 @@ GET /_security/api_key?username=myuser // CONSOLE // TEST[continued] -The following example retrieves the API key identified by the specified `id` if -it is owned by the currently authenticated user: +The following example retrieves all API keys owned by the currently authenticated user: [source,js] -------------------------------------------------- -GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx&owner=true +GET /_security/api_key?owner=true -------------------------------------------------- // CONSOLE // TEST[continued] -The following example retrieves all API keys owned by the currently authenticated user: +Following creates an API key + +[source, js] +------------------------------------------------------------ +POST /_security/api_key +{ + "name": "my-api-key-1" +} +------------------------------------------------------------ +// CONSOLE + +The following example retrieves the API key identified by the specified `id` if +it is owned by the currently authenticated user: [source,js] -------------------------------------------------- -GET /_security/api_key?owner=true +GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx&owner=true -------------------------------------------------- // CONSOLE +// TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/] // TEST[continued] Finally, the following example retrieves all API keys for the user `myuser` in diff --git a/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc index ead1f3cdcfa35..f24f915bd0279 100644 --- a/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc +++ b/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc @@ -47,7 +47,7 @@ used with either `id` or `name` or when `owner` flag is set to `true`. either `id` or `name` or when `owner` flag is set to `true`. `owner`:: -((Optional, boolean) A boolean flag that can be used to query API keys owned +(Optional, boolean) A boolean flag that can be used to query API keys owned by the currently authenticated user. Defaults to false. If this parameter is set to `true` then `realm_name` or `username` parameters cannot be specified as they default to the authenticated users name and realm name. @@ -157,7 +157,6 @@ DELETE /_security/api_key } -------------------------------------------------- // CONSOLE -// TEST The following example invalidates all API keys owned by the currently authenticated user immediately: From bfef20c30a21a7fa95a98a1cb31a8f61543f59e0 Mon Sep 17 00:00:00 2001 From: Yogesh Gaikwad Date: Wed, 21 Aug 2019 18:40:17 +1000 Subject: [PATCH 3/3] address review comments --- x-pack/docs/en/rest-api/security/get-api-keys.asciidoc | 10 +++++----- .../en/rest-api/security/invalidate-api-keys.asciidoc | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) 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 8b60485bb9477..1aa47ebab64cc 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 @@ -47,12 +47,12 @@ either `id` or `name` or when `owner` flag is set to `true`. `owner`:: (Optional, boolean) A boolean flag that can be used to query API keys owned -by the currently authenticated user. Defaults to false. If this parameter is set to -`true` then `realm_name` or `username` parameters cannot be specified as -they default to the authenticated users name and realm name. +by the currently authenticated user. Defaults to false. +The 'realm_name' or 'username' parameters cannot be specified when this +parameter is set to 'true' as they are assumed to be the currently authenticated ones. -NOTE: While all parameters are optional, at least one of them is required when `owner` -flag is set to `false`. +NOTE: At least one of "id", "name", "username" and "realm_name" must be specified + if "owner" is "false" (default). [[security-api-get-api-key-example]] ==== {api-examples-title} diff --git a/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc index f24f915bd0279..ecd79a0906cfd 100644 --- a/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc +++ b/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc @@ -48,12 +48,12 @@ either `id` or `name` or when `owner` flag is set to `true`. `owner`:: (Optional, boolean) A boolean flag that can be used to query API keys owned -by the currently authenticated user. Defaults to false. If this parameter is set to -`true` then `realm_name` or `username` parameters cannot be specified as -they default to the authenticated users name and realm name. +by the currently authenticated user. Defaults to false. +The 'realm_name' or 'username' parameters cannot be specified when this +parameter is set to 'true' as they are assumed to be the currently authenticated ones. -NOTE: While all parameters are optional, at least one of them is required when `owner` -flag is set to `false`. +NOTE: At least one of "id", "name", "username" and "realm_name" must be specified + if "owner" is "false" (default). [[security-api-invalidate-api-key-response-body]] ==== {api-response-body-title}