mTLS 認証を構成する

相互 TLS（mTLS）を使用して Kafka クライアントを認証するように Managed Service for Apache Kafka クラスタを構成できます。この方法では、Certificate Authority Service（CA Service）のクライアント証明書を認証のベースとして使用します。このオプションは、Identity and Access Management（IAM）プリンシパルを使用するデフォルトの SASL メカニズムの代替手段を提供します。

mTLS を使用する場合は、Kafka ACL を使用して認可を構成する必要があります。基本的なコンセプトについては、次のドキュメントをご覧ください。

始める前に

mTLS 認証を構成する前に、次の操作を行います。

クラスタの利用資格を確認します。2025 年 6 月 24 日以降に作成された既存の Managed Service for Apache Kafka クラスタがあることを確認します。これらのクラスタのみが mTLS 認証をサポートしています。クラスタの作成日を確認するには、gcloud managed-kafka clusters describe コマンドを使用するか、コンソールでクラスタの詳細ページを表示します。
CA Service を構成します。クライアント証明書の発行に使用する CA サービスと CA プールを設定します。CA プール内にルート証明書と下位証明書を作成する必要があります。
1. CA プールを作成します。CA プール ID をメモします。
  
  CA プールの作成方法の詳細については、CA プールを作成するをご覧ください。
2. プールのルート CA を作成して有効にします。
  
  プールでルート CA を有効にする方法の詳細については、ルート CA を作成するをご覧ください。
3. 1 つ以上の下位 CA を作成して有効にします。ルート CA を直接使用するのではなく、クライアント証明書の発行には下位 CA を使用することをおすすめします。
  
  下位 CA の作成方法の詳細については、下位認証局を作成するをご覧ください。

必要なロールと権限

mTLS を構成するには、ユーザーと Managed Service for Apache Kafka サービスエージェントの両方に必要な IAM 権限があることを確認する必要があります。これは、新しいクラスタを作成する場合と、mTLS を構成するために既存のクラスタを更新する場合の両方に適用されます。

ユーザー権限

mTLS 用の Managed Service for Apache Kafka クラスタを作成または構成するには、クラスタリソースを作成または更新する権限が必要です。これを行うには、クラスタを含むプロジェクトに対するマネージド Kafka クラスタ編集者（roles/managedkafka.clusterEditor）ロールを付与するよう管理者に依頼してください。

この事前定義ロールには、managedkafka.clusters.create 権限と managedkafka.clusters.update 権限が含まれています。これらの権限により、新しいクラスタを作成したり、既存のクラスタを変更して mTLS に必要な CA Service（CA）プール構成を追加したりできます。

CA プールの完全なリソースパスがあれば、Kafka クラスタで mTLS を構成するために CA Service リソースに対する個別の権限は必要ありません。ただし、Google Cloud コンソールで CA プールを表示、作成、管理するには、CA Service 管理者（roles/privateca.admin）や CA Service オペレーター（roles/privateca.operator）など、CA Service 固有の追加ロールが必要です。

サービスエージェントの権限

mTLS 統合が機能するには、Managed Service for Apache Kafka サービスエージェントに、指定された CA プールにアクセスする権限が必要です。サービスエージェントは、プロジェクトの Google 管理のサービスアカウントです。

Managed Service for Apache Kafka クラスタと CA プールが同じプロジェクトにある場合、サービスエージェントにはデフォルトで必要な権限が付与されています。プロジェクトのサービスエージェントに自動的に付与される managedkafka.serviceAgent ロールには、必要な privateca.caPools.get 権限が含まれています。
CA プールが Managed Service for Apache Kafka クラスタとは異なるプロジェクトにある場合は、サービスエージェントにアクセス権を手動で付与する必要があります。CA プールを含むプロジェクトのサービスエージェントに プライベート CA プール読み取り（roles/privateca.poolReader）ロールを付与します。

必要な権限の概要

必要とされる正確な権限については、次のセクションを開いてご確認ください。

必要な権限

ユーザーの権限:

