設定 SASL 驗證

用戶端可以使用開放原始碼 Apache Kafka API 連線至 Managed Service for Apache Kafka 叢集。所有連線都必須使用 TLS 加密，不支援純文字通訊。驗證作業會透過兩種支援機制之一進行處理，每種機制都有不同的憑證類型：SASL 或 mTLS。

本文說明如何使用 SASL 方法進行驗證。用戶端會使用授權的 Identity and Access Management 主體 (例如服務帳戶) 憑證進行驗證。Managed Service for Apache Kafka 會管理所有連線的伺服器端代理程式憑證。

事前準備

建議您進一步瞭解下列主題：

• 服務帳戶總覽

• 向 Managed Kafka API 進行驗證

• 主體 ID

將代管 Kafka 用戶端角色授予服務帳戶

您必須在包含叢集的專案中，將 roles/managedkafka.client IAM 角色授予要用來連線至叢集的服務帳戶。

代管 Kafka 用戶端角色包含所有連線所需的 managedkafka.clusters.connect 權限。如要將代管 Kafka 用戶端角色授予服務帳戶，請按照下列步驟操作：

控制台

1. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。
   前往「IAM」頁面
2. 確認專案已設為 Managed Service for Apache Kafka 用戶端要存取的消費者專案。
3. 按一下「授予存取權」。
4. 在新頁面的「新增主體」中，輸入您使用的服務帳戶電子郵件地址。
5. 在「指派角色」中，選取「Managed Kafka client」(受管理 Kafka 用戶端) 角色。
6. 按一下 [儲存]。

gcloud CLI

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 執行 gcloud projects add-iam-policy-binding 指令：

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member serviceAccount:SERVICE_ACCOUNT_EMAIL \
     --role roles/managedkafka.client

   更改下列內容：

   • PROJECT_ID 是專案 ID。

   • SERVICE_ACCOUNT_EMAIL 是服務帳戶的電子郵件地址。

設定 Kafka 用戶端，以便向 Google Cloud

您可以使用下列其中一種機制，向 Google Cloud 驗證 Kafka 用戶端：

OAUTHBEARER (建議使用)：這個機制需要使用應用程式預設憑證 (ADC)。驗證程式庫會使用 ADC 策略，根據應用程式環境自動尋找憑證。如要進一步瞭解 ADC 尋找憑證的位置和順序，請參閱「應用程式預設憑證的運作方式」一文。

SASL/PLAIN：這個機制需要使用可從服務帳戶金鑰 JSON 檔案或存取權杖衍生的使用者名稱和密碼。

一般來說，建議使用 OAUTHBEARER。不過，SASL/PLAIN 可能更適合用於測試。

OAuthBearer 驗證

如要瞭解如何驗證開放原始碼 Kafka API，請參閱 GitHub 上的說明文件。

SASL/PLAIN 驗證

Managed Service for Apache Kafka 支援使用服務帳戶金鑰 JSON 檔案或存取權憑證的 SASL/PLAIN 驗證。

服務帳戶金鑰 JSON 檔案

注意： 如未妥善管理服務帳戶金鑰，可能會產生安全性風險，您有責任保護私密金鑰的安全，並執行「 管理服務帳戶金鑰的最佳做法」一文所述的其他作業。假如無法建立服務帳戶金鑰，可能是因為貴組織已停用這項功能。詳情請參閱 這篇文章。

如果您是從外部來源取得服務帳戶金鑰，必須先驗證金鑰，才能使用。詳情請參閱「 外部來源憑證的安全規定」一節。

這個方法適用於所有 Kafka 用戶端。

1. 為要用於用戶端的服務帳戶下載服務帳戶金鑰 JSON 檔案。

2. 使用 Base64 編碼方式編碼服務帳戶檔案，做為驗證字串。假設檔案名稱為 my_service_account_key.json。

   如果作業系統是 Linux 或 macOS，請使用 base64 指令 (通常預設會安裝)，如下所示：

   base64 -w 0 < my_service_account_key.json > password.txt
   

   這個指令會執行下列動作：

   • base64 < my_service_account_key.json： 讀取名為 my_service_account_key.json 的檔案內容。

   • 使用 Base64 編碼方式編碼檔案內容。Base64 編碼可將二進位資料 (例如服務帳戶檔案中的 JSON 資料) 表示為 ASCII 文字。這通常用於透過專為文字設計的管道傳輸資料。

   • > password.txt：將 base64 指令的輸出內容 (服務帳戶檔案的 base64 編碼版本) 重新導向至名為 password.txt 的新檔案。

