Add documentation about auth for the collector

content/en/docs/collector/configuration.md

@@ -448,3 +448,94 @@ following proxy environment variables:
 
 If set at Collector start time then exporters, regardless of protocol, will or
 will not proxy traffic as defined by these environment variables.
+
+### Authentication
+
+Most receivers exposing an HTTP or gRPC port are able to be protected using the collector's
+authentication mechanism, and most exporters using HTTP or gRPC clients are able to add
+authentication data to the outgoing requests.
+
+The authentication mechanism in the collector uses the extensions mechanism, allowing for
+custom authenticators to be plugged into collector distributions. If you are interested
+in developing a custom authenticator, check out the "Building a custom authenticator" document.
+
+Each authentication extension has two possible usages: as client authenticator for exporters,
+adding auth data to outgoing requests, and as server authenticator for receivers, authenticating
+incoming connections. Refer to the authentication extension for a list of its capabilities, but
+in general, an authentication extension would only implement one of those traits. For a list of
+known authenticators, use the [Registry](/registry/?s=authenticator&component=extension&language=) available in this website.
+
+To add a server authenticator to a receiver in your collector, make sure to:
+
+1. add the authenticator extension under the `extensions` section
+1. add the extension to the `services` node
+1. add a reference to the authenticator under the `auth` node for your receiver
+
+Here's an example that uses the OIDC authenticator on the receiver side, making this suitable for
+a remote collector that receives data from an OpenTelemetry Collector acting as agent:
+
+```yaml
+extensions:
+  oidc:
+    issuer_url: http://localhost:8080/auth/realms/opentelemetry
+    audience: collector
+
+receivers:
+  otlp/auth:
+    protocols:
+      grpc:
+        auth:
+          authenticator: oidc
+
+processors:
+
+exporters:
+  logging:
+
+service:
+  extensions:
+    - oidc
+  pipelines:
+    traces:
+      receivers:
+        - otlp/auth
+      processors: []
+      exporters:
+        - logging
+```
+
+On the agent side, this is an example that makes the OTLP exporter obtain OIDC tokens, adding
+them to every RPC made to a remote collector:
+
+```yaml
+extensions:
+  oauth2clientcredentials:
+    client_id: agent
+    client_secret: some-secret
+    token_url: http://localhost:8080/auth/realms/opentelemetry/protocol/openid-connect/token
+
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: localhost:4317
+
+processors:
+
+exporters:
+  otlp/auth:
+    endpoint: remote-collector:4317
+    auth:
+      authenticator: oauth2clientcredentials
+
+service:
+  extensions:
+    - oauth2clientcredentials
+  pipelines:
+    traces:
+      receivers:
+        - otlp
+      processors: []
+      exporters:
+        - otlp/auth
+```

content/en/docs/collector/custom-auth.md

@@ -0,0 +1,117 @@
+---
+title: "Building a custom authenticator"
+weight: 30
+---
+
+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 [`extensions`](https://pkg.go.dev/go.opentelemetry.io/collector/component#Extension) 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 registry.
+
+Use this guide for general directions on how to build a custom authenticator and refer to the up-to-date [API Reference Guide](https://pkg.go.dev/go.opentelemetry.io/collector/config/configauth) for the actual semantics of each type and function.
+
+If at anytime you need assistance, join the [#opentelemetry-collector](https://cloud-native.slack.com/archives/C01N6P7KR6W) room at the [CNCF Slack workspace](https://slack.cncf.io).
+
+## Architecture
+
+Authenticators are regular extensions that also satisfy one or more interfaces related to the authentication mechanism:
+
+- [go.opentelemetry.io/collector/config/configauth/ServerAuthenticator](https://pkg.go.dev/go.opentelemetry.io/collector/config/configauth#ServerAuthenticator)
+- [go.opentelemetry.io/collector/config/configauth/GRPCClientAuthenticator](https://pkg.go.dev/go.opentelemetry.io/collector/config/configauth#GRPCClientAuthenticator)
+- [go.opentelemetry.io/collector/config/configauth/HTTPClientAuthenticator](https://pkg.go.dev/go.opentelemetry.io/collector/config/configauth#HTTPClientAuthenticator)
+
+Server authenticators are used with receivers, and are able to intercept HTTP and gRPC requests, while client authenticators are used with exporteres, 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:
+
+```yaml
+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 `otlp/auth`:
+
+```yaml
+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 is needed, they can have different names:
+
+```yaml
+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:  []
+```
+
+### Server authenticators
+
+A server authenticator is essentially an extension with an `Authenticate` 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 [`Start`](https://pkg.go.dev/go.opentelemetry.io/collector/component#Component) phase, and is expected to clean them up upon `Shutdown`.
+
+The `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.
+
+### Client authenticators
+
+A client authenticator is one that implements one or more of the following interfaces:
+
+- [go.opentelemetry.io/collector/config/configauth/GRPCClientAuthenticator](https://pkg.go.dev/go.opentelemetry.io/collector/config/configauth#GRPCClientAuthenticator)
+- [go.opentelemetry.io/collector/config/configauth/HTTPClientAuthenticator](https://pkg.go.dev/go.opentelemetry.io/collector/config/configauth#HTTPClientAuthenticator)
+
+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`](https://pkg.go.dev/net/http#RoundTripper), while the gRPC client authenticator can produce a [`credentials.PerRPCCredentials`](https://pkg.go.dev/google.golang.org/grpc/credentials#PerRPCCredentials).
+
+## 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](https://github.com/open-telemetry/opentelemetry-collector-builder) utility.

content/en/registry/collector-extension-auth-bearertokenauthextension.md

@@ -0,0 +1,15 @@
+---
+title: Bearer token authenticator extension
+registryType: extension
+isThirdParty: false
+language: collector
+tags:
+  - go
+  - extension
+  - collector
+repo: https://github.com/open-telemetry/opentelemetry-collector/tree/main/extension/bearertokenauthextension
+license: Apache 2.0
+description: The Bearer token authenticator extension allows gRPC and HTTP-based exporters to add authentication data to outgoing calls based on a static token.
+authors: OpenTelemetry Authors
+otVersion: latest
+---

content/en/registry/collector-extension-auth-oauth2clientcredentials.md

@@ -0,0 +1,15 @@
+---
+title: OAuth2 client credentials authenticator extension
+registryType: extension
+isThirdParty: false
+language: collector
+tags:
+  - go
+  - extension
+  - collector
+repo: https://github.com/open-telemetry/opentelemetry-collector/tree/main/extension/oauth2clientcredentials
+license: Apache 2.0
+description: The OAuth2 client credentials authenticator extension allows gRPC and HTTP-based exporters to add authentication data to outgoing calls.
+authors: OpenTelemetry Authors
+otVersion: latest
+---

content/en/registry/collector-extension-auth-oidc.md

@@ -0,0 +1,15 @@
+---
+title: OIDC authenticator extension
+registryType: extension
+isThirdParty: false
+language: collector
+tags:
+  - go
+  - extension
+  - collector
+repo: https://github.com/open-telemetry/opentelemetry-collector/tree/main/extension/oidcauthextension
+license: Apache 2.0
+description: The OIDC authenticator extension allows gRPC and HTTP-based receivers to require authentication from remote clients.
+authors: OpenTelemetry Authors
+otVersion: latest
+---