configauth

README

Authentication configuration

This module defines necessary interfaces to implement server and client type authenticators:

• Server type authenticators perform authentication for incoming HTTP/gRPC requests and are typically used in receivers.
• Client type authenticators perform client-side authentication for outgoing HTTP/gRPC requests and are typically used in exporters.

The currently known authenticators are:

• Server Authenticators

  • oidc

• Client Authenticators

  • oauth2
  • BearerToken

Examples:

extensions:
  oidc:
    # see the blog post on securing the otelcol for information
    # on how to setup an OIDC server and how to generate the TLS certs
    # required for this example
    # https://medium.com/opentelemetry/securing-your-opentelemetry-collector-1a4f9fa5bd6f
    issuer_url: http://localhost:8080/auth/realms/opentelemetry
    audience: account

  oauth2client:
    client_id: someclientid
    client_secret: someclientsecret
    token_url: https://example.com/oauth2/default/v1/token
    scopes: ["api.metrics"]
    # tls settings for the token client
    tls:
      insecure: true
      ca_file: /var/lib/mycert.pem
      cert_file: certfile
      key_file: keyfile
    # timeout for the token client
    timeout: 2s

receivers:
  otlp/with_auth:
    protocols:
      grpc:
        endpoint: localhost:4318
        tls:
          cert_file: /tmp/certs/cert.pem
          key_file: /tmp/certs/cert-key.pem
        auth:
          ## oidc is the extension name to use as the authenticator for this receiver
          authenticator: oidc

  otlphttp/withauth:
    endpoint: http://localhost:9000
    auth:
      authenticator: oauth2client

Creating an authenticator

New authenticators can be added by creating a new extension that also implements the appropriate interface (configauth.ServerAuthenticator or configauth.ClientAuthenticator).

Generic authenticators that may be used by a good number of users might be accepted as part of the contrib distribution. If you have an interest in contributing an authenticator, open an issue with your proposal. For other cases, you'll need to include your custom authenticator as part of your custom OpenTelemetry Collector, perhaps being built using the OpenTelemetry Collector Builder.

Documentation

Overview

Package configauth implements the configuration settings to ensure authentication on incoming requests, and allows exporters to add authentication on outgoing requests.

Index

• type AuthenticateFunc
• type Authentication
  • func (a Authentication) GetClientAuthenticator(extensions map[component.ID]component.Extension) (ClientAuthenticator, error)
  • func (a Authentication) GetServerAuthenticator(extensions map[component.ID]component.Extension) (ServerAuthenticator, error)
• type ClientAuthenticator
  • func NewClientAuthenticator(options ...ClientOption) ClientAuthenticator
• type ClientOption
  • func WithClientRoundTripper(roundTripperFunc func(base http.RoundTripper) (http.RoundTripper, error)) ClientOption
  • func WithClientShutdown(shutdownFunc component.ShutdownFunc) ClientOption
  • func WithClientStart(startFunc component.StartFunc) ClientOption
  • func WithPerRPCCredentials(perRPCCredentialsFunc func() (credentials.PerRPCCredentials, error)) ClientOption
• type MockClientAuthenticator
  • func (m *MockClientAuthenticator) PerRPCCredentials() (credentials.PerRPCCredentials, error)
  • func (m *MockClientAuthenticator) RoundTripper(base http.RoundTripper) (http.RoundTripper, error)
  • func (m *MockClientAuthenticator) Shutdown(ctx context.Context) error
  • func (m *MockClientAuthenticator) Start(ctx context.Context, host component.Host) error
• type Option
  • func WithAuthenticate(authenticateFunc AuthenticateFunc) Option
  • func WithShutdown(shutdownFunc component.ShutdownFunc) Option
  • func WithStart(startFunc component.StartFunc) Option
• type ServerAuthenticator
  • func NewServerAuthenticator(options ...Option) ServerAuthenticator

Types

type AuthenticateFunc

type AuthenticateFunc func(ctx context.Context, headers map[string][]string) (context.Context, error)

AuthenticateFunc defines the signature for the function responsible for performing the authentication based on the given headers map. See ServerAuthenticator.Authenticate.

type Authentication

type Authentication struct {
	// AuthenticatorID specifies the name of the extension to use in order to authenticate the incoming data point.
	AuthenticatorID component.ID `mapstructure:"authenticator"`
}

Authentication defines the auth settings for the receiver.

func (Authentication) GetClientAuthenticator

func (a Authentication) GetClientAuthenticator(extensions map[component.ID]component.Extension) (ClientAuthenticator, error)

GetClientAuthenticator attempts to select the appropriate ClientAuthenticator from the list of extensions, based on the component id of the extension. If an authenticator is not found, an error is returned. This should be only used by HTTP clients.

func (Authentication) GetServerAuthenticator

func (a Authentication) GetServerAuthenticator(extensions map[component.ID]component.Extension) (ServerAuthenticator, error)

GetServerAuthenticator attempts to select the appropriate ServerAuthenticator from the list of extensions, based on the requested extension name. If an authenticator is not found, an error is returned.

type ClientAuthenticator

