From a16f1c59f583ac7405cccb18d5c326ef9c29f500 Mon Sep 17 00:00:00 2001 From: David Kilfoyle Date: Thu, 5 Sep 2024 13:24:18 -0400 Subject: [PATCH 1/4] Fix up enrollment token docs --- .../security/enrollment-tokens.asciidoc | 21 +++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/en/ingest-management/security/enrollment-tokens.asciidoc b/docs/en/ingest-management/security/enrollment-tokens.asciidoc index 6634434bd..39d194e50 100644 --- a/docs/en/ingest-management/security/enrollment-tokens.asciidoc +++ b/docs/en/ingest-management/security/enrollment-tokens.asciidoc @@ -1,8 +1,9 @@ [[fleet-enrollment-tokens]] = {fleet} enrollment tokens -A {fleet} enrollment token is an {es} API key that you use to enroll one or more -{agent}s in {fleet}. The enrollment token enrolls the {agent} in a specific +A {fleet} enrollment token (also referred to as an `enrollment API key` ) +is an {es} API key that you use to enroll one or more {agent}s in {fleet}. +The enrollment token enrolls the {agent} in a specific agent policy that defines the data to be collected by the agent. You can use the token as many times as required. It will remain valid until you revoke it. @@ -38,6 +39,8 @@ To create an enrollment token: . Click **Create enrollment token**. Name your token and select an agent policy. + +Note that the token name you specify must be unique so as to avoid conflict with any existing API keys. ++ [role="screenshot"] image::images/create-token.png[Enrollment tokens tab in {fleet}] @@ -61,6 +64,9 @@ information, refer to <>. [[revoke-fleet-enrollment-tokens]] == Revoke enrollment tokens +You can revoke an enrollment token that you no longer wish to use to enroll {agents} in an agent policy in {fleet}. +Revoking an enrollment token essentially invalidates the API key used by agents to communicate with {fleet-server}. + To revoke an enrollment token: . In {fleet}, click **Enrollment tokens**. @@ -75,3 +81,14 @@ image::images/revoke-token.png[Enrollment tokens tab with Revoke token highlight {agent}s. However, the currently enrolled agents will continue to function. To re-enroll your {agent}s, use an active enrollment token. + +Note that when an enrollment token is revoked it is not immediately deleted. +Deletion occurs automatically after the duration specified in the {es} +{ref}/security-settings.html#api-key-service-settings-delete-retention-period[`xpack.security.authc.api_key.delete.retention_period`] setting has expired. +Until the enrollment token has been deleted, the token name may not be re-used when you <>. + +As well, until an enrollment token has been deleted: + +* It continues to be visible in the {fleet} UI. +* It continues to be returned by a `GET /api/fleet/enrollment_api_keys` API request. Revoked enrollment tokens are identified as `"active": false`. + From 35dcbb40ac6c49b79fc6fe3ad8608d71f332d789 Mon Sep 17 00:00:00 2001 From: David Kilfoyle Date: Thu, 5 Sep 2024 13:33:54 -0400 Subject: [PATCH 2/4] fixup --- docs/en/ingest-management/security/enrollment-tokens.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/ingest-management/security/enrollment-tokens.asciidoc b/docs/en/ingest-management/security/enrollment-tokens.asciidoc index 39d194e50..de9dd8636 100644 --- a/docs/en/ingest-management/security/enrollment-tokens.asciidoc +++ b/docs/en/ingest-management/security/enrollment-tokens.asciidoc @@ -1,7 +1,7 @@ [[fleet-enrollment-tokens]] = {fleet} enrollment tokens -A {fleet} enrollment token (also referred to as an `enrollment API key` ) +A {fleet} enrollment token (referred to as an `enrollment API key` in the {fleet} API documentation) is an {es} API key that you use to enroll one or more {agent}s in {fleet}. The enrollment token enrolls the {agent} in a specific agent policy that defines the data to be collected by the agent. You can From 909dc677baa72a77a8704212f1588d106e85f44d Mon Sep 17 00:00:00 2001 From: David Kilfoyle Date: Thu, 5 Sep 2024 13:42:39 -0400 Subject: [PATCH 3/4] fixup --- .../security/enrollment-tokens.asciidoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/en/ingest-management/security/enrollment-tokens.asciidoc b/docs/en/ingest-management/security/enrollment-tokens.asciidoc index de9dd8636..d94f02e4e 100644 --- a/docs/en/ingest-management/security/enrollment-tokens.asciidoc +++ b/docs/en/ingest-management/security/enrollment-tokens.asciidoc @@ -79,16 +79,16 @@ image::images/revoke-token.png[Enrollment tokens tab with Revoke token highlight . Click **Revoke enrollment token**. You can no longer use this token to enroll {agent}s. However, the currently enrolled agents will continue to function. - ++ To re-enroll your {agent}s, use an active enrollment token. Note that when an enrollment token is revoked it is not immediately deleted. Deletion occurs automatically after the duration specified in the {es} {ref}/security-settings.html#api-key-service-settings-delete-retention-period[`xpack.security.authc.api_key.delete.retention_period`] setting has expired. -Until the enrollment token has been deleted, the token name may not be re-used when you <>. - -As well, until an enrollment token has been deleted: -* It continues to be visible in the {fleet} UI. -* It continues to be returned by a `GET /api/fleet/enrollment_api_keys` API request. Revoked enrollment tokens are identified as `"active": false`. +Until the enrollment token has been deleted: +* The token name may not be re-used when you <>. +* The token continues to be visible in the {fleet} UI. +* The token continues to be returned by a `GET /api/fleet/enrollment_api_keys` API request. +Revoked enrollment tokens are identified as `"active": false`. From f58520500e58fa50f59174fbd7ef0bf91b21b11d Mon Sep 17 00:00:00 2001 From: David Kilfoyle Date: Tue, 10 Sep 2024 10:01:30 -0400 Subject: [PATCH 4/4] Add link to 'Invalidate API key API' --- docs/en/ingest-management/security/enrollment-tokens.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/ingest-management/security/enrollment-tokens.asciidoc b/docs/en/ingest-management/security/enrollment-tokens.asciidoc index d94f02e4e..f9c41d1b3 100644 --- a/docs/en/ingest-management/security/enrollment-tokens.asciidoc +++ b/docs/en/ingest-management/security/enrollment-tokens.asciidoc @@ -84,7 +84,7 @@ To re-enroll your {agent}s, use an active enrollment token. Note that when an enrollment token is revoked it is not immediately deleted. Deletion occurs automatically after the duration specified in the {es} -{ref}/security-settings.html#api-key-service-settings-delete-retention-period[`xpack.security.authc.api_key.delete.retention_period`] setting has expired. +{ref}/security-settings.html#api-key-service-settings-delete-retention-period[`xpack.security.authc.api_key.delete.retention_period`] setting has expired (see {ref}/security-api-invalidate-api-key.html[Invalidate API key API] for details). Until the enrollment token has been deleted: