ADO.NET Provider for Apache Kafka

Build 25.0.9434

接続の確立

Apache Kafka への接続

.NET ベースのエディションは、Confluent.Kafka およびlibrdkafka ライブラリに依存して機能します。 これらのアセンブリはインストーラーにバンドルされ、自動的に本製品 と一緒にインストールされます。 別のインストール方法を利用する場合は、NuGet から依存関係のあるConfluent.Kafka 2.10.0 をインストールしてください。

Apache Kafka サーバーのアドレスを指定するには、BootstrapServers パラメータを使用します。

デフォルトでは、本製品 はデータソースとPLAINTEXT で通信し、これはすべてのデータが暗号化なしで送信されることを意味します。 通信を暗号化するには：

  1. UseSSL をtrue に設定し、本製品 がSSL 暗号化を使用するように構成します。
  2. SSLServerCert およびSSLServerCertType を設定して、サーバー証明書をロードします。

PEM ファイルおよびWindows 証明書ストアがサポートされる証明書ストアです。

Note： ProxyServer のようなプロキシ設定やFirewallServer のようなファイアウォール設定は、Apache Kafka ブローカーへの接続には影響しません。 なぜなら、本製品 はプロキシをサポートしていない公式ライブラリを使用してApache Kafka に相互接続するからです。 これらのオプションは、本製品 がスキーマレジストリに接続する場合にのみ使用されます。詳細はトピックからのメタデータの抽出 を参照してください。

Apache Kafka への認証

Apache Kafka データソースは、次の認証メソッドをサポートしています：

  • Anonymous
  • Plain
  • SCRAM ログインモジュール
  • SSL クライアント証明書
  • Kerberos

Anonymous

Apache Kafka の特定のオンプレミスデプロイメントでは、認証接続プロパティを設定することなくApache Kafka に接続できます。 こうした接続はanonymous（匿名）と呼ばれます。

匿名認証を行うには、このプロパティを設定します。

SASL Plain

Plain 認証では、認証にプレーンテキストのログインモジュールを使用します。

次のプロパティを設定します。

  • AuthScheme：Plain。
  • User：認証を行うユーザー。
  • Password：認証するユーザーのパスワード。

SCRAM ログインモジュール

SCRAM ログインモジュールを使用して認証するには、以下のプロパティを設定します。

  • AuthScheme：SHA-256 ハッシュでSCRAM ログインモジュールを使用する場合はSCRAM を、SHA-512 ハッシュでSCRAM ログインモジュールを使用する場合はSCRAM-SHA-512 を指定します。
  • User：認証を行うユーザー。
  • Password：認証するユーザーのパスワード。

SSL クライアント証明書

SSL クライアント証明書を使用して認証するには、次のプロパティを設定します。

  • AuthScheme：SSLCertificate。
  • SSLClientCert：CData ADO.NET Provider for Apache Kafka ブローカーへの接続に使用されるSSL クライアント証明書。
  • SSLClientCertType：CData ADO.NET Provider for Apache Kafka ブローカーへの接続に使用されるSSL クライアント証明書の形式：PEMKEY_FILE（デフォルト）、JKSFILE、またはPMKEY_BLOB。

PEM 証明書形式を推奨しますが、PEM およびPFX の両方をサポートしています。

Kerberos

Kerberos で認証するには、システムのKerberos 設定ファイルを指定する必要があります。 次のプロパティを設定します。

Note： KerberosKeytabFile、KerberosSPN、およびUseKerberosTicketCache はWindows 環境では動作しません。 代わりに、ドライバーはドメインログオンユーザーから必要な情報をすべて取得します。

Kafka OpenID Connect

本製品 は、Apache Kafka クライアントライブラリによって提供される限定的なOAuth をサポートしています。 Azure Event Hubs やGCP Kafka に接続する認証スキームとは異なり、この認証スキームは特定の認証プロバイダー（IdP）に紐づいていません。 IdP がクライアント資格情報グラント種別をサポートし、アクセストークン形式としてJWT を使用することのみが必要です。 IdP がこれらの要件を満たす場合、本製品 で使用するためのOAuth アプリケーションをIdP に登録できます。

