configauth

README

Authentication configuration for receivers

This module allows server types, such as gRPC and HTTP, to be configured to perform authentication for requests and/or RPCs. Each server type is responsible for getting the request/RPC metadata and passing down to the authenticator.

The currently known authenticators:

• oidc

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

receivers:
  otlp/with_auth:
    protocols:
      grpc:
        endpoint: localhost:4318
        tls_settings:
          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

Creating an authenticator

New authenticators can be added by creating a new extension that also implements the configauth.ServerAuthenticator extension. Generic authenticators that may be used by a good number of users might be accepted as part of the core distribution, or as part of the contrib distribution. If you have interest in contributing one 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

• func DefaultGRPCStreamServerInterceptor(srv interface{}, stream grpc.ServerStream, _ *grpc.StreamServerInfo, ...) error
• func DefaultGRPCUnaryServerInterceptor(ctx context.Context, req interface{}, _ *grpc.UnaryServerInfo, ...) (interface{}, error)
• type AuthenticateFunc
• type Authentication
• type ClientAuthenticator
• type GRPCClientAuthenticator
  • func GetGRPCClientAuthenticator(extensions map[config.ComponentID]component.Extension, ...) (GRPCClientAuthenticator, error)
• type GRPCStreamInterceptorFunc
• type GRPCUnaryInterceptorFunc
• type HTTPClientAuthenticator
  • func GetHTTPClientAuthenticator(extensions map[config.ComponentID]component.Extension, ...) (HTTPClientAuthenticator, error)
• type MockAuthenticator
  • func (m *MockAuthenticator) Authenticate(ctx context.Context, headers map[string][]string) (context.Context, error)
  • func (m *MockAuthenticator) GRPCStreamServerInterceptor(interface{}, grpc.ServerStream, *grpc.StreamServerInfo, grpc.StreamHandler) error
  • func (m *MockAuthenticator) GRPCUnaryServerInterceptor(context.Context, interface{}, *grpc.UnaryServerInfo, grpc.UnaryHandler) (interface{}, error)
  • func (m *MockAuthenticator) Shutdown(ctx context.Context) error
  • func (m *MockAuthenticator) Start(context.Context, component.Host) error
• 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 ServerAuthenticator
  • func GetServerAuthenticator(extensions map[config.ComponentID]component.Extension, ...) (ServerAuthenticator, error)

Functions

func DefaultGRPCStreamServerInterceptor

func DefaultGRPCStreamServerInterceptor(srv interface{}, stream grpc.ServerStream, _ *grpc.StreamServerInfo, handler grpc.StreamHandler, authenticate AuthenticateFunc) error

DefaultGRPCStreamServerInterceptor provides a default implementation of GRPCStreamInterceptorFunc, useful for most authenticators. It extracts the headers from the incoming request, under the assumption that the credentials will be part of the resulting map.

func DefaultGRPCUnaryServerInterceptor

func DefaultGRPCUnaryServerInterceptor(ctx context.Context, req interface{}, _ *grpc.UnaryServerInfo, handler grpc.UnaryHandler, authenticate AuthenticateFunc) (interface{}, error)

DefaultGRPCUnaryServerInterceptor provides a default implementation of GRPCUnaryInterceptorFunc, useful for most authenticators. It extracts the headers from the incoming request, under the assumption that the credentials will be part of the resulting map.

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 {
	// AuthenticatorName specifies the name of the extension to use in order to authenticate the incoming data point.
	AuthenticatorName string `mapstructure:"authenticator"`
}

Authentication defines the auth settings for the receiver.

type ClientAuthenticator

type ClientAuthenticator interface {
	component.Extension
}

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.

type GRPCClientAuthenticator

type GRPCClientAuthenticator interface {
	ClientAuthenticator
	PerRPCCredentials() (credentials.PerRPCCredentials, error)
}

GRPCClientAuthenticator is a ClientAuthenticator that can be used as an authenticator for the configauth.Authentication option for gRPC clients.

func GetGRPCClientAuthenticator

func GetGRPCClientAuthenticator(extensions map[config.ComponentID]component.Extension,
	componentID config.ComponentID) (GRPCClientAuthenticator, error)

GetGRPCClientAuthenticator attempts to select the appropriate GRPCClientAuthenticator 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 only be used by gRPC clients.