managedkafka.clusters.create: mTLS 用に構成された新しい Kafka クラスタを作成するために必要です。
managedkafka.clusters.update: 既存の Kafka クラスタを更新して mTLS を構成するために必要です。

Managed Service for Apache Kafka サービスエージェントの権限:

privateca.caPools.get: サービスエージェントが CA プールにアクセスするために必要です。これは roles/privateca.poolReader ロールに含まれています。

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

サービスエージェントに CA プールへのアクセス権を付与する

CA Service CA プールと Managed Service for Apache Kafka クラスタが異なる Google Cloud プロジェクトにある場合は、クラスタのサービスエージェントに CA プールへのアクセス権を付与する必要があります。Managed Service for Apache Kafka サービスエージェントの名前は service-CLUSTER_PROJECT_NUMBER@gcp-sa-managedkafka.iam.gserviceaccount.com です。

CA を含む個々のプール単位（推奨）またはプロジェクト内のすべてのプールで、Managed Service for Apache Kafka サービスエージェントに CA プール閲覧者（roles/privateca.poolReader）ロールを付与します。このロールには、必要な privateca.caPools.get 権限が付与されています。

個々の CA プール

単一の CA プールに権限を付与する方法は、最小権限の原則に沿っているため、おすすめします。

gcloud privateca pools add-iam-policy-binding コマンドを実行します。

gcloud privateca pools add-iam-policy-binding CA_POOL_ID \
    --location=CA_POOL_LOCATION \
    --member='serviceAccount:service-CLUSTER_PROJECT_NUMBER@gcp-sa-managedkafka.iam.gserviceaccount.com' \
    --role='roles/privateca.poolReader'

次のように置き換えます。

CA_POOL_ID: アクセス権を付与する CA プールの ID。例: test-mtls-pool1
CA_POOL_LOCATION: CA プールが配置されている Google Cloud リージョン。例: us-central1
CLUSTER_PROJECT_NUMBER: Managed Service for Apache Kafka クラスタを含むプロジェクトのプロジェクト番号。例: 12341234123

すべての CA プール

また、プロジェクトレベルでポリシーを設定して、プロジェクト内のすべての CA プールにアクセスする権限をサービスエージェントに付与することもできます。

gcloud projects add-iam-policy-binding コマンドを実行します。

gcloud projects add-iam-policy-binding CA_PROJECT_ID \
    --member='serviceAccount:service-CLUSTER_PROJECT_NUMBER@gcp-sa-managedkafka.iam.gserviceaccount.com' \
    --role='roles/privateca.poolReader'

次のように置き換えます。

CA_PROJECT_ID: アクセス権を付与する CA プールを含むプロジェクトの ID。例: test-cas-project
CLUSTER_PROJECT_NUMBER: Managed Service for Apache Kafka クラスタを含むプロジェクトのプロジェクト番号。例: 12341234123

クラスタで mTLS を有効にする

mTLS を有効にするには、クライアント認証に使用する 1 つ以上の CA Service CA プールのリソース名をクラスタに指定します。これは、新しいクラスタを作成するとき、または 2025 年 6 月 24 日以降に作成された既存のクラスタを更新するときに行うことができます。

CA プール ID を指定すると、サービスは指定されたプールから CA 証明書を自動的にダウンロードし、クラスタ内の各ブローカーのトラストストアにインストールします。

コンソール

mTLS は、作成時に新しいクラスタで有効にするか、既存のクラスタを編集して有効にできます。

新しいクラスタの場合

Google Cloud コンソールで、[クラスタ] ページに移動します。

クラスタに移動
[作成] を選択します。
[Kafka クラスタの作成] ページが開きます。
クラスタを作成するの手順に沿って操作します。
最後の手順の前に、オプションの mTLS 構成のセクションを見つけます。
CA プールの完全なリソース名を projects/PROJECT_ID/LOCATION/LOCATION/caPools/POOL_ID の形式で入力します。
さらに追加するには、[CA プールを追加] をクリックします。CA プールは 10 個まで追加できます。
（省略可）プリンシパルマッピングルールを入力します。
[作成] をクリックして、mTLS を有効にしてクラスタを作成します。

