From 238a459b77a72da5c00bf0148aad8a02db8d0f2f Mon Sep 17 00:00:00 2001
From: Tim Vernum <tim@adjective.org>
Date: Tue, 15 Sep 2020 13:26:49 +1000
Subject: [PATCH 1/3] Add warning about derived API keys to docs
This updates the Create API Key reference document with
information about the limitations of derived API keys.
Since ES v7.6.0, API keys that are created from an API key (what we
refer to as "derived API keys" must be created with an empty
privileges list (to explicitly match the effective behaviour of all
earlier versions).
This information was included in the release notes, but didn't get
added to the API reference.
Relates: #53647, #54522, #60154
---
.../docs/en/rest-api/security/create-api-keys.asciidoc | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc
index aea9e47c220f2..1490ca13f0de0 100644
--- a/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc
+++ b/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc
@@ -19,6 +19,10 @@ Creates an API key for access without requiring basic authentication.
* To use this API, you must have at least the `manage_api_key` cluster privilege.
+IMPORTANT: If the credential that is used to authenticate this request is
+an API key, then the derived API key that is created cannot have any privileges.
+See the note under `role_descriptors`.
+
[[security-api-create-api-key-desc]]
==== {api-description-title}
@@ -57,6 +61,12 @@ thereby limiting the access scope for API keys.
The structure of role descriptor is the same as the request for create role API.
For more details, see <<security-api-put-role, create or update roles API>>.
+NOTE: Due to the way in which this permission intersection is calculated, it is not
+possible to create an API key that is a child of another API key, unless the derived
+key is created without any privileges. In this case, you must explicitly specify a
+role descriptor with no privileges, and the derived API key can be used for
+authentication only, but will not have access to call {es} APIs.
+
`expiration`::
(Optional, string) Expiration time for the API key. By default, API keys never
expire.
From b885b3a9ce4fc0321ea5340235924ed7b10d98f9 Mon Sep 17 00:00:00 2001
From: lcawl <lcawley@elastic.co>
Date: Tue, 15 Sep 2020 11:03:43 -0700
Subject: [PATCH 2/3] [DOCS] Nests admonition block
---
x-pack/docs/en/rest-api/security/create-api-keys.asciidoc | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc
index 1490ca13f0de0..cf68d28c968b9 100644
--- a/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc
+++ b/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc
@@ -60,13 +60,16 @@ would be an intersection of API keys permissions and authenticated user's permis
thereby limiting the access scope for API keys.
The structure of role descriptor is the same as the request for create role API.
For more details, see <<security-api-put-role, create or update roles API>>.
-
++
+--
NOTE: Due to the way in which this permission intersection is calculated, it is not
possible to create an API key that is a child of another API key, unless the derived
key is created without any privileges. In this case, you must explicitly specify a
role descriptor with no privileges, and the derived API key can be used for
authentication only, but will not have access to call {es} APIs.
+--
+
`expiration`::
(Optional, string) Expiration time for the API key. By default, API keys never
expire.
From 03c35a57476a827312f8a46ee34247e29bce191e Mon Sep 17 00:00:00 2001
From: Tim Vernum <tim@adjective.org>
Date: Thu, 17 Sep 2020 22:03:09 +1000
Subject: [PATCH 3/3] Apply suggestions from code review
Co-authored-by: Lisa Cawley <lcawley@elastic.co>
---
x-pack/docs/en/rest-api/security/create-api-keys.asciidoc | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc
index cf68d28c968b9..b9a22b5fb621e 100644
--- a/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc
+++ b/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc
@@ -20,7 +20,7 @@ Creates an API key for access without requiring basic authentication.
* To use this API, you must have at least the `manage_api_key` cluster privilege.
IMPORTANT: If the credential that is used to authenticate this request is
-an API key, then the derived API key that is created cannot have any privileges.
+an API key, the derived API key cannot have any privileges. If you specify privileges, the API returns an error.
See the note under `role_descriptors`.
[[security-api-create-api-key-desc]]
@@ -65,8 +65,8 @@ For more details, see <<security-api-put-role, create or update roles API>>.
NOTE: Due to the way in which this permission intersection is calculated, it is not
possible to create an API key that is a child of another API key, unless the derived
key is created without any privileges. In this case, you must explicitly specify a
-role descriptor with no privileges, and the derived API key can be used for
-authentication only, but will not have access to call {es} APIs.
+role descriptor with no privileges. The derived API key can be used for
+authentication; it will not have authority to call {es} APIs.
--