Vous pouvez configurer votre cluster Managed Service pour Apache Kafka afin d'authentifier les clients Kafka à l'aide du protocole TLS mutuel (mTLS). Cette méthode utilise des certificats clients de Certificate Authority Service (CA Service) comme base pour l'authentification. Cette option constitue une alternative au mécanisme SASL par défaut qui utilise les comptes principaux Identity and Access Management (IAM).
Lorsque vous utilisez mTLS, l'autorisation doit être configurée à l'aide des LCA Kafka. Pour découvrir les concepts de base, consultez les documents suivants :
Avant de commencer
Avant de configurer l'authentification mTLS, procédez comme suit :
Vérifiez l'éligibilité du cluster. Vérifiez que vous disposez d'un cluster Managed Service pour Apache Kafka créé après le 24 juin 2025. Seuls ces clusters sont compatibles avec l'authentification mTLS. Pour vérifier la date de création de votre cluster, utilisez la commande
gcloud managed-kafka clusters describeou affichez la page d'informations du cluster dans la console.Configurez le service d'autorité de certification. Configurez le service CA et les pools d'autorités de certification que vous prévoyez d'utiliser pour émettre des certificats client. Vous devez créer des certificats racine et subordonnés dans les pools d'autorités de certification.
Créez un pool d'autorités de certification. Notez l'ID du pool d'autorités de certification.
Pour savoir comment créer un pool d'autorités de certification, consultez Créer un pool d'autorités de certification.
Créez et activez une autorité de certification racine pour le pool.
Pour savoir comment activer une autorité de certification racine pour le pool, consultez Créer une autorité de certification racine.
Créez et activez une ou plusieurs autorités de certification subordonnées. Nous vous recommandons d'utiliser une autorité de certification subordonnée pour émettre des certificats client plutôt que d'utiliser directement une autorité de certification racine.
Pour savoir comment créer une autorité de certification subordonnée, consultez Créer une autorité de certification subordonnée.
Rôles et autorisations nécessaires
Pour configurer l'authentification mTLS, vous devez vous assurer que vous (l'utilisateur) et l'agent de service Managed Service pour Apache Kafka disposez des autorisations IAM nécessaires. Cela s'applique que vous créiez un cluster ou que vous en mettiez à jour un existant pour configurer mTLS.
Autorisations utilisateur
Pour créer ou configurer un cluster Managed Service pour Apache Kafka pour mTLS, vous devez disposer des autorisations nécessaires pour créer ou mettre à jour la ressource de cluster. Pour ce faire, demandez à votre administrateur de vous attribuer le rôle Éditeur de cluster Kafka géré (roles/managedkafka.clusterEditor) sur le projet contenant votre cluster.
Ce rôle prédéfini contient les autorisations managedkafka.clusters.create et managedkafka.clusters.update. Ces autorisations vous permettent de créer un cluster ou de modifier un cluster existant pour ajouter la configuration du pool CA Service (CA) requise pour mTLS.
Vous n'avez pas besoin d'autorisations distinctes sur les ressources CA Service pour configurer mTLS sur le cluster Kafka, à condition de disposer du chemin d'accès complet à la ressource du pool d'autorités de certification. Toutefois, pour afficher, créer ou gérer des pools d'autorités de certification dans la consoleGoogle Cloud , vous aurez besoin de rôles supplémentaires spécifiques au service d'autorité de certification, tels que Administrateur de services d'autorité de certification (roles/privateca.admin) ou Opérateur de services d'autorité de certification (roles/privateca.operator).
Autorisations de l'agent de service
Pour que l'intégration mTLS fonctionne, l'agent de service Managed Service pour Apache Kafka doit être autorisé à accéder au pool d'autorités de certification spécifié. L'agent de service est un compte de service géré par Google pour votre projet.
Si votre cluster Managed Service pour Apache Kafka et le pool d'autorité de certification se trouvent dans le même projet, l'agent de service dispose par défaut des autorisations nécessaires. Le rôle
managedkafka.serviceAgent, automatiquement accordé à l'agent de service sur votre projet, inclut l'autorisationprivateca.caPools.getrequise.Si votre pool d'autorité de certification se trouve dans un projet différent de votre cluster Managed Service pour Apache Kafka, vous devez accorder manuellement à l'agent de service l'autorisation d'y accéder. Accordez le rôle Lecteur de pool d'autorités de certification privées (
roles/privateca.poolReader) à l'agent de service sur le projet contenant le pool d'autorités de certification.
Récapitulatif des autorisations requises
Pour afficher les autorisations exactes requises, développez la section suivante.
Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.
Accorder à l'agent de service l'accès aux pools d'AC
Si votre pool d'AC CA Service et votre cluster Managed Service pour Apache Kafka se trouvent dans des projets Google Cloud différents, vous devez autoriser l'agent de service du cluster à accéder au pool d'AC. L'agent de service Managed Service pour Apache Kafka est nommé service-CLUSTER_PROJECT_NUMBER@gcp-sa-managedkafka.iam.gserviceaccount.com.
Accordez le rôle Lecteur de pool d'autorités de certification (roles/privateca.poolReader) à l'agent de service Managed Service pour Apache Kafka au niveau du pool individuel (recommandé) qui contient vos autorités de certification ou dans tous les pools du projet.
Ce rôle fournit l'autorisation privateca.caPools.get nécessaire.
Pool d'autorités de certification individuel
Il est recommandé d'accorder des autorisations à un seul pool d'AC, car cela suit le principe du moindre privilège.
Exécutez la commande
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'
Remplacez les éléments suivants :
-
CA_POOL_ID : ID du pool d'autorités de certification auquel vous accordez l'accès. Exemple :
test-mtls-pool1 CA_POOL_LOCATION : région Google Cloud où se trouve le pool d'autorités de certification. Par exemple,
us-central1.-
CLUSTER_PROJECT_NUMBER : numéro du projet contenant votre cluster Managed Service pour Apache Kafka. Exemple :
12341234123
Tous les pools d'autorités de certification
Vous pouvez également accorder à l'agent de service l'autorisation d'accéder à tous les pools d'AC d'un projet en définissant la règle au niveau du projet.
Exécutez la commande
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'
Remplacez les éléments suivants :
-
CA_PROJECT_ID : ID du projet contenant les pools d'autorités de certification auxquels vous accordez l'accès. Exemple :
test-cas-project -
CLUSTER_PROJECT_NUMBER : numéro du projet contenant votre cluster Managed Service pour Apache Kafka. Exemple :
12341234123
Activer mTLS sur un cluster
Pour activer mTLS, fournissez à votre cluster les noms de ressources d'un ou de plusieurs pools d'autorités de certification CA Service à utiliser pour l'authentification du client. Vous pouvez le faire lorsque vous créez un cluster ou en mettant à jour un cluster existant créé après le 24 juin 2025.
Une fois que vous avez fourni les identifiants du pool d'autorités de certification, le service télécharge automatiquement les certificats d'autorité de certification à partir des pools spécifiés et les installe dans le truststore de chaque agent du cluster.
Console
Vous pouvez activer mTLS sur un nouveau cluster lors de sa création ou sur un cluster existant en le modifiant.
Sur un nouveau cluster
Dans la console Google Cloud , accédez à la page Clusters.
- Sélectionnez Créer.
La page Créer un cluster Kafka s'ouvre.
- Suivez la procédure décrite dans Créer un cluster.
- Avant la dernière étape, recherchez la section Configuration mTLS facultative.
- Saisissez le nom de ressource complet d'un pool d'autorités de certification au format
projects/PROJECT_ID/LOCATION/LOCATION/caPools/POOL_ID. - Pour en ajouter d'autres, cliquez sur Ajouter un pool d'autorités de certification. Vous pouvez ajouter jusqu'à 10 pools d'AC.
- (Facultatif) Saisissez des règles de mappage de comptes principaux.
- Cliquez sur Créer pour créer le cluster avec le chiffrement mTLS activé.
Sur un cluster existant
- Dans la console Google Cloud , accédez à la page Clusters.
- Cliquez sur le nom du cluster que vous souhaitez mettre à jour.
- Cliquez sur Modifier.
- Dans la section Configuration mTLS, ajoutez ou modifiez la liste des pools d'autorités de certification. Vous pouvez ajouter jusqu'à 10 pools d'AC.
- (Facultatif) Saisissez ou modifiez les règles de mappage des comptes principaux.
- Cliquez sur Enregistrer.
gcloud
Sur un nouveau cluster
-
In the Google Cloud console, 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.
-
Exécutez la commande
gcloud managed-kafka clusters createavec l'option--mtls-ca-pools. Dans cet exemple, deux pools d'AC sont configurés.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
Remplacez les éléments suivants :
-
CLUSTER_ID : ID ou nom du cluster.
Pour en savoir plus sur la façon de nommer un cluster, consultez les consignes de dénomination des ressources Managed Service pour Apache Kafka. Par exemple,
test-mtls-cluster. -
LOCATION : emplacement du cluster.
Pour en savoir plus sur les emplacements compatibles, consultez Emplacements Managed Service pour Apache Kafka compatibles. Par exemple,
us-central1. -
SUBNETS : liste des sous-réseaux à connecter. Utilisez des virgules pour séparer plusieurs valeurs de sous-réseau.
Le format du sous-réseau est
projects/PROJECT_ID/locations/LOCATION/subnetworks/SUBNET_ID. -
POOL_ID_2 : ID du deuxième pool d'autorités de certification. Par exemple,
test-mtls-pool2.
POOL_ID_1 : ID du premier pool d'autorités de certification.
Par exemple, test-mtls-pool1.
Sur un cluster existant
-
In the Google Cloud console, 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.
-
Exécutez la commande
gcloud managed-kafka clusters update. Cette commande écrase l'ensemble des pools actuellement configurés. Fournissez la liste complète des pools d'autorités de certification requis. Dans cet exemple, deux pools d'AC sont configurés.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
Remplacez les éléments suivants :
-
CLUSTER_ID : ID ou nom du cluster.
Pour en savoir plus sur la façon de nommer un cluster, consultez les consignes de dénomination des ressources Managed Service pour Apache Kafka. Par exemple,
test-mtls-cluster. -
LOCATION : emplacement du cluster.
Pour en savoir plus sur les emplacements compatibles, consultez Emplacements Managed Service pour Apache Kafka compatibles. Par exemple,
us-central1. -
POOL_ID_2 : ID du deuxième pool d'autorités de certification. Par exemple,
test-mtls-pool2.
POOL_ID_1 : ID du premier pool d'autorités de certification.
Par exemple, test-mtls-pool1.
Configurer le mappage des noms de principaux
Lorsqu'un client s'authentifie avec mTLS, le principal Kafka est dérivé par défaut du nom unique de l'objet (DN) du certificat et se présente sous la forme User:CN=...,OU=...,O=...,L=...,ST=...,C=....
Créez des règles de mappage pour transformer le nom unique du sujet du certificat en alias pratique et plus facile à utiliser dans les LCA Kafka.
Pour en savoir plus sur le format du nom unique du sujet, consultez Personnaliser le nom d'utilisateur SSL dans la documentation Apache Kafka.
Ces transformations sont définies par la propriété de broker Kafka ssl.principal.mapping.rules, qui utilise des expressions régulières pour extraire et reformater des parties du sujet du certificat.
Par exemple, vous pouvez appliquer une règle pour transformer un nom unique de sujet complet en alias comme suit :
Nom distinctif de l'objet du certificat :
CN=order-processing-app,OU=marketing,O=company,C=USRègle de mappage :
RULE:^.*[Cc][Nn]=([a-zA-Z0-9.-]*).*$/$1/L,DEFAULTPrincipal Kafka résultant :
order-processing-app
Cet exemple de règle extrait le nom commun (CN) de l'objet du certificat et l'utilise comme nom principal dans Kafka.
Pour définir une règle de mappage sur votre cluster à l'aide de Google Cloud CLI, procédez comme suit. Lorsque vous utilisez la console, vous pouvez définir les règles de mappage lors de la création ou de la mise à jour d'un cluster.
Pour mettre à jour votre cluster, utilisez la commande
gcloud managed-kafka clusters updateavec l'option--ssl-principal-mapping-rules.gcloud managed-kafka clusters update CLUSTER_ID \ --location=REGION \ --ssl-principal-mapping-rules='MAPPING_RULE'Remplacez les éléments suivants :
CLUSTER_ID: ID du cluster Managed Service pour Apache Kafka que vous créez. Par exemple :test-kafka-cluster.REGION: région Google Cloud dans laquelle créer le cluster. Par exemple,us-central1.MAPPING_RULE*: règle de mappage que vous souhaitez appliquer. Par exemple :RULE:^.*[Cc][Nn]=([a-zA-Z0-9.-]*).*$/$1/L,DEFAULT.
Pour savoir comment écrire des règles de mappage, consultez Autorisation et LCA dans la documentation Apache Kafka.
Configurer les LCA Kafka pour les principaux mTLS
Par défaut, tout client qui s'authentifie avec succès à l'aide d'un certificat mTLS valide se voit accorder un accès complet au cluster. Pour appliquer le principe du moindre privilège, vous devez créer des LCA Kafka afin de définir des autorisations spécifiques pour vos principaux mTLS. Le principal d'un client mTLS est le nom unique du sujet de son certificat (ou un alias mappé), précédé de User:.
Pour créer des LCA Kafka, vous avez besoin du rôle IAM Éditeur de LCA Managed Kafka (roles/managedkafka.aclEditor).
Supposons que vous disposez d'une application identifiée par son certificat qui produit des messages pour orders-topic et consomme des messages provenant de analytics-topic. Le principal de l'application, après simplification avec une règle de mappage, est order-processing-app. Lorsque vous créez des LCA Kafka, vous devez préfixer le principal avec User:.
Appliquez la LCA
WRITEau cluster. Exécutez la commandegcloud managed-kafka acls add-entrypour accorder l'autorisationWRITEsurorders-topic.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="*"Remplacez les éléments suivants :
CLUSTER_ID: ID du cluster Managed Service pour Apache Kafka que vous créez. Par exemple :test-kafka-cluster.REGION: région Google Cloud dans laquelle créer le cluster. Par exemple,us-central1.
Appliquez la LCA
READau cluster. Exécutez la commandegcloud managed-kafka acls add-entrypour accorder l'autorisationREADsuranalytics-topic.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="*"
Après avoir appliqué ces LCA, le client order-processing-app ne dispose que des autorisations spécifiques que vous lui avez accordées. Pour savoir comment créer des LCA, consultez Créer des LCA Kafka.
Configurer les clients Kafka
Après avoir configuré mTLS sur votre cluster, vous devez configurer vos applications clientes pour qu'elles s'authentifient à l'aide de cette méthode. Pour ce faire, vous devez créer un certificat client et configurer les propriétés de votre client pour qu'il l'utilise.
Créez et téléchargez un certificat client sur votre machine cliente. Exécutez la commande
gcloud privateca certificates createpour émettre un nouveau certificat à partir de l'un des pools d'AC que vous avez configurés pour votre cluster.Cette commande télécharge le certificat
client-cert.pemet sa clé privéeclient-key.pemdans votre environnement local.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.pemRemplacez les éléments suivants :
CERTIFICATE_ID: nom unique de l'objet de certificat. Par exemple,order-app-cert.PROJECT_ID: ID du projet contenant le pool d'autorités de certification. Par exemple,test-project-12345.REGION: région où se trouve le pool d'autorités de certification. Par exemple,us-central1.POOL_ID: ID du pool d'autorités de certification à partir duquel émettre le certificat. Par exemple,test-mtls-pool1.CA_NAME: nom de l'autorité de certification dans le pool. Par exemple,test-sub-ca.--dns-san="client.example.com": autre nom d'objet DNS Vous pouvez utiliser n'importe quelle valeur pertinente pour votre client.--subject="CN=test-client-app": nom distinctif de l'objet. Ce nom est utilisé comme compte principal mTLS, sauf si vous avez configuré une règle de mappage des noms de comptes principaux.
Affichez le certificat client et son sujet, puis vérifiez
ssl.principal.mapping.rules. Exécutez la commandegcloud privateca certificates describe:gcloud privateca certificates describe CERTIFICATE_ID \ --issuer-pool=POOL_ID \ --issuer-location=REGIONRemplacez les éléments suivants :
CERTIFICATE_ID: nom unique de l'objet certificat. Par exemple,order-app-cert.POOL_ID: ID du pool d'autorités de certification à partir duquel vous avez émis le certificat. Par exemple,test-mtls-pool1.REGION: région où se trouve le pool d'autorités de certification. Par exemple,us-central1.
Le résultat ressemble à ce qui suit :
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 ...Créez un keystore Java. Combinez le certificat et la clé privée dans un fichier
PKCS#12, puis importez-le dans un fichier Java KeyStore (.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"Pour vérifier que la clé a bien été stockée, exécutez la commande suivante :
keytool -v -list -keystore client-keystore.jks -storepass "$KEYSTORE_PASSWORD"Le résultat ressemble à ce qui suit :
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 ...Notez que la ligne
Owneraffiche le nom distinctif de l'objet du certificat. Par défaut, Kafka définit le principal Kafka sur ce format exact :CN=...,OU=...,O=...,L=...,ST=...,C=.... Pour en savoir plus, consultez Autorisation et LCA dans la documentation Apache Kafka.Configurez les propriétés du client Kafka et l'adresse d'amorçage. Dans votre application cliente Kafka, définissez les propriétés suivantes pour utiliser le keystore pour une connexion SSL. Assurez-vous également d'utiliser la bonne adresse d'amorçage avec le port
9192. Pour savoir comment configurer un client, consultez Démarrage rapide : créer un cluster Managed Service pour Apache Kafka et connecter un client.security.protocol=SSL ssl.keystore.location=KEYSTORE_LOCATION ssl.keystore.password=KEYSTORE_PASSWORD bootstrap.servers=CLUSTER_BOOTSTRAP_ADDRESSRemplacez les éléments suivants :
KEYSTORE_LOCATION: chemin d'accès au fichier.jks.KEYSTORE_PASSWORD: mot de passe du keystore.CLUSTER_BOOTSTRAP_ADDRESS: adresse d'amorçage de votre cluster. Pour trouver l'adresse d'amorçage, consultez Afficher les détails du cluster. Veillez à ajouter le numéro de port sous la forme9192.
Sécuriser la configuration de votre client
L'exemple précédent implique le stockage local de clés privées et de mots de passe. Nous ne le recommandons donc pas pour les environnements de production. Pour la production, gérez vos secrets client de manière sécurisée. Vous avez le choix entre plusieurs options :
Stockez le keystore et son mot de passe sous forme de secrets dans Google Cloud Secret Manager, puis récupérez-les au moment de l'exécution dans le code de votre application.
Si vous déployez votre application sur GKE, utilisez le module complémentaire Secret Manager pour installer les secrets dans le système de fichiers de votre application au moment de l'exécution.
Surveiller mTLS
Vous pouvez surveiller l'état des mises à jour des certificats mTLS à l'aide des métriques et des journaux dans Cloud Monitoring et Cloud Logging.
Pour surveiller de manière proactive l'état des mises à jour des certificats mTLS, utilisez la métrique managedkafka.googleapis.com/mtls_truststore_update_count dans Monitoring. Cette métrique comptabilise les tentatives de mise à jour du truststore et inclut un libellé STATUS, qui peut être SUCCESS ou une raison d'échec telle que CA_POOL_FETCH_ERROR.
Le service Managed Service pour Apache Kafka tente d'actualiser le truststore une fois par heure pour chaque cluster. Nous vous recommandons de créer une alerte qui se déclenche lorsque cette métrique signale un nombre d'erreurs persistant pendant plus de trois heures. Cela peut indiquer une erreur de configuration nécessitant une intervention manuelle.
Les mises à jour du truststore consomment le quota de l'API Certificate Authority Service. Il est important de comprendre les points suivants :
Le processus de mise à jour appelle la méthode
FetchCaCerts, qui est soumise au quotaAPI requests per minute per region.Cette utilisation du quota est attribuée au projet contenant le pool d'autorité de certification référencé, et non au projet Managed Service pour Apache Kafka.
La limite par défaut est de 400 requêtes par seconde (RPS) par région. Étant donné la faible fréquence d'une requête par cluster et par heure, il est peu probable que ces mises à jour du truststore vous fassent dépasser ce quota.
Vous pouvez également suivre les mises à jour du truststore en consultant les journaux dans Logging. Recherchez les entrées de journal suivantes pour confirmer que les mises à jour ont réussi :
Managed Service for Apache Kafka updated the mTLS trust storeAdded root CA certificate to trust store
Étapes suivantes
Découvrez comment créer un cluster.
Découvrez comment afficher les détails d'un cluster.