Building a custom authenticator
The OpenTelemetry Collector allows receivers and exporters to be connected to authenticators, providing a way to both authenticate incoming connections at the receiver’s side, as well as adding authentication data to outgoing requests at the exporter’s side.
This mechanism is implemented on top of the
framework and this document will guide you on implementing your own
authenticators. If you are looking for documentation on how to use an existing
authenticator, refer to the Getting Started page and to your authenticator’s
documentation. You can find a list of existing authenticators in this website’s
Use this guide for general directions on how to build a custom authenticator and refer to the up-to-date API Reference Guide for the actual semantics of each type and function.
If at anytime you need assistance, join the #opentelemetry-collector room at the CNCF Slack workspace.
Authenticators are regular extensions that also satisfy one or more interfaces related to the authentication mechanism:
Server authenticators are used with receivers, and are able to intercept HTTP and gRPC requests, while client authenticators are used with exporters, able to add authentication data to HTTP and gRPC requests. It is possible for authenticators to implement both interfaces at the same time, allowing a single instance of the extension to be used both for the incoming and outgoing requests. Note that users might still want to have different authenticators for the incoming and outgoing requests, so, don’t make your authenticator required to be used at both ends.
Once an authenticator extension is available in the collector distribution, it can be referenced in the configuration file as a regular extension:
extensions: oidc: receivers: processors: exporters: service: extensions: - oidc pipelines: traces: receivers:  processors:  exporters: 
However, an authenticator will need to be referenced by a consuming component to
be effective. The following example shows the same extension as above, now being
used by a receiver named
extensions: oidc: receivers: otlp/auth: protocols: grpc: auth: authenticator: oidc processors: exporters: service: extensions: - oidc pipelines: traces: receivers: - otlp/auth processors:  exporters: 
When multiple instances of a given authenticator are needed, they can have different names:
extensions: oidc/some-provider: oidc/another-provider: receivers: otlp/auth: protocols: grpc: auth: authenticator: oidc/some-provider processors: exporters: service: extensions: - oidc/some-provider - oidc/another-provider pipelines: traces: receivers: - otlp/auth processors:  exporters: 
A server authenticator is essentially an extension with an
function, receiving the payload headers as parameter. If the authenticator is
able to authenticate the incoming connection, it should return a
nil error, or
the concrete error if it can’t. As an extension, the authenticator should make
sure to initialize all the resources it needs during the
phase, and is expected to clean them up upon
Authenticate call is part of the hot path for incoming requests and will
block the pipeline, so make sure to properly handle any blocking operations you
need to make. Concretely, respect the deadline set by the context, in case one
is provided. Also make sure to add enough observability to your extension,
especially in the form of metrics and traces, so that users can get setup a
notification system in case error rates go up beyond a certain level and can
debug specific failures.
A client authenticator is one that implements one or more of the following interfaces:
Similar to server authenticators, they are essentially extensions with extra
functions, each receiving an object that gives the authenticator an opportunity
to inject the authentication data into. For instance, the HTTP client
authenticator provides an
http.RoundTripper, while the gRPC
client authenticator can produce a
Adding your custom authenticator to a distribution
Custom authenticators have to be part of the same binary as the main collector. When building your own authenticator, you’ll likely have to build a custom distribution as well, or provide means for your users to consume your extension as part of their own distributions. Fortunately, building a custom distribution can be done using the OpenTelemetry Collector Builder utility.