既存クラスタの場合

Google Cloud コンソールで、[クラスタ] ページに移動します。
クラスタに移動
更新するクラスタの名前をクリックします。
[編集] をクリックします。
[mTLS 構成] セクションで、CA プールのリストを追加または変更します。CA プールは 10 個まで追加できます。
（省略可）プリンシパルマッピングルールを入力または編集します。
[保存] をクリックします。

gcloud

新しいクラスタの場合

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.

--mtls-ca-pools フラグを指定して gcloud managed-kafka clusters create コマンドを実行します。この例では、2 つの CA プールが構成されています。

gcloud managed-kafka clusters create CLUSTER_ID \
    --location=LOCATION \
    --cpu=3 \
    --memory=3GiB \
    --subnets=projects/PROJECT_ID/locations/LOCATION/subnetworks/SUBNET_ID \
    --mtls-ca-pools=projects/PROJECT_ID/locations/LOCATION/caPools/POOL_ID_1,projects/PROJECT_ID/locations/LOCATION/caPools/POOL_ID_2

次のように置き換えます。

CLUSTER_ID: クラスタの ID または名前。
クラスタの命名方法の詳細については、 Managed Service for Apache Kafka リソースの命名ガイドラインをご覧ください。例: test-mtls-cluster
LOCATION: クラスタのロケーション。
サポートされているロケーションの詳細については、サポートされている Managed Service for Apache Kafka のロケーションをご覧ください。例: us-central1
SUBNETS: 接続するサブネットのリスト。複数のサブネット値を指定する場合は、カンマで区切ります。
サブネットの形式は projects/PROJECT_ID/locations/LOCATION/subnetworks/SUBNET_ID です。

POOL_ID_1: 最初の CA プールの ID。例: test-mtls-pool1

POOL_ID_2: 2 番目の CA プールの ID。例: test-mtls-pool2

既存クラスタの場合

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.
gcloud managed-kafka clusters update コマンドを使用します。このコマンドは、現在構成されているプールセット全体を上書きします。必要な CA プールの完全なリストを指定します。この例では、2 つの CA プールが構成されています。
```
gcloud managed-kafka clusters update CLUSTER_ID \
    --location=LOCATION \
    --mtls-ca-pools=projects/PROJECT_ID/locations/LOCATION/caPools/POOL_ID_1,projects/PROJECT_ID/locations/LOCATION/caPools/POOL_ID_2
```

次のように置き換えます。

CLUSTER_ID: クラスタの ID または名前。
クラスタの命名方法の詳細については、 Managed Service for Apache Kafka リソースの命名ガイドラインをご覧ください。例: test-mtls-cluster
LOCATION: クラスタのロケーション。
サポートされているロケーションの詳細については、サポートされている Managed Service for Apache Kafka のロケーションをご覧ください。例: us-central1

POOL_ID_1: 最初の CA プールの ID。例: test-mtls-pool1

POOL_ID_2: 2 番目の CA プールの ID。例: test-mtls-pool2

プリンシパル名マッピングを構成する

クライアントが mTLS で認証する場合、デフォルトでは Kafka プリンシパルは証明書のサブジェクト識別名（DN）から派生し、User:CN=...,OU=...,O=...,L=...,ST=...,C=... の形式になります。証明書のサブジェクト DN を、Kafka ACL で使いやすい便利なエイリアスに変換するマッピングルールを作成します。サブジェクト DN の形式の詳細については、Apache Kafka ドキュメントの SSL ユーザー名のカスタマイズをご覧ください。

これらの変換は、正規表現を使用して証明書のサブジェクトの一部を抽出して再フォーマットする ssl.principal.mapping.rules Kafka ブローカープロパティによって定義されます。

たとえば、次のようにルールを適用して、完全なサブジェクト DN をエイリアスに変換できます。

証明書のサブジェクト DN: CN=order-processing-app,OU=marketing,O=company,C=US
マッピングルール: RULE:^.*[Cc][Nn]=([a-zA-Z0-9.-]*).*$/$1/L,DEFAULT
結果の Kafka プリンシパル: order-processing-app

