构建自定义身份验证器

OpenTelemetry Collector允许将接收器和导出器与身份验证器连接起来，为接收器一侧的传入连接提供身份验证的方式，并在导出器一侧的传出请求中添加身份验证数据。

该机制是基于extensions框架实现的，本文档将指导您如何实现自己的身份验证器。如果您想获取关于如何使用现有身份验证器的文档，请参考入门页面和身份验证器的文档。您可以在本网站的注册表中找到已有的身份验证器列表。

请参考本指南了解构建自定义身份验证器的常规方法，并查阅最新的API参考指南了解每个类型和函数的实际语义。

如果您需要帮助，请加入CNCF Slack工作空间的#opentelemetry-collector频道。

架构

身份验证器是常规扩展，同时还满足与身份验证机制相关的一个或多个接口：

服务器身份验证器用于接收器，可以拦截HTTP和gRPC请求，而客户端身份验证器用于导出器，可以在HTTP和gRPC请求中添加身份验证数据。身份验证器可以同时实现这两个接口，允许一个扩展的实例用于传入和传出请求。但是，请注意，用户可能仍然希望为传入和传出请求使用不同的身份验证器，因此不要将您的身份验证器要求同时在两端使用。

一旦身份验证器扩展在收集器分发中可用，可以将其作为常规扩展在配置文件中引用：

extensions:
  oidc:

receivers:
processors:
exporters:

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

但是，身份验证器需要被一个消耗组件引用才能生效。下面的示例展示了与上面相同的扩展，现在被名为otlp/auth的接收器使用：

extensions:
  oidc:

receivers:
  otlp/auth:
    protocols:
      grpc:
        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:
        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。

将自定义身份验证器添加到分发中

自定义身份验证器必须与主要的收集器二进制文件一起。在构建自己的身份验证器时，您可能还需要构建一个自定义的分发，或者提供一种让用户在其自己的分发中使用您的扩展的方法。幸运的是，可以使用OpenTelemetry Collector Builder工具来构建自定义分发。

最后修改 December 10, 2023: translate (a4350d6e)