Building an authenticator extension

The OpenTelemetry Collector allows you to connect receivers and exporters to authenticators so you can authenticate incoming connections at the receiver side and add authentication data to outgoing requests at the exporter side.

Authenticators are implemented through extensions. This document guides you on implementing your own authenticators. If you want to learn how to use an existing authenticator, see the documentation for that specific authenticator. You can find a list of existing authenticators in the registry on this website.

Use this guide for general directions on how to build a custom authenticator and see the API Reference Guide for the semantics of each type and function.

If you need help, join the #opentelemetry-collector-dev channel at the CNCF Slack workspace.

Architecture

Authenticators in OpenTelemetry are just like any other extension, but they also have to implement one or more specific interfaces that define how authentication is performed (for example, authenticating HTTP or gRPC requests). Use server authenticators with receivers to intercept HTTP and gRPC requests. Use client authenticators with exporters to add authentication data to HTTP and gRPC requests. Authenticators can also implement both interfaces at the same time, allowing a single instance of the extension to handle both incoming and outgoing requests.

Once an authenticator extension is available in a Collector distribution, you can reference it in the configuration file the same as other extensions. However, an authenticator is effective only when it’s referenced by a consuming component. The following configuration shows a receiver named otlp/auth using the oidc authenticator extension:

extensions:
  oidc:

receivers:
  otlp/auth:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
        auth:
          authenticator: oidc

processors:
exporters:

service:
  extensions:
    - oidc
  pipelines:
    traces:
      receivers:
        - otlp/auth
      processors: []
      exporters: []

If you need multiple instances of an authenticator, give them different names:

extensions:
  oidc/some-provider:
  oidc/another-provider:

receivers:
  otlp/auth:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
        auth:
          authenticator: oidc/some-provider

processors:
exporters:

service:
  extensions:
    - oidc/some-provider
    - oidc/another-provider
  pipelines:
    traces:
      receivers:
        - otlp/auth
      processors: []
      exporters: []

Server authenticators

A server authenticator is an extension with an Authenticate method. This function is called whenever a request comes in, and it checks the request’s headers to authenticate the request. If the authenticator decides the request is valid, it returns a nil error. If the request isn’t valid, it returns an error explaining why.

Because it’s an extension, the authenticator should set up the resources it needs (like keys, clients, or caches) at Start and should clean everything up at Shutdown.

The Authenticate function runs for every incoming request, and the pipeline can’t move forward until this function finishes. Because of that, your authenticator must avoid slow or unnecessary blocking work. If the context sets a deadline, make sure your code follows it so the pipeline isn’t delayed or left hanging.

You should also add good observability to your authenticator, especially metrics and traces. This helps users set up alerts if errors start increasing and makes it easier for them to troubleshoot authentication problems.

Client authenticators

Client authenticators are extensions with extra functions that implement one or more of the defined interfaces. Each authenticator receives an object that allows it to inject authentication data. For instance, the HTTP client authenticator provides an http.RoundTripper, while the gRPC client authenticator can produce a credentials.PerRPCCredentials.

Add your custom authenticator to a distribution

Custom authenticators must be part of the same binary as the Collector itself. When building your own authenticator, you have two options:

• You can build a custom Collector distribution using the OpenTelemetry Collector Builder
• You can provide a way, such as publishing a Go module, for users to add your extension to their own distributions.