このルールの例では、証明書のサブジェクトから共通名（CN）を抽出し、Kafka のプリンシパル名として使用します。

Google Cloud CLI を使用してクラスタにマッピングルールを設定する手順は次のとおりです。コンソールを使用する場合は、クラスタの作成時または更新時にマッピングルールを設定できます。

クラスタを更新するには、--ssl-principal-mapping-rules フラグを指定して gcloud managed-kafka clusters update コマンドを使用します。
```
gcloud managed-kafka clusters update CLUSTER_ID \
    --location=REGION \
    --ssl-principal-mapping-rules='MAPPING_RULE'
```
次のように置き換えます。
- CLUSTER_ID: 作成する Managed Service for Apache Kafka クラスタの ID。例: test-kafka-cluster。
- REGION: クラスタを作成する Google Cloud リージョン。例: us-central1
- MAPPING_RULE*: 適用するマッピングルール。例: RULE:^.*[Cc][Nn]=([a-zA-Z0-9.-]*).*$/$1/L,DEFAULT。

マッピングルールの作成方法については、Apache Kafka ドキュメントの認可と ACL をご覧ください。

mTLS プリンシパルの Kafka ACL を構成する

デフォルトでは、有効な mTLS 証明書で認証に成功したクライアントには、クラスタへのフルアクセス権が付与されます。最小権限の原則を適用するには、Kafka ACL を作成して、mTLS プリンシパルの特定の権限を定義する必要があります。mTLS クライアントのプリンシパルは、証明書のサブジェクト DN（またはマッピングされたエイリアス）に User: を付けたものです。

Kafka ACL を作成するには、マネージド Kafka ACL 編集者（roles/managedkafka.aclEditor）IAM ロールが必要です。

証明書で識別されるアプリケーションがあり、orders-topic にメッセージを生成し、analytics-topic からメッセージを使用するとします。マッピングルールで簡略化されたアプリケーションのプリンシパルは order-processing-app です。Kafka ACL を作成する場合は、プリンシパルの前に User: を付ける必要があります。

WRITE ACL をクラスタに適用します。gcloud managed-kafka acls add-entry コマンドを実行して、orders-topic に対する WRITE 権限を付与します。
```
gcloud managed-kafka acls add-entry topic/orders-topic \
    --cluster=CLUSTER_ID \
    --location=REGION \
    --principal=User:order-processing-app \
    --operation=WRITE \
    --permission-type=ALLOW \
    --host="*"
```
次のように置き換えます。
- CLUSTER_ID: 作成する Managed Service for Apache Kafka クラスタの ID。例: test-kafka-cluster。
- REGION: クラスタを作成する Google Cloud リージョン。例: us-central1

READ ACL をクラスタに適用します。gcloud managed-kafka acls add-entry コマンドを実行して、analytics-topic に対する READ 権限を付与します。

gcloud managed-kafka acls add-entry topic/analytics-topic \
    --cluster=CLUSTER_ID \
    --location=REGION \
    --principal=User:order-processing-app \
    --operation=READ \
    --permission-type=ALLOW \
    --host="*"

これらの ACL を適用すると、order-processing-app クライアントには付与した特定の権限のみが付与されます。ACL の作成方法の詳細については、Kafka ACL を作成するをご覧ください。

Kafka クライアントを構成する

クラスタで mTLS を構成したら、この方法を使用して認証するようにクライアントアプリケーションを構成する必要があります。このプロセスでは、クライアント証明書を作成し、それを使用するようにクライアントのプロパティを構成します。

クライアントマシンでクライアント証明書を作成してダウンロードします。gcloud privateca certificates create コマンドを実行して、クラスタ用に構成した CA プールのいずれかから新しい証明書を発行します。