type GRPCStreamInterceptorFunc

type GRPCStreamInterceptorFunc func(srv interface{}, stream grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler, authenticate AuthenticateFunc) error

GRPCStreamInterceptorFunc defines the signature for the function intercepting streaming gRPC calls, useful for authenticators to use as types for internal structs, making it easier to mock them in tests. See ServerAuthenticator.GRPCStreamServerInterceptor.

type GRPCUnaryInterceptorFunc

type GRPCUnaryInterceptorFunc func(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler, authenticate AuthenticateFunc) (interface{}, error)

GRPCUnaryInterceptorFunc defines the signature for the function intercepting unary gRPC calls, useful for authenticators to use as types for internal structs, making it easier to mock them in tests. See ServerAuthenticator.GRPCUnaryServerInterceptor.

type HTTPClientAuthenticator

type HTTPClientAuthenticator interface {
	ClientAuthenticator
	RoundTripper(base http.RoundTripper) (http.RoundTripper, error)
}

HTTPClientAuthenticator is a ClientAuthenticator that can be used as an authenticator for the configauth.Authentication option for HTTP clients.

func GetHTTPClientAuthenticator

func GetHTTPClientAuthenticator(extensions map[config.ComponentID]component.Extension,
	componentID config.ComponentID) (HTTPClientAuthenticator, error)

GetHTTPClientAuthenticator attempts to select the appropriate HTTPClientAuthenticator 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.

type MockAuthenticator

type MockAuthenticator struct {
	// AuthenticateFunc to use during the authentication phase of this mock. Optional.
	AuthenticateFunc AuthenticateFunc
}

MockAuthenticator provides a testing mock for code dealing with authentication.

func (*MockAuthenticator) Authenticate

func (m *MockAuthenticator) Authenticate(ctx context.Context, headers map[string][]string) (context.Context, error)

Authenticate executes the mock's AuthenticateFunc, if provided, or just returns the given context unchanged.

func (*MockAuthenticator) GRPCStreamServerInterceptor

func (m *MockAuthenticator) GRPCStreamServerInterceptor(interface{}, grpc.ServerStream, *grpc.StreamServerInfo, grpc.StreamHandler) error

GRPCStreamServerInterceptor isn't currently implemented and always returns nil.

func (*MockAuthenticator) GRPCUnaryServerInterceptor

func (m *MockAuthenticator) GRPCUnaryServerInterceptor(context.Context, interface{}, *grpc.UnaryServerInfo, grpc.UnaryHandler) (interface{}, error)

GRPCUnaryServerInterceptor isn't currently implemented and always returns nil.

func (*MockAuthenticator) Shutdown

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

Shutdown isn't currently implemented and always returns nil.

func (*MockAuthenticator) Start

func (m *MockAuthenticator) Start(context.Context, component.Host) error

Start isn't currently implemented and always returns nil.

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 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)

	// GRPCUnaryServerInterceptor is a helper method to provide a gRPC-compatible UnaryServerInterceptor, typically calling the authenticator's Authenticate method.
	// While the context is the typical source of authentication data, the interceptor is free to determine where the auth data should come from. For instance, some
	// receivers might implement an interceptor that looks into the payload instead.
	// Once the authentication succeeds, the interceptor is expected to call the handler.
	// See https://pkg.go.dev/google.golang.org/grpc#UnaryServerInterceptor.
	GRPCUnaryServerInterceptor(ctx context.Context, req interface{}, srvInfo *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error)

	// GRPCStreamServerInterceptor is a helper method to provide a gRPC-compatible StreamServerInterceptor, typically calling the authenticator's Authenticate method.
	// While the context is the typical source of authentication data, the interceptor is free to determine where the auth data should come from. For instance, some
	// receivers might implement an interceptor that looks into the payload instead.
	// Once the authentication succeeds, the interceptor is expected to call the handler.
	// See https://pkg.go.dev/google.golang.org/grpc#StreamServerInterceptor.
	GRPCStreamServerInterceptor(srv interface{}, stream grpc.ServerStream, srvInfo *grpc.StreamServerInfo, handler grpc.StreamHandler) 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 GetServerAuthenticator

func GetServerAuthenticator(extensions map[config.ComponentID]component.Extension, componentID config.ComponentID) (ServerAuthenticator, error)

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