Note：IdP もApache Kafka ブローカーも、多様な方法で設定できます。 本製品 と接続する際は、双方の要件を理解している必要があります。 詳細については、Apache Kafka ブローカーとIdP のドキュメントを参照してください。

  • 認証プロバイダー：IdP は通常、アプリケーションが認証を行う前に登録を要求します。 クライアント資格情報アプリケーションを登録すると、クライアントID、クライアントシークレット、およびこれらの値を受け入れるトークンURL が提供されます。 IdP は、Apache Kafka ブローカーが受け入れるアクセストークンを生成するために、特定のスコープも要求する場合があります。
  • Apache Kafka Broker：Apache Kafka ブローカーは、アクセストークンを検証するための複数のオプションをサポートしています。 これらの中で本製品 にとって最も重要なのは、アクセストークンに適用されるオーディエンス、発行者、署名鍵です。 アクセストークンが一致するオーディエンスや発行者を持たない場合、あるいは認識されない鍵で署名されている場合、ブローカーは接続を拒否します。 このような場合、ブローカーログを確認して検証に失敗した原因を特定する必要があります。 ブローカーは本製品 に検証に失敗した理由を伝えないため、クライアントログの使用は限定的です。

認証するには、次のプロパティを設定します。

  • AuthScheme：KafkaOAuthClient。
  • OAuthAccessTokenURL：IdP がOAuth トークンリクエストを受け入れるURL。
  • OAuthClientId：IdP に登録したアプリケーションのクライアントID。
  • OAuthClientSecret：IdP に登録したアプリケーションのクライアントシークレット。
  • Scope（オプション）：IdP が有効なアクセストークンを取得するために特定のスコープを要求する場合、ここで設定します。

Azure Event Hubs への接続

本製品 は、OAuth および共有アクセス署名を使用したAzure Event Hubs への接続をサポートします。 開始する前に、Event Hubs のネームスペースがKafka プロトコルを使用した接続をサポートしていることを確認してください。 本製品 ではこの機能を必須としており、価格体系によってはご利用いただけない場合があります。

以下で説明するスキーム固有のプロパティに加えて、Azure へのすべての接続で次のプロパティを設定する必要があります。

Entra ID（Azure AD）

Note：Microsoft はAzure AD をEntra ID にリブランドしました。ユーザーがEntra ID 管理サイトを操作する必要があるトピックでは、Microsoft が使用している名称と同じものを使用します。ただし、名前または値が"Azure AD" を参照しているCData 接続プロパティは、依然として存在します。

Microsoft Entra ID は、マルチテナント型のクラウドベースのID およびアクセス管理プラットフォームです。 OAuth ベースの認証フローに対応しており、ドライバーによるApache Kafka エンドポイントへのセキュアなアクセスを実現します。

Web アプリケーションを介したEntra ID への認証には、必ずはじめにカスタムOAuth アプリケーションを作成して登録する必要があります。 これにより、アプリケーションは独自のリダイレクトURI を定義し、クレデンシャルのスコープを管理し、組織固有のセキュリティポリシーに準拠することができるようになります。

カスタムOAuth アプリケーションの作成および登録方法の詳細については、Entra ID（Azure AD）アプリケーションの作成 を参照してください。

AuthScheme をAzureAD に設定した後の認証手順は、環境によって異なります。 デスクトップアプリケーション、Web ベースのワークフロー、またはヘッドレスシステムから接続する方法の詳細については、以下のセクションを参照してください。

デスクトップアプリケーション

デスクトップアプリケーションでは、ドライバーに組み込まれたOAuth アプリケーション、またはMicrosoft Entra ID に登録されたカスタムOAuth アプリケーションのいずれかを使用して認証を行うことができます。

オプション1：組み込みOAuth アプリケーションの使用

これはドライバーに含まれている、事前登録済みのアプリケーションです。 セットアップが簡単で、独自の認証情報を登録する必要がないため、開発環境、単一ユーザー向けツール、または迅速かつ簡単な認証が求められる構成に最適です。

次の接続プロパティを設定します。

  • AuthScheme：AzureAD
  • InitiateOAuth：
    • GETANDREFRESH – 初回ログイン時に使用します。ログインページを起動し、トークンを保存します。
    • REFRESH – すでに有効なアクセストークンおよびリフレッシュトークンを取得している場合は、この設定を使用します。保存されたトークンを再利用するため、ユーザーに再度プロンプトを表示することはありません。

