認証エクステンションの構築

OpenTelemetryコレクターを使用すると、レシーバーとエクスポーターを認証機能に接続できるため、レシーバー側での受信接続の認証や、エクスポーター側での送信リクエストへの認証データの追加が可能になります。

認証機能はエクステンションを通じて実装されます。 このドキュメントでは、独自の認証機能を実装する方法について説明します。 既存の認証機能の使用方法を学びたい場合は、その特定の認証機能のドキュメントを参照してください。 このウェブサイトのレジストリで、既存の認証機能のリストを見つけることができます。

カスタム認証機能の構築方法に関する一般的な手順についてはこのガイドを使用し、各タイプと関数のセマンティクスについてはAPIリファレンスガイドを参照してください。

ヘルプが必要な場合は、CNCFのSlackワークスペースの#opentelemetry-collector-devチャンネルに参加してください。

アーキテクチャ

OpenTelemetryにおける認証機能は、ほかのエクステンションと同様ですが、認証がどのように実行されるか（たとえば、HTTPまたはgRPCリクエストの認証など）を定義する1つ以上の特定のインターフェイスも実装する必要があります。 サーバー認証機能をレシーバーで使用して、HTTPおよびgRPCリクエストをインターセプトします。 クライアント認証機能をエクスポーターで使用して、HTTPおよびgRPCリクエストに認証データを追加します。 認証機能は両方のインターフェイスに同時に実装することも可能であり、エクステンションの単一インスタンスが受信および送信両方のリクエストを処理できるようにします。

認証エクステンションがコレクターのディストリビューションで利用可能になると、ほかのエクステンションと同様に構成ファイルで参照できます。 しかし、認証機能は利用するコンポーネントから参照される場合にのみ有効です。 次の構成は、oidc認証エクステンションを使用する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関数は、受信するすべてのリクエストに対して実行され、パイプラインはこの関数が終了するまで先に進むことができません。 そのため、認証機能は遅い、または不必要なブロッキング作業を避ける必要があります。 contextが期限を設定している場合、パイプラインが遅延したりハングアップしないように、コードがその設定に従うことを確認してください。

認証機能には、特にメトリクスとトレースなどの優れたオブザーバビリティを追加する必要があります。 これにより、ユーザーはエラーが増加し始めた場合にアラートを設定でき、認証の問題のトラブルシューティングが容易になります。

クライアント認証機能

クライアント認証機能は、1つ以上の定義されたインターフェイスを実装する追加の関数を持つエクステンションです。 各認証機能は、認証データを注入できるオブジェクトを受け取ります。 たとえば、HTTPクライアント認証機能はhttp.RoundTripperを提供し、一方でgRPCクライアント認証機能はcredentials.PerRPCCredentialsを生成します。

カスタム認証機能をディストリビューションに追加する

カスタム認証機能は、コレクター自体と同じバイナリの一部でなければなりません。 独自の認証機能を構築する場合、2つのオプションがあります。

• OpenTelemetry Collector Builderを使用してカスタムコレクターのディストリビューションを構築できます
• Goモジュールを公開するなど、ユーザーが独自のディストリビューションにエクステンションを追加する方法を提供できます。