构建认证器扩展

OpenTelemetry Collector 允许将接收器和导出器连接到认证器， 从而在接收端对传入连接进行身份验证，并在导出端为传出的请求添加认证数据。

这种机制是通过扩展实现的，本文将指导你实现自己的认证器。 如果你正在寻找如何使用现有认证器的文档，请参考入门指南页面以及你的认证器文档。 你可以在本网站的注册表中找到现有认证器的列表。

请使用本指南作为构建自定义认证器的常规指导，并参考最新的 API 参考指南 以了解每种类型和函数的实际语义。

如果你需要帮助，可以随时加入 CNCF Slack 工作区中的 #opentelemetry-collector 聊天室。

架构

认证器是普通的扩展，但同时满足与认证机制相关的一个或多个接口。 服务器认证器与接收器一起使用，可以拦截 HTTP 和 gRPC 请求； 客户端认证器与导出器一起使用，可以向 HTTP 和 gRPC 请求添加认证数据。 一个认证器可以同时实现这两个接口，从而允许同一个扩展实例同时用于处理传入和传出的请求。 但请注意，用户可能仍然希望针对传入和传出请求使用不同的认证器， 因此不要让你的认证器必须同时在两端使用。

一旦认证器扩展可用于 Collector 发行版中，就可以像普通扩展一样在配置文件中引用此扩展：

extensions:
  oidc:

receivers:
processors:
exporters:

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

但是，认证器必须由使用它的组件引用才能生效。 下面的示例展示了与上面相同的扩展，但现在它被名为 otlp/auth 的接收器使用：

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: []

当需要多个相同类型的认证器实例时，可以给它们不同的名称：

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: []

服务器认证器

服务器认证器本质上是一个带有 Authenticate 函数的扩展，该函数接收载荷头作为参数。 如果认证器能够验证传入连接，应返回 nil 错误；如果无法认证，则返回具体错误。 作为扩展，认证器应确保在 Start 阶段初始化所需的所有资源，并在 Shutdown 时清理这些资源。

Authenticate 调用是传入请求的热路径的一部分，会阻塞管道， 因此要正确处理任何可能阻塞的操作。具体来说，如果提供了上下文的截止时间，要确保遵守该截止时间。 此外，还要为扩展添加足够的可观测性，尤其是通过指标和追踪， 以便用户在错误率高于某个水平时能够设置通知系统，并能调试特定的失败情况。

客户端认证器

客户端认证器是实现了客户端认证器中定义的一个或多个接口的扩展。

与服务器认证器类似，它们本质上是带有额外函数的扩展， 每个函数都会接收一个对象，让认证器有机会向其中注入认证数据。 例如，HTTP 客户端认证器会提供一个 http.RoundTripper， 而 gRPC 客户端认证器则可以生成 credentials.PerRPCCredentials。

将自定义认证器添加到发行版

自定义认证器必须与主要 Collector 位于同一个可执行文件中。 当你构建自己的认证器时，通常需要同时构建自定义发行版，或者为用户提供将你的扩展作为其发行版一部分的方式。 幸运的是，可以使用 OpenTelemetry Collector Builder 工具轻松构建自定义发行版。