接続時には、ドライバーは既定のブラウザでMicrosoft Entra のサインインページを開きます。 サインインしてアクセスを許可すると、ドライバーはアクセストークンおよびリフレッシュトークンを取得し、OAuthSettingsLocation で指定されたパスに保存します。

オプション2：カスタムOAuth アプリケーションの使用

組織でセキュリティポリシーの管理、リダイレクトURI の設定、アプリケーションのブランディングなど、より高度な制御が必要な場合は、代わりにMicrosoft Entra ID にカスタムOAuth アプリケーションを登録し、接続時にその値を指定することができます。

登録時に、以下の値を記録してください。

  • OAuthClientId：カスタムOAuth アプリケーションの登録時に生成されたクライアントId。
  • OAuthClientSecret：カスタムOAuth アプリケーションの登録時に生成されたクライアントシークレット。
  • CallbackURL：アプリケーション登録時に定義したリダイレクトURI。

カスタムOAuth アプリケーションの登録とリダイレクトURI の設定方法の詳細については、Entra ID（Azure AD）アプリケーションの作成 を参照してください。

次の接続プロパティを設定します。

  • AuthScheme： AzureAD
  • InitiateOAuth：
    • GETANDREFRESH – 初回ログイン時に使用します。ログインページを起動し、トークンを保存します。
    • REFRESH – すでに有効なアクセストークンおよびリフレッシュトークンを取得している場合は、この設定を使用します。保存されたトークンを再利用するため、ユーザーに再度プロンプトを表示することはありません。
  • OAuthClientId：カスタムOAuth アプリケーションの登録時に生成されたクライアントId。
  • OAuthClientSecret：カスタムOAuth アプリケーションの登録時に生成されたクライアントシークレット。
  • CallbackURL：アプリケーション登録時に定義したリダイレクトURI。

認証後、トークンはOAuthSettingsLocation に保存されます。 これらの値はセッションをまたいで保持され、アクセストークンの有効期限が切れた際に自動的に更新されるため、次回以降の接続時に再度ログインする必要はありません。

Web アプリケーション

Web アプリケーションから認証を行うには、Microsoft Entra ID（旧称：Azure Active Directory）にカスタムOAuth アプリケーションを登録する必要があります。 Web ベースのフローでは、登録済みのリダイレクトURI と一元的な認証情報の管理が必要となるため、組み込みのOAuth アプリケーションはこの用途ではサポートされていません。

このアプローチは、ホスト型のマルチユーザー環境向けに設計されており、安全で標準に準拠したOAuth ワークフローを経由してアクセスを委任する必要がある場合に適しています。 これにより、組織はOAuth クライアント、リダイレクトURI、ブランディング、権限スコープを制御できます。

開始する前に：Azure ポータルでカスタムOAuth アプリケーションを登録してください。登録時に、以下の値を記録してください。

  • OAuthClientId：カスタムOAuth アプリケーションの登録時に生成されたクライアントId。
  • OAuthClientSecret：カスタムOAuth アプリケーションの登録時に生成されたクライアントシークレット。
  • CallbackURL：アプリケーション登録時に定義したリダイレクトURI。

カスタムOAuth アプリケーションの登録とリダイレクトURI の設定方法の詳細については、Entra ID（Azure AD）アプリケーションの作成 を参照してください。

Web アプリケーションでAzureAD を使用して認証するには、以下の接続プロパティを設定します。

  • AuthScheme：AzureAD
  • InitiateOAuth：OFF – 自動ログインのプロンプトを無効にします。
  • OAuthClientId：カスタムOAuth アプリケーションの登録時に生成されたクライアントId。
  • OAuthClientSecret：カスタムOAuth アプリケーションの登録時に生成されたクライアントシークレット。
  • CallbackURL：アプリケーション登録時に定義したリダイレクトURI。

Web アプリケーションでは通常、OAuth フローをサーバー側で手動で管理するため、InitiateOAuth はOFF に設定する必要があります。 これにより、ストアドプロシージャを使用して、トークンの取得および交換のタイミングと方法を明示的に制御できるようになります。