type ClientAuthenticator interface {
	component.Extension

	// RoundTripper returns a RoundTripper that can be used to authenticate HTTP requests.
	RoundTripper(base http.RoundTripper) (http.RoundTripper, error)

	// PerRPCCredentials returns a PerRPCCredentials that can be used to authenticate gRPC requests.
	PerRPCCredentials() (credentials.PerRPCCredentials, error)
}

ClientAuthenticator is an Extension that can be used as an authenticator for the configauth.Authentication option. Authenticators are then included as part of OpenTelemetry Collector builds and can be referenced by their names from the Authentication configuration.

func NewClientAuthenticator

func NewClientAuthenticator(options ...ClientOption) ClientAuthenticator

NewClientAuthenticator returns a ClientAuthenticator configured with the provided options.

type ClientOption

type ClientOption func(*defaultClientAuthenticator)

Option represents the possible options for NewServerAuthenticator.

func WithClientRoundTripper

func WithClientRoundTripper(roundTripperFunc func(base http.RoundTripper) (http.RoundTripper, error)) ClientOption

WithClientRoundTripper provides a `RoundTripper` function for this client authenticator. The default round tripper is no-op.

func WithClientShutdown

func WithClientShutdown(shutdownFunc component.ShutdownFunc) ClientOption

WithClientShutdown overrides the default `Shutdown` function for a component.Component. The default always returns nil.

func WithClientStart

func WithClientStart(startFunc component.StartFunc) ClientOption

WithClientStart overrides the default `Start` function for a component.Component. The default always returns nil.

func WithPerRPCCredentials

func WithPerRPCCredentials(perRPCCredentialsFunc func() (credentials.PerRPCCredentials, error)) ClientOption

WithPerRPCCredentials provides a `PerRPCCredentials` function for this client authenticator. There's no default.

type MockClientAuthenticator

type MockClientAuthenticator struct {
	ResultRoundTripper      http.RoundTripper
	ResultPerRPCCredentials credentials.PerRPCCredentials
	MustError               bool
}

MockClientAuthenticator provides a mock implementation of GRPCClientAuthenticator and HTTPClientAuthenticator interfaces

func (*MockClientAuthenticator) PerRPCCredentials

func (m *MockClientAuthenticator) PerRPCCredentials() (credentials.PerRPCCredentials, error)

PerRPCCredentials for the MockClientAuthenticator either returns error if the mock authenticator is forced to or returns the supplied resultPerRPCCredentials.

func (*MockClientAuthenticator) RoundTripper

func (m *MockClientAuthenticator) RoundTripper(base http.RoundTripper) (http.RoundTripper, error)

RoundTripper for the MockClientAuthenticator either returns error if the mock authenticator is forced to or returns the supplied resultRoundTripper.

func (*MockClientAuthenticator) Shutdown

func (m *MockClientAuthenticator) Shutdown(ctx context.Context) error

Shutdown for the MockClientAuthenticator does nothing

func (*MockClientAuthenticator) Start

func (m *MockClientAuthenticator) Start(ctx context.Context, host component.Host) error

Start for the MockClientAuthenticator does nothing

type Option

type Option func(*defaultServerAuthenticator)

Option represents the possible options for NewServerAuthenticator.

func WithAuthenticate

func WithAuthenticate(authenticateFunc AuthenticateFunc) Option

WithAuthenticate specifies which function to use to perform the authentication.

func WithShutdown

func WithShutdown(shutdownFunc component.ShutdownFunc) Option

WithShutdown overrides the default `Shutdown` function for a component.Component. The default always returns nil.

func WithStart

func WithStart(startFunc component.StartFunc) Option

WithStart overrides the default `Start` function for a component.Component. The default always returns nil.

type ServerAuthenticator

type ServerAuthenticator interface {
	component.Extension

	// Authenticate checks whether the given headers map contains valid auth data. Successfully authenticated calls will always return a nil error.
	// When the authentication fails, an error must be returned and the caller must not retry. This function is typically called from interceptors,
	// on behalf of receivers, but receivers can still call this directly if the usage of interceptors isn't suitable.
	// The deadline and cancellation given to this function must be respected, but note that authentication data has to be part of the map, not context.
	// The resulting context should contain the authentication data, such as the principal/username, group membership (if available), and the raw
	// authentication data (if possible). This will allow other components in the pipeline to make decisions based on that data, such as routing based
	// on tenancy as determined by the group membership, or passing through the authentication data to the next collector/backend.
	// The context keys to be used are not defined yet.
	Authenticate(ctx context.Context, headers map[string][]string) (context.Context, error)
}

ServerAuthenticator is an Extension that can be used as an authenticator for the configauth.Authentication option. Authenticators are then included as part of OpenTelemetry Collector builds and can be referenced by their names from the Authentication configuration. Each ServerAuthenticator is free to define its own behavior and configuration options, but note that the expectations that come as part of Extensions exist here as well. For instance, multiple instances of the same authenticator should be possible to exist under different names.

func NewServerAuthenticator

func NewServerAuthenticator(options ...Option) ServerAuthenticator

NewServerAuthenticator returns a ServerAuthenticator configured with the provided options.