3. 您可以使用密碼檔案的內容，透過下列參數進行驗證。

   security.protocol=SASL_SSL
   sasl.mechanism=PLAIN
   sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \
   username="SERVICE_ACCOUNT_EMAIL_ADDRESS" \
   password="CONTENTS_OF_BASE64_ENCODED_PASSWORD_FILE";
   

   更改下列內容：

   • SERVICE_ACCOUNT_EMAIL_ADDRESS：要用於驗證的服務帳戶電子郵件地址。
   • CONTENTS_OF_BASE64_ENCODED_PASSWORD_FILE：您在上一個步驟取得的 Base64 編碼密碼檔案內容。這必須是單行。

驗證叢集的連入連線時，Managed Service for Apache Kafka 會檢查下列項目：

1. 提供的使用者名稱與密碼中使用的金鑰所屬的服務帳戶相符。

2. 提供的服務帳戶主體在叢集上具有 managedkafka.clusters.connect 權限 (包含在 roles/managedkafka.client IAM 角色中)。

存取權杖

注意：使用 SASL/PLAIN 搭配存取權杖時，請務必特別小心，因為存取權杖的效期很短，可能會過期。您必須確保用戶端程式庫在建立每個新的 Kafka 線路通訊協定連線時，都會提供有效的存取權杖。如需更多資訊和參考實作，請參閱 GitHub 上的文件。

1. 取得要用於驗證的主體存取權杖。 舉例來說，取得目前 gcloud CLI 主體的存取權杖：

   gcloud auth print-access-token
   

2. 您可以使用存取權杖，透過下列參數進行驗證。

   security.protocol=SASL_SSL
   sasl.mechanism=PLAIN
   sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \
   username="PRINCIPAL_EMAIL_ADDRESS" \
   password="ACCESS_TOKEN_VALUE";
   
   

   更改下列內容：

   • PRINCIPAL_EMAIL_ADDRESS：您用來取得存取權權杖的主體電子郵件地址。
   • ACCESS_TOKEN_VALUE：您在上一個步驟中取得的存取權杖值。

驗證叢集的連入連線時，Managed Service for Apache Kafka 會檢查下列項目：

1. 存取權杖有效且尚未過期。

2. 所提供的使用者名稱與存取權杖相關聯的主體電子郵件地址相符。

3. 存取權杖的主體在叢集上具有 managedkafka.clusters.connect 權限 (包含在 roles/managedkafka.client IAM 角色中)。

Workload Identity Federation for GKE

本節僅適用於使用 Workload Identity Federation for GKE 的情況。 如果您使用 iam.gke.io/gcp-service-account 註解 將 Kubernetes 服務帳戶連結至 IAM 服務帳戶，則不適用本節內容。

Managed Service for Apache Kafka 支援使用 GKE 適用的工作負載身分聯盟，向開放原始碼 Apache Kafka API 進行驗證。SASL/PLAIN 和 SASL/OAUTHBEARER 都支援驗證。

如要搭配使用 Workload Identity Federation for GKE 與 Managed Service for Apache Kafka，您必須符合下列規定：

1. 使用 GKE 1.31.1-gke.1241000 以上版本。

2. 使用 iam.gke.io/return-principal-id-as-email: "true" 註解 Kubernetes 服務帳戶。 例如：

   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: kafka-service-account
     annotations:
       iam.gke.io/return-principal-id-as-email: "true"
   

3. 如果您使用本機驗證伺服器，請確認您也使用 2.40.3 以上版本的 google-auth 套件。

確認 GKE 主體具有 managedkafka.clusters.connect 權限 (包含在 roles/managedkafka.client IAM 角色中)。

Managed Service for Apache Kafka 不支援使用 Fleet 工作負載身分驗證開放原始碼 Apache Kafka API。 或者，您也可以將 Kubernetes 服務帳戶連結至 IAM 服務帳戶。

排解驗證錯誤

如果 Managed Service for Apache Kafka 用戶端無法向 Managed Service for Apache Kafka 進行驗證，您會看到類似以下的錯誤訊息：

Exception in thread "main" java.util.concurrent.ExecutionException:
org.apache.kafka.common.errors.SaslAuthenticationException:
Authentication failed: Invalid username or password

如要解決這個問題，請檢查下列原因：

• 密碼格式有誤，經過 Base64 解碼後，並非有效的服務帳戶金鑰 JSON Blob 或有效的存取權杖。

• 驗證主體在叢集上沒有 managedkafka.clusters.connect 權限。

• 提供的使用者名稱與憑證主體不符。

如果用戶端每 30 分鐘就會頻繁中斷連線，可能是因為用戶端不支援定期重新驗證。Managed Service for Apache Kafka 代理程式會強制要求用戶端每 30 分鐘重新驗證一次，這是由 connections.max.reauth.ms 代理程式屬性所控管。確認 Kafka 用戶端程式庫版本為 2.2.0 以上，且支援重新驗證。

後續步驟

• 使用 Kafka ACL 控管存取權。

• 驗證 Managed Kafka API。

Apache Kafka® 是 The Apache Software Foundation 或其關聯企業在美國與/或其他國家/地區的註冊商標。