これらのプロパティを設定した後、以下の手順に従ってOAuth トークンを取得および交換してください。

  1. GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。
    • CallbackURL：登録したリダイレクトURI に設定します。
  2. 返されたURL をブラウザで開きます。Microsoft Entra ID アカウントでサインインし、アクセスを許可します。
  3. サインイン後、クエリ文字列にcode パラメータが含まれた状態でCallbackURL にリダイレクトされます。
  4. そのcode を抽出し、GetOAuthAccessToken ストアドプロシージャに渡します。
    • AuthMode：WEB
    • Verifier：CallbackURL からの認可コード。
  5. プロシージャは、以下を返します。
    • OAuthAccessToken：認証に使用されます。
    • OAuthRefreshToken：アクセストークンを更新するために使用されます。
    • ExpiresIn：アクセストークンの有効期間（秒単位）。

トークンの自動更新を有効にするには、以下の接続プロパティを設定します。

InitiateOAuth がREFRESH に設定されている場合、ドライバーは提供されたリフレッシュトークンを使用して、自動的に新しいアクセストークンを要求します。

接続に成功すると、ドライバーは更新されたアクセストークンとリフレッシュトークンを、OAuthSettingsLocation によって指定されたファイルに保存します。

リフレッシュトークンが期限切れになるか、取り消されるか、無効になる場合のみ、OAuth の認可フロー全体を再実行する必要があります。

Microsoft Entra ID におけるOAuth フローの詳細については、 Microsoft Entra 認証の概要を参照してください。

ヘッドレスマシン

CI / CD パイプライン、バックグラウンドサービス、サーバーベース連携などのヘッドレス環境では、対話型のブラウザが使用できません。 AzureAD を使用して認証するには、別のデバイス上のブラウザでOAuth フローを完了し、その認証結果をヘッドレスシステムに転送する必要があります。

セットアップオプション ：

  • Verifier code を取得および交換
    • 別のデバイスを使用してサインインし、Verifier code を取得します。ヘッドレスシステムがこのコードを使用してトークンを要求します。
  • OAuth 設定ファイルを転送
    • 別のデバイスで認証を行い、その後、保存されたトークンファイルをヘッドレス環境にコピーします。

Verifier code の使用

  1. ブラウザを備えたデバイスで：
    • カスタムOAuth アプリケーションを使用する場合は、次のプロパティを設定します。
      • InitiateOAuth：OFF
      • OAuthClientId：カスタムOAuth アプリケーションの登録時に生成されたクライアントId。
      • OAuthClientSecret：カスタムOAuth アプリケーションの登録時に生成されたクライアントシークレット。
    • GetOAuthAuthorizationURL ストアドプロシージャを呼び出し、サインインURL を生成します。
    • 返されたURL をブラウザで開きます。サインインして、ドライバーにアクセス許可を与えます。verifier code を含むコールバックURL にリダイレクトされます。
    • サインイン後、リダイレクトURL のcode パラメータの値を保存します。この値は後でOAuthVerifier 接続プロパティを設定する際に使用します。
  2. ヘッドレスマシンで：
    • 次のプロパティを設定します。
      • AuthScheme：AzureAD
      • InitiateOAuth：REFRESH
      • OAuthVerifier：保存したverifier code。
      • OAuthSettingsLocation：OAuth トークンの値を保存するファイルのパス。
      • カスタムアプリケーションの場合：
        • OAuthClientId：カスタムOAuth アプリケーションの登録時に生成されたクライアントId。
        • OAuthClientSecret：カスタムOAuth アプリケーションの登録時に生成されたクライアントシークレット。
    • トークンを保存した後、以下の設定により再利用できます。
      • InitiateOAuth：REFRESH
      • OAuthSettingsLocation：アクセストークンの自動リフレッシュを有効にするために、この場所がドライバーに読み書きのアクセス許可を与えることを確認してください。
      • カスタムアプリケーションの場合：
        • OAuthClientId：カスタムOAuth アプリケーションの登録時に生成されたクライアントId。
        • OAuthClientSecret：カスタムOAuth アプリケーションの登録時に生成されたクライアントシークレット。

OAuth 設定を転送

  1. ブラウザを備えたデバイスで：
    • デスクトップアプリケーションセクションの説明に従って接続します。
    • 接続後、トークンはOAuthSettingsLocation のファイルパスに保存されます。デフォルトのファイル名はOAuthSettings.txt です。

  2. ヘッドレスマシンで：
    • OAuth 設定ファイルをマシンにコピーします。
    • 次のプロパティを設定します。
      • AuthScheme：AzureAD
      • InitiateOAuth：REFRESH
      • OAuthSettingsLocation：アクセストークンの自動リフレッシュを有効にするために、この場所がドライバーに読み書きのアクセス許可を与えることを確認してください。
      • カスタムアプリケーションの場合：
        • OAuthClientId：カスタムOAuth アプリケーションの登録時に生成されたクライアントId。
        • OAuthClientSecret：カスタムOAuth アプリケーションの登録時に生成されたクライアントシークレット。