このコマンドは、証明書 client-cert.pem とその秘密鍵 client-key.pem をローカル環境にダウンロードします。
```
gcloud privateca certificates create CERTIFICATE_ID \
    --project=PROJECT_ID \
    --issuer-location=REGION \
    --issuer-pool=POOL_ID \
    --ca=CA_NAME \
    --generate-key \
    --dns-san="client.example.com" \
    --subject="CN=test-client-app" \
    --key-output-file=client-key.pem \
    --cert-output-file=client-cert.pem
```
次のように置き換えます。
- CERTIFICATE_ID: 証明書オブジェクトの一意の名前。例: order-app-cert
- PROJECT_ID: CA プールを含むプロジェクトの ID。例: test-project-12345
- REGION: CA プールが配置されているリージョン。例: us-central1
- POOL_ID: 証明書を発行する CA プールの ID。例: test-mtls-pool1
- CA_NAME: プール内の認証局の名前。例: test-sub-ca
- --dns-san="client.example.com": DNS サブジェクト代替名。クライアントに関連する任意の値を使用できます。
- --subject="CN=test-client-app": 主体者識別名。この名前は、プリンシパル名マッピングルールを構成していない限り、mTLS プリンシパルとして使用されます。

クライアント証明書を表示し、証明書のサブジェクトを表示して、ssl.principal.mapping.rules を確認します。gcloud privateca certificates describe コマンドを実行する

gcloud privateca certificates describe CERTIFICATE_ID \
   --issuer-pool=POOL_ID \
   --issuer-location=REGION

次のように置き換えます。

CERTIFICATE_ID: 証明書オブジェクトの一意の名前。例: order-app-cert
POOL_ID: 証明書を発行した CA プールの ID。例: test-mtls-pool1
REGION: CA プールが配置されているリージョン。例: us-central1

出力は次のようになります。

certificateDescription:
  aiaIssuingCertificateUrls:
  - http://privateca-content-68e092f4-0000-288c-95cf-30fd3814648c.storage.googleapis.com/a6553d092bbedd752e34/ca.crt
  authorityKeyId:
    keyId: 9568aa9d2baa11a097addc2e24adeaebea0d6a2a
  certFingerprint:
    sha256Hash: 230e52b8411fd094048fca194fc6cf80e41b3e8561298aec3519e13cb1fd05eb
  ...
  subjectDescription:
    hexSerialNumber: 2107b74cf5a814043a38a87eeb6cd7c7891a5f
    lifetime: P30D
    notAfterTime: '2025-07-13T15:34:43Z'
    notBeforeTime: '2025-06-13T15:34:44Z'
    subject:
      commonName: test-client-app
    subjectAltName:
      dnsNames:
      - client.example.com
  ...

Java キーストアを作成します。証明書と秘密鍵を PKCS#12 ファイルに結合し、Java キーストア（.jks）ファイルにインポートします。

# Create a password for the keystore
export KEYSTORE_PASSWORD="KEYSTORE_PASSWORD"

# Combine the key and cert into a PKCS#12 file
openssl pkcs12 -export -inkey client-key.pem -in client-cert.pem \
  -name client -out client-keystore.p12 -password "pass:$KEYSTORE_PASSWORD"

# Import the PKCS#12 file into a Java KeyStore
keytool -importkeystore -srckeystore client-keystore.p12 -srcstoretype pkcs12 \
  -destkeystore client-keystore.jks -srcstorepass "$KEYSTORE_PASSWORD" -deststorepass "$KEYSTORE_PASSWORD"

次のコマンドを実行して、鍵が正常に保存されたことを確認できます。

keytool -v -list -keystore client-keystore.jks -storepass "$KEYSTORE_PASSWORD"

出力は次のようになります。

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

Alias name: client
Creation date: Jun 13, 2024
Entry type: Private key entry
Certificate chain length: 1
Certificate[1]:
Owner: CN=test-client-app
Issuer: CN=test-sub-ca
...

Owner 行には証明書のサブジェクト DN が表示されます。デフォルトでは、Kafka は Kafka プリンシパルを CN=...,OU=...,O=...,L=...,ST=...,C=... という形式に設定します。詳細については、Apache Kafka ドキュメントの認可と ACL をご覧ください。

Kafka クライアントのプロパティとブートストラップアドレスを構成します。Kafka クライアントアプリケーションで、次のプロパティを設定して、SSL 接続にキーストアを使用します。また、ポート 9192 で正しいブートストラップアドレスを使用していることを確認してください。クライアントの設定方法については、クイックスタート: Managed Service for Apache Kafka クラスタを作成してクライアントを接続するをご覧ください。
```
security.protocol=SSL
ssl.keystore.location=KEYSTORE_LOCATION
ssl.keystore.password=KEYSTORE_PASSWORD
bootstrap.servers=CLUSTER_BOOTSTRAP_ADDRESS
```
次のように置き換えます。
- KEYSTORE_LOCATION: .jks ファイルのパス。
- KEYSTORE_PASSWORD: キーストアのパスワード。
- CLUSTER_BOOTSTRAP_ADDRESS: クラスタのブートストラップアドレス。ブートストラップアドレスを確認するには、クラスタの詳細を表示するをご覧ください。ポート番号を 9192 として追加してください。

クライアント構成を保護する

上記の例では、秘密鍵とパスワードをローカルに保存するため、本番環境にはおすすめしません。本番環境では、クライアントシークレットを安全に処理します。選択できるオプションは次のとおりです:

キーストアとそのパスワードを Google Cloud Secret Manager のシークレットとして保存し、実行時にアプリケーションコードで取得します。
GKE にアプリケーションをデプロイする場合は、Secret Manager アドオンを使用して、実行時にシークレットをアプリケーションのファイルシステムにマウントします。

mTLS をモニタリングする

Cloud Monitoring と Cloud Logging の指標とログを使用して、mTLS 証明書の更新の健全性をモニタリングできます。

mTLS 証明書の更新の健全性をプロアクティブにモニタリングするには、Monitoring の managedkafka.googleapis.com/mtls_truststore_update_count 指標を使用します。この指標は、トラストストアの更新試行回数をカウントし、STATUS ラベルを含みます。このラベルは SUCCESS または CA_POOL_FETCH_ERROR などの失敗理由になります。

Managed Service for Apache Kafka サービスは、クラスタごとに 1 時間に 1 回、トラストストアの更新を試みます。この指標で 3 時間以上エラー数が継続的に報告された場合にアラートが発生するように作成することをおすすめします。これは、手動での介入が必要な構成ミスを示している可能性があります。

トラストストアの更新では、Certificate Authority Service API の割り当てが消費されます。次の点を理解することが重要です。

更新プロセスは FetchCaCerts メソッドを呼び出します。このメソッドは API requests per minute per region 割り当ての対象となります。
この割り当て使用量は、Managed Service for Apache Kafka プロジェクトではなく、参照された CA プールを含むプロジェクトに割り当てられます。
デフォルトの上限は、リージョンあたり 1 秒あたりのクエリ数（QPS）が 400 です。クラスタごとに 1 時間に 1 回のリクエストという頻度を考えると、これらのトラストストアの更新によってこの割り当てを超える可能性は低いと考えられます。

Logging でログを表示して、トラストストアの更新を追跡することもできます。更新が成功したことを確認するには、次のログエントリを探します。

Managed Service for Apache Kafka updated the mTLS trust store
Added root CA certificate to trust store

次のステップ

クラスタを作成する方法を学ぶ。
クラスタの詳細を表示する方法を確認する。

Apache Kafka® は、Apache Software Foundation または米国その他の諸国における関連会社の商標です。

mTLS 認証を構成する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

必要なロールと権限

必要な権限

サービス エージェントに CA プールへのアクセス権を付与する

個々の CA プール

すべての CA プール

クラスタで mTLS を有効にする

コンソール

新しいクラスタの場合

既存クラスタの場合

gcloud

新しいクラスタの場合

既存クラスタの場合

プリンシパル名マッピングを構成する

mTLS プリンシパルの Kafka ACL を構成する

Kafka クライアントを構成する

クライアント構成を保護する

mTLS をモニタリングする

次のステップ

mTLS 認証を構成する

サービスエージェントに CA プールへのアクセス権を付与する