Loading

Authentication methods for the EDOT Collector

Stack Serverless

The Elastic Distribution of OpenTelemetry Collector supports multiple authentication methods to secure connections and ensure only authorized clients can send telemetry data. This guide covers the available authentication extensions and how to configure them.

Authentication in the EDOT Collector is handled through extensions that implement the extensionauth interface. These extensions can be used to:

  • Authenticate incoming requests from SDKs and other collectors.
  • Authenticate outgoing requests to external services.

The EDOT Collector supports the following authentication extensions:

The apikeyauth extension is an Elastic-specific authentication method that validates Elasticsearch API keys against your Elasticsearch cluster. This extension is ideal for authenticating requests from EDOT SDKs and other Collectors that use Elasticsearch API keys.

The bearertokenauth extension is an contrib OpenTelemetry authentication method that supports static bearer tokens. This extension is useful for token-based authentication scenarios.

These examples show how to configure the apikeyauth and bearertokenauth extensions.

Configure the apikeyauth extension to authenticate incoming requests:

extensions:
  apikeyauth:
    endpoint: "https://example.com:9200"
    application_privileges:
      - application: "apm"
        privileges: ["config_agent:read"]
        resources: ["*"]
    cache:
      capacity: 1000
      ttl: "5m"
      pbkdf2_iterations: 10000
      key_headers: ["X-Tenant-Id"]

receivers:
  otlp:
    protocols:
      grpc:
        auth:
          authenticator: apikeyauth
      http:
        auth:
          authenticator: apikeyauth

service:
  extensions: [apikeyauth]

The following configuration options are available for the apikeyauth extension:

Option Type Description Default
endpoint string The Elasticsearch endpoint for API key validation Required
application_privileges array List of required application privileges and resources Required
application_privileges.application string Name of the application for which privileges are defined ""
application_privileges.privileges array List of application-specific privileges that the API Key must have to be considered valid []
application_privileges.resources array List of application-specific resources that the API Key must have access to be considered valid []
cache.capacity integer Maximum number of cached entries 1000
cache.ttl duration Time-to-live for cached entries 30s
cache.pbkdf2_iterations integer Number of PBKDF2 iterations for key derivation 10000
cache.key_headers array Optional headers to include in cache key generation []

Configure the bearertokenauth extension for bearer token-based authentication:

extensions:
  bearertokenauth:
    scheme: "Bearer"
    token: "your-secret-token"
    header: "Authorization"

receivers:
  otlp:
    protocols:
      grpc:
        auth:
          authenticator: bearertokenauth
      http:
        auth:
          authenticator: bearertokenauth

service:
  extensions: [bearertokenauth]

The following configuration options are available for the bearertokenauth extension:

Option Type Description Default
scheme string Authentication scheme "Bearer"
token string Static token for authentication. Only required if tokens is an empty list and filename is empty. ""
tokens string array List of multiple tokens. Only required if token and filename are empty. []
filename string Path to file containing the token, required if token and tokens are left unset. ""
header string Custom header name "Authorization"

For enhanced security, store tokens in files instead of configuration:

extensions:
  bearertokenauth:
    scheme: "Bearer"
    filename: "/path/to/token/file"
    header: "Authorization"

service:
  extensions: [bearertokenauth]

The extension automatically monitors the token file for changes and reloads the token when the file is modified.

These use cases show how to configure the apikeyauth and bearertokenauth extensions for different scenarios.

When using EDOT SDKs, configure the apikeyauth extension to validate API keys:

extensions:
  apikeyauth:
    endpoint: "${ELASTIC_ENDPOINT}"
    application_privileges:
      - application: "apm"
        privileges: ["config_agent:read"]
        resources: ["*"]

receivers:
  otlp:
    protocols:
      grpc:
        auth:
          authenticator: apikeyauth
      http:
        auth:
          authenticator: apikeyauth

Use bearer token authentication for secure communication between collectors:

extensions:
  bearertokenauth:
    scheme: "Collector"
    token: "collector-secret-token"

receivers:
  otlp:
    protocols:
      grpc:
        auth:
          authenticator: bearertokenauth

For multi-tenant environments, use the apikeyauth extension with tenant-specific headers:

extensions:
  apikeyauth:
    endpoint: "${ELASTIC_ENDPOINT}"
    application_privileges:
      - application: "apm"
        privileges: ["config_agent:read"]
        resources: ["*"]
    cache:
      key_headers: ["X-Tenant-Id", "X-Organization-Id"]

In general, be aware of the following security considerations:

  • Store API keys securely using environment variables or secret management systems.
  • Use the minimum required privileges for API keys.
  • Regularly rotate API keys.
  • Monitor API key usage and access patterns.
  • Use strong, randomly generated tokens.
  • Store tokens in secure files with appropriate permissions.
  • Avoid hardcoding tokens in configuration files.
  • Consider using token rotation mechanisms.

The following issues might occur.

API key validation failures
  • Verify the Elasticsearch endpoint is accessible.
  • Check API key permissions and application privileges.
  • Ensure the API key is valid and not expired.
  • Verify network connectivity and firewall rules.
Bearer token authentication failures
  • Confirm the token is correct and not expired.
  • Check the authentication scheme matches expectations.
  • Verify the token file exists and is readable.
  • Ensure the custom header is properly configured.