From 33cf937c04d661a7730a9cf4c835175278c2765a Mon Sep 17 00:00:00 2001 From: Aleksandra Spilkowska Date: Thu, 13 Nov 2025 16:49:54 +0100 Subject: [PATCH] Clarifies EDOT SDK authentication using API keys --- .../config/authentication-methods.md | 60 +++++++++++++++++-- .../config/default-config-standalone.md | 40 +++++++++---- 2 files changed, 86 insertions(+), 14 deletions(-) diff --git a/docs/reference/edot-collector/config/authentication-methods.md b/docs/reference/edot-collector/config/authentication-methods.md index d7aae469151..61efdc16189 100644 --- a/docs/reference/edot-collector/config/authentication-methods.md +++ b/docs/reference/edot-collector/config/authentication-methods.md @@ -27,11 +27,11 @@ Authentication in the EDOT Collector is handled through extensions that implemen The EDOT Collector supports the following authentication extensions: -### Elastic API Key Authentication (`apikeyauth`) +### Elastic API key authentication (`apikeyauth`) The `apikeyauth` extension is an Elastic-specific authentication method that validates Elasticsearch API keys against your {{es}} cluster. This extension is ideal for authenticating requests from EDOT SDKs and other Collectors that use Elasticsearch API keys. -### Bearer Token Authentication (`bearertokenauth`) +### Bearer token authentication (`bearertokenauth`) The `bearertokenauth` extension is an contrib OpenTelemetry authentication method that supports static bearer tokens. This extension is useful for token-based authentication scenarios. @@ -71,6 +71,44 @@ service: extensions: [apikeyauth] ``` +#### Using `apikeyauth` with EDOT SDKs and central configuration + +The `apikeyauth` authenticator is also used by the `apmconfig` extension when EDOT SDKs retrieve central configuration from the EDOT Collector. + +EDOT SDKs send their own {{es}} API key to the Collector in the `Authorization` header (for example: `Authorization: ApiKey `). + +The Collector does not store or embed the API key. Instead, the `apikeyauth` extension validates the incoming key by calling {{es}} and checking that it has: + +* `application: "apm"` + +* privilege: `config_agent:read` + +* `resources: ["*"]` + +A minimal configuration for this use case looks like: + +```yaml +extensions: + apikeyauth: + endpoint: "${ELASTIC_ENDPOINT}" + application_privileges: + - application: "apm" + privileges: ["config_agent:read"] + resources: ["*"] + + apmconfig: + opamp: + protocols: + http: + auth: + authenticator: apikeyauth + +service: + extensions: [apikeyauth] +``` + +Use `resources: ["*"]` to grant read access for all APM services. A literal dash (`"-"`) is not valid. + #### Configuration options The following configuration options are available for the `apikeyauth` extension: @@ -147,7 +185,9 @@ These use cases show how to configure the `apikeyauth` and `bearertokenauth` ext ### Authenticating EDOT SDKs -When using EDOT SDKs, configure the `apikeyauth` extension to validate API keys: +When EDOT SDKs retrieve central configuration from the Collector, they authenticate using an {{es}} API key. The Collector validates this key using the `apikeyauth` extension. + +For example: ```yaml subs=true extensions: @@ -172,6 +212,18 @@ service: extensions: [apikeyauth] ``` +::::{note} +EDOT SDKs authenticate by sending their API key in the `Authorization` header. The EDOT Collector doesn't store the API key, it only validates it. + +Ensure the API key has: + +* `application: "apm"` +* `privileges: ["config_agent:read"]` +* `resources: ["*"]` + +These privileges allow SDKs to read their central configuration through the Collector. +:::: + ### Securing collector-to-collector communication Use bearer token authentication for secure communication between collectors: @@ -195,7 +247,7 @@ service: ### Multi-tenant authentication -For multi-tenant environments, use the `apikeyauth` extension with tenant-specific headers: +For multi-tenant environments, use the `apikeyauth` extension with additional cache key headers to ensure privileges are validated for each tenant: ```yaml subs=true extensions: diff --git a/docs/reference/edot-collector/config/default-config-standalone.md b/docs/reference/edot-collector/config/default-config-standalone.md index 13f0361d708..acb93a12e9f 100644 --- a/docs/reference/edot-collector/config/default-config-standalone.md +++ b/docs/reference/edot-collector/config/default-config-standalone.md @@ -282,10 +282,32 @@ The EDOT Collector can be configured to use [APM Agent Central Configuration](do To activate the central configuration feature, add the [`apmconfig`](https://github.com/elastic/opentelemetry-collector-components/blob/main/extension/apmconfigextension/README.md). For example: -:::{include} ../_snippets/edot-collector-auth.md -::: +```yaml +extensions: + apikeyauth: + endpoint: "${ELASTIC_ENDPOINT}" + application_privileges: + - application: "apm" + privileges: ["config_agent:read"] + resources: ["*"] + + apmconfig: + opamp: + protocols: + http: + auth: + authenticator: apikeyauth +``` + +::::{note} +The EDOT Collector doesn't store or embed the {{es}} API key. -Create an API Key following [these instructions](docs-content://deploy-manage/api-keys/elasticsearch-api-keys.md). The API key must have `config_agent:read` permissions and resources set to `-`. +Each EDOT SDK sends its own API key in the `Authorization` header (for example: `Authorization: ApiKey `). + +The `apikeyauth` extension only validates incoming API keys against {{es}}, ensuring they include the `apm` to `config_agent:read` privilege and `resources: ["*"]`. +:::: + +Create an API Key following [these instructions](docs-content://deploy-manage/api-keys/elasticsearch-api-keys.md). The API key must include the application privilege `config_agent:read` with resources set to `"*"`. ## Secure connection @@ -314,25 +336,23 @@ extensions: In addition to TLS, you can configure authentication to ensure that only authorized agents can communicate with the extension and retrieve their corresponding remote configurations. -The `apmconfig` extension supports any configauth authenticator. Use the `apikeyauth` extension to authenticate with Elasticsearch API keys: +The `apmconfig` extension supports any `configauth` authenticator. Use the `apikeyauth` extension to authenticate with {{es}} API keys: ```yaml extensions: apikeyauth: - endpoint: "" + endpoint: "${ELASTIC_ENDPOINT}" application_privileges: - application: "apm" - privileges: - - "config_agent:read" - resources: - - "-" + privileges: ["config_agent:read"] + resources: ["*"] + apmconfig: opamp: protocols: http: auth: authenticator: apikeyauth - ... ``` Create an API key with the minimum required application permissions through {{kib}} under **Observability** → **Applications** → **Settings** → **Agent Keys**, or by using the Elasticsearch Security API: