From 68c7145e5443e1155802349c9bcfa94b211b4c73 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 7 Oct 2020 16:48:10 -0700 Subject: [PATCH 1/8] [DOCS] Add grant API key API --- x-pack/docs/en/rest-api/security.asciidoc | 8 +- .../rest-api/security/grant-api-keys.asciidoc | 133 ++++++++++++++++++ 2 files changed, 138 insertions(+), 3 deletions(-) create mode 100644 x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc diff --git a/x-pack/docs/en/rest-api/security.asciidoc b/x-pack/docs/en/rest-api/security.asciidoc index 25dc90f7cb1e5..e503116f7070f 100644 --- a/x-pack/docs/en/rest-api/security.asciidoc +++ b/x-pack/docs/en/rest-api/security.asciidoc @@ -61,10 +61,11 @@ without requiring basic authentication: You can use the following APIs to create, retrieve and invalidate API keys for access without requiring basic authentication: -* <> -* <> -* <> +* <> +* <> +* <> * <> +* <Grant API keys +++++ + +Creates an API key on behalf of another user for access without requiring basic +authentication. + +[[security-api-grant-api-key-request]] +==== {api-request-title} + +`POST /_security/api_key/grant` + +[[security-api-grant-api-key-prereqs]] +==== {api-prereq-title} + +* To use this API, you must have the `grant_api_key` cluster privilege. + +[[security-api-grant-api-key-desc]] +==== {api-description-title} + +This API is similar to <>, however it creates the +API key for a user that is different than the user that runs the API. + +The API keys are created by the {es} API key service, which is automatically +enabled when you configure TLS on the HTTP interface. See <>. +Alternatively, you can explicitly enable the +`xpack.security.authc.api_key.enabled` setting. When you are running in +production mode, a bootstrap check prevents you from enabling the API key +service unless you also enable TLS on the HTTP interface. + +A successful grant API key API call returns a JSON structure that contains the +API key, its unique id, and its name. If applicable, it also returns expiration +information for the API key in milliseconds. + +NOTE: By default, API keys never expire. You can specify expiration information +when you create the API keys. + +See <> for configuration settings related to API key +service. + +[[security-api-grant-api-key-request-body]] +==== {api-request-body-title} + +The following parameters can be specified in the body of a POST request: + +`access_token`:: +(Required*, string) +The user's access token. If you specify the `access_token` grant type, this +parameter is required. It is not valid with other grant types. + +`api_key`:: +(Required, object) +Defines the API key. + +`expiration`::: +(Optional, string) Expiration time for the API key. By default, API keys never +expire. + +`name`::: +(Required, string) Specifies the name for this API key. + +`role_descriptors`::: +(Optional, array-of-role-descriptor) An array of role descriptors for this API +key. This parameter is optional. When it is not specified or is an empty array, +the API key has a point in time snapshot of permissions of the specified user or +access token. If you supply role descriptors, the resultant permissions are an +intersection of API keys permissions and the permissions of the user or access +token. The structure of role descriptor is the same as the request for create +role API. For more details, see <>. + +`grant_type':: +(Required, string) +The type of grant. Supported grant types are: `access_token`,`password`. + +`access_token`::: +(Required*, string) +In this type of grant, you must supply an access token that was created by the +{es} token service. For more information, see +<> and <>. + +`password`::: +In this type of grant, you must supply the user ID and password for which you +want to create the API key. + +`password`:: +(Optional*, string) +The user's password. If you specify the `password` grant type, this parameter is +required. It is not valid with other grant types. + +`username`:: +(Optional*, string) +The user name that identifies the user. If you specify the `password` grant type, +this parameter is required. It is not valid with other grant types. + +[[security-api-grant-api-key-example]] +==== {api-examples-title} + +[source,console] +------------------------------------------------------------ +POST /_security/api_key/grant +{ + "grant_type": "password", + "username" : "test_admin", + "password" : "x-pack-test-password" + "api_key" : { + "name": "my-api-key", + "expiration": "1d", + "role_descriptors": { + "role-a": { + "cluster": ["all"], + "index": [ + { + "names": ["index-a*"], + "privileges": ["read"] + } + ] + }, + "role-b": { + "cluster": ["all"], + "index": [ + { + "names": ["index-b*"], + "privileges": ["all"] + } + ] + } + } + } +} +------------------------------------------------------------ From 2ce5722271812121004f011d4e5b1c4ad50f91cc Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 7 Oct 2020 17:02:45 -0700 Subject: [PATCH 2/8] [DOCS] Add rest api spec --- .../api/security.grant_api_key.json | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 x-pack/plugin/src/test/resources/rest-api-spec/api/security.grant_api_key.json diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.grant_api_key.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.grant_api_key.json new file mode 100644 index 0000000000000..89e73abc9a208 --- /dev/null +++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.grant_api_key.json @@ -0,0 +1,34 @@ +{ + "security.grant_api_key":{ + "documentation":{ + "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-grant-api-key.html", + "description":"Creates an API key on behalf of another user for access without requiring basic authentication." + }, + "stability":"stable", + "url":{ + "paths":[ + { + "path":"/_security/api_key/grant", + "methods":[ + "POST" + ] + } + ] + }, + "params":{ + "refresh":{ + "type":"enum", + "options":[ + "true", + "false", + "wait_for" + ], + "description":"If `true` (the default) then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` then do nothing with refreshes." + } + }, + "body":{ + "description":"The api key request to create an API key", + "required":true + } + } +} From 80d21974317343c72aa1fc61b13a79473573901c Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 7 Oct 2020 17:08:46 -0700 Subject: [PATCH 3/8] [DOCS] Add grant_api_key cluster privilege --- x-pack/docs/en/security/authorization/privileges.asciidoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/x-pack/docs/en/security/authorization/privileges.asciidoc b/x-pack/docs/en/security/authorization/privileges.asciidoc index 88f22a2d003a1..e171001db4016 100644 --- a/x-pack/docs/en/security/authorization/privileges.asciidoc +++ b/x-pack/docs/en/security/authorization/privileges.asciidoc @@ -16,6 +16,9 @@ settings update, rerouting, or managing users and roles. Privileges to create snapshots for existing repositories. Can also list and view details on existing repositories and snapshots. +`grant_api_key`:: +Privileges to create {es} API keys on behalf of other users. + `monitor_snapshot`:: Privileges to list and view details on existing repositories and snapshots. From 3bf6841528f7ec88251c1ecb19fe1d5f26693bcc Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 7 Oct 2020 21:58:58 -0700 Subject: [PATCH 4/8] [DOCS] Fixes typo in example --- x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc index 805430279efee..2b02f5ec6982c 100644 --- a/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc +++ b/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc @@ -104,7 +104,7 @@ POST /_security/api_key/grant { "grant_type": "password", "username" : "test_admin", - "password" : "x-pack-test-password" + "password" : "x-pack-test-password", "api_key" : { "name": "my-api-key", "expiration": "1d", From 1bebf25971eeb77b7063478b4b959b451354c625 Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 8 Oct 2020 09:32:05 -0700 Subject: [PATCH 5/8] [DOCS] Fixes typo --- x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc index 2b02f5ec6982c..bce013781ab55 100644 --- a/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc +++ b/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc @@ -71,7 +71,7 @@ intersection of API keys permissions and the permissions of the user or access token. The structure of role descriptor is the same as the request for create role API. For more details, see <>. -`grant_type':: +`grant_type`:: (Required, string) The type of grant. Supported grant types are: `access_token`,`password`. From 131a1ee2f89633677740891c274446643945fb10 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Thu, 15 Oct 2020 12:36:22 -0700 Subject: [PATCH 6/8] Update x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc Co-authored-by: Tim Vernum --- x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc index bce013781ab55..6ce1df5a0cde5 100644 --- a/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc +++ b/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc @@ -5,8 +5,7 @@ Grant API keys ++++ -Creates an API key on behalf of another user for access without requiring basic -authentication. +Creates an API key on behalf of another user. [[security-api-grant-api-key-request]] ==== {api-request-title} From cb011c0949227a2b67280cb39915e43ad5e70277 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Thu, 15 Oct 2020 12:37:10 -0700 Subject: [PATCH 7/8] Update x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc Co-authored-by: Tim Vernum --- x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc index 6ce1df5a0cde5..2b1b3fec831fc 100644 --- a/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc +++ b/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc @@ -23,6 +23,9 @@ Creates an API key on behalf of another user. This API is similar to <>, however it creates the API key for a user that is different than the user that runs the API. +The caller must have authentication credentials (either an access token, or a username and password) for the user on whose behalf the API key will be created. It is not possible to use this API to create an API key without that user's credentials. + +This API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf (see <>). The API keys are created by the {es} API key service, which is automatically enabled when you configure TLS on the HTTP interface. See <>. Alternatively, you can explicitly enable the From 0ea2e3be9623f0e1e375f5447a1cb6b22bee2122 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Thu, 15 Oct 2020 12:38:49 -0700 Subject: [PATCH 8/8] Update x-pack/plugin/src/test/resources/rest-api-spec/api/security.grant_api_key.json --- .../resources/rest-api-spec/api/security.grant_api_key.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.grant_api_key.json b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.grant_api_key.json index 89e73abc9a208..a64f0366a54b8 100644 --- a/x-pack/plugin/src/test/resources/rest-api-spec/api/security.grant_api_key.json +++ b/x-pack/plugin/src/test/resources/rest-api-spec/api/security.grant_api_key.json @@ -2,7 +2,7 @@ "security.grant_api_key":{ "documentation":{ "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-grant-api-key.html", - "description":"Creates an API key on behalf of another user for access without requiring basic authentication." + "description":"Creates an API key on behalf of another user." }, "stability":"stable", "url":{