本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 設定 Amazon MSK 叢集的 SASL/SCRAM 身分驗證
<a name="msk-password-tutorial"></a>

若要在 AWS Secrets Manager 中設定秘密，請遵循 [AWS Secrets Manager 使用者指南](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)中的[建立和擷取](https://docs.aws.amazon.com/secretsmanager/latest/userguide/tutorials_basic.html)秘密教學課程。

為 Amazon MSK 叢集建立秘密時，請注意以下要求：
+ 針對秘密類型，選擇**其他秘密類型 (如 API 金鑰)**。
+ 您的秘密名稱必須以 **Amazon MSK\$1** 字首開頭。
+ 您必須使用現有的自訂 AWS KMS 金鑰或為您的秘密建立新的自訂 AWS KMS 金鑰。Secrets Manager 預設會使用秘密的預設 AWS KMS 金鑰。
**重要**  
使用預設 AWS KMS 金鑰建立的秘密無法與 Amazon MSK 叢集搭配使用。
+ 您的登入憑證資料必須採用下列格式，才能使用**純文字**選項輸入鍵值對。

  ```
  {
    "username": "alice",
    "password": "alice-secret"
  }
  ```
+ 記錄秘密的 ARN (Amazon Resource Name) 值。
+ 
**重要**  
您無法將 Secret Manager 秘密與超過 [正確調整叢集大小：每個標準代理程式的分割區數量](bestpractices.md#partitions-per-broker) 中所述限制的叢集建立關聯。
+ 如果您使用 AWS CLI 建立秘密，請指定 `kms-key-id` 參數的金鑰 ID 或 ARN。請勿指定別名。
+ 若要將秘密與叢集建立關聯，請使用 Amazon MSK 主控台或 [BatchAssociateScramSecret](https://docs.aws.amazon.com/msk/1.0/apireference/clusters-clusterarn-scram-secrets.html#BatchAssociateScramSecret) 操作。
**重要**  
將秘密與叢集建立關聯後，Amazon MSK 會將資源政策連接至秘密，以便叢集能夠存取和讀取您定義的秘密值。您不應該修改此資源政策。這樣做可以防止您的叢集存取您的秘密。如果您對 Secrets 資源政策和/或用於秘密加密的 KMS 金鑰進行任何變更，請務必重新建立秘密與 MSK 叢集的關聯。這將確保您的叢集可以繼續存取您的秘密。

  下列範例中的 `BatchAssociateScramSecret` 操作 JSON 輸入會將秘密與叢集建立關聯：

  ```
  {
    "clusterArn" : "arn:aws:kafka:us-west-2:0123456789019:cluster/SalesCluster/abcd1234-abcd-cafe-abab-9876543210ab-4",          
    "secretArnList": [
      "arn:aws:secretsmanager:us-west-2:0123456789019:secret:AmazonMSK_MyClusterSecret"
    ]
  }
  ```

# 使用登入憑證連線至叢集
<a name="msk-password-tutorial-connect"></a>

建立秘密並將其與叢集建立關聯後，即可將用戶端連線至叢集。下列程序示範如何將用戶端連線至使用 SASL/SCRAM 身分驗證的叢集。它還顯示如何從範例主題產生和使用 。

**Topics**
+ [使用 SASL/SCRAM 身分驗證將用戶端連線至叢集](#w2aab9c13c29c17c13c11b9b7)
+ [連線問題疑難排解](#msk-password-tutorial-connect-troubleshooting)

## 使用 SASL/SCRAM 身分驗證將用戶端連線至叢集
<a name="w2aab9c13c29c17c13c11b9b7"></a>

1. 在 AWS CLI 已安裝 的機器上執行下列命令。以叢集的 ARN 取代 *clusterARN*。

   ```
   aws kafka get-bootstrap-brokers --cluster-arn clusterARN
   ```

   從此命令的 JSON 結果中，儲存與名為 的字串相關聯的值`BootstrapBrokerStringSaslScram`。您將在後續步驟中使用此值。

1. 在用戶端機器上建立 JAAS 組態檔案，其中內含儲存在秘密中的使用者憑證。例如，為使用者 **alice**，建立一個名為 `users_jaas.conf` 的檔案，內含以下內容。

   ```
   KafkaClient {
      org.apache.kafka.common.security.scram.ScramLoginModule required
      username="alice"
      password="alice-secret";
   };
   ```

1. 使用以下命令將 JAAS 組態檔案匯出為 `KAFKA_OPTS` 環境參數。

   ```
   export KAFKA_OPTS=-Djava.security.auth.login.config=<path-to-jaas-file>/users_jaas.conf
   ```

1. 在 `/tmp` 目錄中，建立名為 `kafka.client.truststore.jks` 的檔案。

1. （選用） 使用下列命令，將 JDK 金鑰存放區檔案從 JVM `cacerts` 資料夾複製到您在上一個步驟中建立`kafka.client.truststore.jks`的檔案。使用執行個體上 JDK 資料夾的名稱取代 *JDKFolder*。例如，您的 JDK 資料夾可能會命名為 `java-1.8.0-openjdk-1.8.0.201.b09-0.amzn2.x86_64`。

   ```
   cp /usr/lib/jvm/JDKFolder/lib/security/cacerts /tmp/kafka.client.truststore.jks
   ```

1. 在安裝 Apache Kafka 的 `bin` 目錄中，建立名為 `client_sasl.properties` 的用戶端屬性檔案，內含以下內容。此檔案會定義 SASL 機制和通訊協定。

   ```
   security.protocol=SASL_SSL
   sasl.mechanism=SCRAM-SHA-512
   ```

1. 若要建立範例主題，請執行下列命令。將 *BootstrapBrokerStringSaslScram* 取代為您在本主題的步驟 1 中取得的引導代理程式字串。

   ```
   <path-to-your-kafka-installation>/bin/kafka-topics.sh --create --bootstrap-server BootstrapBrokerStringSaslScram --command-config <path-to-client-properties>/client_sasl.properties --replication-factor 3 --partitions 1 --topic ExampleTopicName
   ```

1. 若要產生資料到您建立的範例主題，請在用戶端機器上執行下列命令。將 *BootstrapBrokerStringSaslScram* 取代為您在本主題的步驟 1 中擷取的引導代理程式字串。

   ```
   <path-to-your-kafka-installation>/bin/kafka-console-producer.sh --broker-list BootstrapBrokerStringSaslScram --topic ExampleTopicName --producer.config client_sasl.properties
   ```

1. 若要從您建立的主題取用資料，請在用戶端機器上執行下列命令。將 *BootstrapBrokerStringSaslScram* 取代為您在本主題的步驟 1 中取得的引導代理程式字串。

   ```
   <path-to-your-kafka-installation>/bin/kafka-console-consumer.sh --bootstrap-server BootstrapBrokerStringSaslScram --topic ExampleTopicName --from-beginning --consumer.config client_sasl.properties
   ```

## 連線問題疑難排解
<a name="msk-password-tutorial-connect-troubleshooting"></a>

執行 Kafka 用戶端命令時，您可能會遇到 Java 堆積記憶體錯誤，特別是在使用大型主題或資料集時。發生這些錯誤是因為 Kafka 工具以 Java 應用程式的形式執行，其預設記憶體設定可能不足以滿足您的工作負載。

若要解決`Out of Memory Java Heap`錯誤，您可以透過修改`KAFKA_OPTS`環境變數以包含記憶體設定來增加 Java 堆積大小。

下列範例會將堆積大小上限設定為 1GB (`-Xmx1G`)。您可以根據可用的系統記憶體和需求來調整此值。

```
export KAFKA_OPTS="-Djava.security.auth.login.config=<path-to-jaas-file>/users_jaas.conf -Xmx1G"
```

對於使用大型主題，請考慮使用時間型或位移型參數，而不是`--from-beginning`限制記憶體用量：

```
<path-to-your-kafka-installation>/bin/kafka-console-consumer.sh --bootstrap-server BootstrapBrokerStringSaslScram --topic ExampleTopicName --max-messages 1000 --consumer.config client_sasl.properties
```