セットアップ後、ドライバーは保存されたトークンを使用してアクセストークンを自動的に更新するため、ブラウザや手動でのログインは必要ありません。

Azure サービスプリンシパル

Note：Microsoft はAzure AD をEntra ID にリブランドしました。ユーザーがEntra ID 管理サイトを操作する必要があるトピックでは、Microsoft が使用している名称と同じものを使用します。ただし、名前または値が"Azure AD" を参照しているCData 接続プロパティは、依然として存在します。

Azure サービスプリンシパルは、ロールに基づいたアプリケーションベースの認証です。これは、認証がユーザーごとではなく、アプリケーションごとに行われることを意味します。 アプリケーションで実行されるすべてのタスクは、デフォルトユーザーコンテキストなしで、割り当てられたロールに基づいて実行されます。 リソースへのアプリケーションのアクセスは、割り当てられたロールの権限によって制御されます。

Azure サービスプリンシパル認証の設定方法については、Entra ID（Azure AD）でのサービスプリンシパルアプリの作成 を参照してください。

Managed Service Identity (MSI)

Azure VM 上でApache Kafka を実行しており、マネージドID（MSI）認証情報を自動的に取得して接続したい場合は、AuthScheme を AzureMSI に設定します。

User-Managed Identities

マネージドID のトークンを取得するには、OAuthClientId プロパティを使用してマネージドID のclient_id を指定します。

VM に複数のユーザーが割り当てられたマネージドID がある場合は、OAuthClientId も指定する必要があります。

共有アクセス署名

本製品 は、共有アクセス署名を使用したパスワードベースの認証をサポートします。 共有シークレットを作成したら、以下のプロパティを設定します。

  • AuthScheme：Plain。
  • User：$ConnectionString。
  • Password：Shared Access Policies 画面にあるEvent Hubs 接続文字列。

GCP Kafka への接続

本製品 は、Google Managed Service for Apache Kafka（GCP Kafka）への接続をサポートします。 GCP Kafka はOAuth 認証を使用し、サービスアカウント、GCP インスタンスアカウント、Workload Identity Federation をサポートしています。

GCP Kafka への接続はすべて、以下のプロパティを設定する必要があります。

  • BootstrapServers：bootstrap.myclustername.myregion.managedkafka.mygcpproject.cloud.goog:9092。 この値は、Cluster Configuration ページのConfigurations タブに表示されます。
  • UseSSL：True。

以下に説明する適切なスキーム固有のプロパティを設定すると、接続の準備が整います。

GCP Kafka への認証

GCP Kafka には、Google サービスアカウント、GCP インスタンスアカウント、またはWorkload Identity Federation 認証情報を使用して認証できます。

サービスアカウント

GCP Kafka はGoogle サービスアカウントでの認証をサポートしています。 このサービスアカウントには、Managed Kafka Client ロールが必要です。

サービスアカウント認証情報を、以下のプロパティとともに本製品 に入力します。

GCP インスタンスアカウント

GCP Kafka は、GCP インスタンスアカウントを使用した接続をサポートします。 このためには、Compute Engine インスタンスにManaged Kafka Client ロールを持つサービスアカウントが必要です。 インスタンスは、Cloud API Access Scopes 内のCloud Platform スコープを有効にする必要もあります。

GCP インスタンスアカウントを使用して接続するには、このプロパティを設定します。

Workload Identity Federation 認証情報

GCP Kafka は、Workload Identity Federation 認証情報を使用した接続をサポートします。 ただし、RequestingServiceAccount プロパティによる委任によってのみ、これらのアカウントをサポートします。 通常のサービスアカウントと同様に、委任されたサービスアカウントには、Managed Kafka Client ロールが必要です。

Workload Identity Federation 認証情報を使用して接続するには、以下のプロパティを設定します。

Copyright (c) 2025 CData Software, Inc. - All rights reserved.
Build 25.0.9434