Clarifies EDOT SDK authentication using API keys (#11170) (#11502)

* Clarifies EDOT SDK authentication using API keys

* Remove snippet

(cherry picked from commit 15bc3df)

Co-authored-by: Aleksandra Spilkowska <[email protected]>

Author: mergify[bot]

docs/reference/edot-collector/_snippets/edot-collector-auth.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 <Base64(id:key)>`).
+
+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:

docs/reference/edot-collector/config/authentication-methods.md

@@ -291,10 +291,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 <Base64(id:key)>`).
+
+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
 
@@ -323,25 +345,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: "<YOUR_ELASTICSEARCH_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: