构建认证器扩展

OpenTelemetry Collector 允许您将接收器和导出器连接到认证器，以便您可以在接收器端对传入连接进行身份验证，并在导出器端向传出请求添加身份验证数据。

认证器通过 扩展 实现。本文档将指导您实现自己的认证器。如果您想了解如何使用现有认证器，请参阅该特定认证器的文档。您可以在此网站的 注册表 中找到现有认证器的列表。

使用本指南了解构建自定义认证器的一般方向，并参阅 API 参考指南 以了解每种类型和函数的语义。

如果您需要帮助，请加入 #opentelemetry-collector-dev 频道，该频道位于 CNCF Slack 工作区。

架构

认证器 在 OpenTelemetry 中与其他扩展一样，但它们还必须实现一个或多个定义身份验证方式的特定接口（例如，身份验证 HTTP 或 gRPC 请求）。将 服务器认证器 与接收器一起使用，以拦截 HTTP 和 gRPC 请求。将客户端认证器与导出器一起使用，以向 HTTP 和 gRPC 请求添加身份验证数据。认证器也可以同时实现这两个接口，允许扩展的一个实例处理传入和传出的请求。

一旦认证器扩展在 Collector 分发版中可用，您就可以在配置文件中像其他扩展一样引用它。但是，只有当认证器被消耗组件引用时，它才会生效。以下配置显示了一个名为 otlp/auth 的接收器，它使用了 oidc 认证器扩展。

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 函数会为每个传入请求运行，并且在函数完成之前管道无法继续前进。因此，您的认证器必须避免缓慢或不必要的阻塞操作。如果 context 设置了截止时间，请确保您的代码遵守它，以免管道延迟或被挂起。

您还应该为您的认证器添加良好的可观察性，尤其是指标和跟踪。这有助于用户在错误开始增加时设置警报，并使他们更容易排查身份验证问题。

客户端认证器

客户端认证器 是实现了一个或多个已定义接口的附加功能的扩展。每个认证器都会收到一个对象，允许它注入身份验证数据。例如，HTTP 客户端认证器提供一个 http.RoundTripper，而 gRPC 客户端认证器可以生成一个 credentials.PerRPCCredentials。

将您的自定义认证器添加到分发版

自定义认证器必须与 Collector 本身在同一个二进制文件中。构建自己的认证器时，您有两个选择：

• 您可以使用 OpenTelemetry Collector Builder 构建自定义 Collector 分发版。
• 您可以提供一种方法（例如发布 Go 模块）供用户将其扩展添加到他们自己的分发版中。