Configura la autenticación mTLS

Puedes configurar tu clúster de Managed Service para Apache Kafka para autenticar clientes de Kafka con TLS mutua (mTLS). Este método usa certificados de cliente de Certificate Authority Service (CA Service) como base para la autenticación. Esta opción proporciona una alternativa al mecanismo SASL predeterminado que usa principales de Identity and Access Management (IAM).

Cuando usas mTLS, la autorización se debe configurar con las LCA de Kafka. Para conocer los conceptos básicos, consulta los siguientes documentos:

Antes de comenzar

Antes de configurar la autenticación de mTLS, completa los siguientes pasos:

  • Confirma la elegibilidad del clúster. Verifica que tengas un clúster existente de Managed Service for Apache Kafka creado después del 24 de junio de 2025. Solo estos clústeres admiten la autenticación de mTLS. Para verificar la fecha de creación de tu clúster, usa el comando gcloud managed-kafka clusters describe o consulta la página de detalles del clúster en la consola.

  • Configura el servicio de CA. Configura el servicio de CA y los grupos de CA que planeas usar para emitir certificados de cliente. Debes crear certificados raíz y subordinados dentro de los grupos de CA.

    1. Crea un grupo de CA. Anota el ID del grupo de la AC.

      Para obtener más información sobre cómo crear un grupo de CA, consulta Crea un grupo de CA.

    2. Crea y habilita una CA raíz para el grupo.

      Para obtener más información sobre cómo habilitar una CA raíz para el grupo, consulta Crea una CA raíz.

    3. Crea y habilita una o más CA subordinadas. Te recomendamos que uses una CA subordinada para emitir certificados de cliente en lugar de usar una CA raíz directamente.

      Para obtener más información sobre cómo crear una CA subordinada, consulta Crea una autoridad de certificación subordinada.

Roles y permisos requeridos

Para configurar mTLS, debes asegurarte de que tanto tú (el usuario) como el agente de servicio del servicio administrado para Apache Kafka tengan los permisos de IAM necesarios. Esto se aplica tanto si creas un clúster nuevo como si actualizas uno existente para configurar mTLS.

Permisos del usuario

Para crear o configurar un clúster de Servicio administrado para Apache Kafka para mTLS, necesitas permisos para crear o actualizar el recurso del clúster. Para ello, pídele a tu administrador que te otorgue el rol de Editor de clústeres de Kafka administrado (roles/managedkafka.clusterEditor) en el proyecto que contiene tu clúster.

Este rol predefinido contiene los permisos managedkafka.clusters.create y managedkafka.clusters.update. Estos permisos te permiten crear un clúster nuevo o modificar uno existente para agregar la configuración del grupo de CA Service (CA) que se requiere para mTLS.

No necesitas permisos separados en los recursos de CA Service para configurar mTLS en el clúster de Kafka, siempre y cuando tengas la ruta de acceso completa del grupo de CA. Sin embargo, para ver, crear o administrar grupos de AC en la consola deGoogle Cloud , necesitarás roles adicionales específicos del servicio de CA, como Administrador del servicio de CA (roles/privateca.admin) o Operador del servicio de CA (roles/privateca.operator).

Permisos del agente de servicio

Para que la integración de mTLS funcione, el agente de servicio de Managed Service para Apache Kafka requiere permiso para acceder al grupo de CA especificado. El agente de servicio es una cuenta de servicio administrada por Google para tu proyecto.

  • Si tu clúster de Managed Service para Apache Kafka y el grupo de CA se encuentran en el mismo proyecto, el agente de servicio tiene los permisos necesarios de forma predeterminada. El rol managedkafka.serviceAgent, que se otorga automáticamente al agente de servicio en tu proyecto, incluye el permiso privateca.caPools.get requerido.

  • Si tu grupo de entidades certificadoras está en un proyecto diferente al de tu clúster de Managed Service para Apache Kafka, debes otorgar permiso al agente de servicio de forma manual para acceder a él. Otorga el rol de lector de grupos de CA privadas (roles/privateca.poolReader) al agente de servicio en el proyecto que contiene el grupo de CA.

Resumen de los permisos necesarios

Para ver los permisos exactos necesarios, expande la siguiente sección.

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Otorga acceso al agente de servicio a los grupos de CA

Si tu grupo de entidades certificadoras del servicio de CA y tu clúster de Managed Service para Apache Kafka se encuentran en Google Cloud proyectos diferentes, debes otorgar permiso al agente de servicio del clúster para acceder al grupo de entidades certificadoras. El agente de servicio de Managed Service para Apache Kafka se llama service-CLUSTER_PROJECT_NUMBER@gcp-sa-managedkafka.iam.gserviceaccount.com.

Otorga el rol de lector de grupos de AC (roles/privateca.poolReader) al agente de servicio de Managed Service para Apache Kafka a nivel del grupo individual (recomendado) que contiene tus AC o en todos los grupos del proyecto. Este rol proporciona el permiso privateca.caPools.get necesario.

Grupo de CA individual

Otorgar permisos a un solo grupo de CA es el enfoque recomendado, ya que sigue el principio de privilegio mínimo.

Ejecuta el comando 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'

Reemplaza lo siguiente:

  • CA_POOL_ID: Es el ID del grupo de AC al que otorgas acceso. Por ejemplo, test-mtls-pool1

  • CA_POOL_LOCATION: Es la Google Cloud región en la que se encuentra el grupo de AC. Por ejemplo, us-central1.

  • CLUSTER_PROJECT_NUMBER: Es el número del proyecto que contiene tu clúster de Managed Service para Apache Kafka. Por ejemplo, 12341234123

Todos los grupos de AC

Como alternativa, puedes otorgar permiso al agente de servicio para acceder a todos los grupos de entidades certificadoras dentro de un proyecto configurando la política a nivel del proyecto.

Ejecuta el comando 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'

Reemplaza lo siguiente:

  • CA_PROJECT_ID: Es el ID del proyecto que contiene los grupos de AC a los que otorgas acceso. Por ejemplo, test-cas-project

  • CLUSTER_PROJECT_NUMBER: Es el número del proyecto que contiene tu clúster de Managed Service para Apache Kafka. Por ejemplo, 12341234123

Habilita la mTLS en un clúster

Para habilitar mTLS, proporciona a tu clúster los nombres de recursos de uno o más grupos de AC del servicio de CA para usar en la autenticación del cliente. Puedes hacerlo cuando crees un clúster nuevo o actualices uno existente que se haya creado después del 24 de junio de 2025.

Después de que proporciones los identificadores del grupo de AC, el servicio descargará automáticamente los certificados de AC de los grupos especificados y los instalará en el almacén de confianza de cada agente del clúster.

Console

Puedes habilitar mTLS en un clúster nuevo durante la creación o en un clúster existente editándolo.

En un clúster nuevo

  1. En la consola de Google Cloud , ve a la página Clústeres.

    Ir a los clústeres

  2. Selecciona Crear.

    Se abre la página Crear clúster de Kafka.

  3. Sigue los pasos en Crea un clúster.
  4. Antes del paso final, busca la sección Configuración opcional de mTLS.
  5. Ingresa el nombre completo del recurso de un grupo de CA con el siguiente formato: projects/PROJECT_ID/LOCATION/LOCATION/caPools/POOL_ID.
  6. Para agregar más, haz clic en Agregar grupo de AC. Puedes agregar hasta 10 grupos de CA.
  7. (Opcional) Ingresa las reglas de asignación de principales que desees.
  8. Haz clic en Crear para crear el clúster con mTLS habilitado.

En un clúster existente

  1. En la consola de Google Cloud , ve a la página Clústeres.

    Ir a los clústeres

  2. Haz clic en el nombre del clúster que deseas actualizar.
  3. Haz clic en Editar.
  4. En la sección Configuración de mTLS, agrega o modifica la lista de grupos de CA. Puedes agregar hasta 10 grupos de CA.
  5. (Opcional) Ingresa o edita las reglas de asignación de principales.
  6. Haz clic en Guardar.

gcloud

En un clúster nuevo

  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. Ejecuta el comando gcloud managed-kafka clusters create con la marca --mtls-ca-pools. En este ejemplo, se configuran dos grupos de 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

Reemplaza lo siguiente:

En un clúster existente

  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. Usa el comando gcloud managed-kafka clusters update. Este comando reemplaza todo el conjunto de grupos configurados actualmente. Proporciona la lista completa de los grupos de CA requeridos. En este ejemplo, se configuran dos grupos de 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

Reemplaza lo siguiente:

Configura la asignación de nombres principales

Cuando un cliente se autentica con mTLS, de forma predeterminada, la entidad principal de Kafka se deriva del nombre distintivo (DN) del sujeto del certificado y tiene la forma User:CN=...,OU=...,O=...,L=...,ST=...,C=.... Crea reglas de asignación para transformar el DN del sujeto del certificado en un alias conveniente que sea más fácil de usar en las LCA de Kafka. Para obtener más información sobre el formulario del DN del sujeto, consulta Cómo personalizar el nombre de usuario de SSL en la documentación de Apache Kafka.

Estas transformaciones se definen con la propiedad del agente de Kafka ssl.principal.mapping.rules, que usa expresiones regulares para extraer y reformatear partes del sujeto del certificado.

Por ejemplo, puedes aplicar una regla para transformar un DN de asunto completo en un alias de la siguiente manera:

  • DN del sujeto del certificado: CN=order-processing-app,OU=marketing,O=company,C=US

  • Regla de asignación: RULE:^.*[Cc][Nn]=([a-zA-Z0-9.-]*).*$/$1/L,DEFAULT

  • Principal de Kafka resultante: order-processing-app

Esta regla de ejemplo extrae el nombre común (CN) del sujeto del certificado y lo usa como nombre principal en Kafka.

Para establecer una regla de asignación en tu clúster con Google Cloud CLI, sigue estos pasos. Cuando usas la consola, puedes establecer las reglas de asignación mientras creas o actualizas un clúster.

  • Para actualizar tu clúster, usa el comando gcloud managed-kafka clusters update con la marca --ssl-principal-mapping-rules.

    gcloud managed-kafka clusters update CLUSTER_ID \
    --location=REGION \
    --ssl-principal-mapping-rules='MAPPING_RULE'

    Reemplaza lo siguiente:

    • CLUSTER_ID: Es el ID del clúster de Managed Service para Apache Kafka que estás creando. Por ejemplo, test-kafka-cluster.

    • REGION: Es la Google Cloud región en la que se creará el clúster. Por ejemplo: us-central1.

    • MAPPING_RULE*: Es la regla de asignación que deseas aplicar. Por ejemplo, RULE:^.*[Cc][Nn]=([a-zA-Z0-9.-]*).*$/$1/L,DEFAULT.

Para obtener más información sobre cómo escribir reglas de asignación, consulta Autorización y ACL en la documentación de Apache Kafka.

Configura las LCA de Kafka para los principales de mTLS

De forma predeterminada, cualquier cliente que se autentique correctamente con un certificado de mTLS válido obtiene acceso completo al clúster. Para aplicar el principio de privilegio mínimo, debes crear ACL de Kafka para definir permisos específicos para tus principales de mTLS. El principal de un cliente de mTLS es el DN del sujeto de su certificado (o un alias asignado), con el prefijo User:.

Para crear LCA de Kafka, necesitas el rol de IAM de Editor de ACL de Kafka administrado (roles/managedkafka.aclEditor).

Supongamos que tienes una aplicación identificada por su certificado que produce mensajes para orders-topic y consume mensajes de analytics-topic. El principal de la aplicación, después de simplificarse con una regla de asignación, es order-processing-app. Cuando creas LCA de Kafka, debes agregar el prefijo User: al principal.

  1. Aplica la ACL de WRITE al clúster. Ejecuta el comando gcloud managed-kafka acls add-entry para otorgar permiso de WRITE en orders-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="*"

    Reemplaza lo siguiente:

    • CLUSTER_ID: Es el ID del clúster de Managed Service para Apache Kafka que estás creando. Por ejemplo, test-kafka-cluster.

    • REGION: Es la Google Cloud región en la que se creará el clúster. Por ejemplo: us-central1.

  2. Aplica la ACL de READ al clúster. Ejecuta el comando gcloud managed-kafka acls add-entry para otorgar permiso de READ en analytics-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="*"

Después de aplicar estas LCA, el cliente de order-processing-app solo tendrá los permisos específicos que le otorgaste. Para obtener más información sobre cómo crear LCA, consulta Crea LCA de Kafka.

Configura clientes de Kafka

Después de configurar mTLS en tu clúster, debes configurar tus aplicaciones cliente para que se autentiquen con este método. El proceso implica crear un certificado de cliente y configurar las propiedades de tu cliente para que lo use.

  1. Crea y descarga un certificado de cliente en tu máquina cliente. Ejecuta el comando gcloud privateca certificates create para emitir un certificado nuevo desde uno de los grupos de CA que configuraste para tu clúster.

    Este comando descarga el certificado client-cert.pem y su clave privada client-key.pem en tu entorno 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.pem

    Reemplaza lo siguiente:

    • CERTIFICATE_ID: Es un nombre único para el objeto de certificado. Por ejemplo: order-app-cert.

    • PROJECT_ID: Es el ID del proyecto que contiene el grupo de AC. Por ejemplo: test-project-12345.

    • REGION: Es la región en la que se encuentra el grupo de AC. Por ejemplo: us-central1.

    • POOL_ID: Es el ID del grupo de CA desde el que se emitirá el certificado. Por ejemplo: test-mtls-pool1.

    • CA_NAME: Es el nombre de la entidad certificadora dentro del grupo. Por ejemplo: test-sub-ca.

    • --dns-san="client.example.com": Es el nombre alternativo del sujeto del DNS. Puedes usar cualquier valor que sea relevante para tu cliente.

    • --subject="CN=test-client-app": Es el DN del sujeto. Este nombre se usa como principal de mTLS, a menos que hayas configurado una regla de asignación de nombres principales.

  2. Visualiza el certificado de cliente, el asunto del certificado y verifica ssl.principal.mapping.rules. Ejecuta el comando gcloud privateca certificates describe:

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

    Reemplaza lo siguiente:

    • CERTIFICATE_ID: Es el nombre único del objeto de certificado. Por ejemplo: order-app-cert.

    • POOL_ID: Es el ID del grupo de AC desde el que emitiste el certificado. Por ejemplo: test-mtls-pool1.

    • REGION: Es la región en la que se encuentra el grupo de AC. Por ejemplo: us-central1.

    El resultado es similar a lo siguiente:

    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
  ...

  3. Crea un almacén de claves de Java. Combina el certificado y la clave privada en un archivo PKCS#12 y, luego, impórtalo a un archivo de almacén de claves 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"

    Para verificar que la clave se haya almacenado de forma correcta, ejecuta el siguiente comando:

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

    El resultado es similar a lo siguiente:

    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
...

    Ten en cuenta que la línea Owner muestra el DN del sujeto del certificado. De forma predeterminada, Kafka establece el principal de Kafka en este formato exacto: CN=...,OU=...,O=...,L=...,ST=...,C=.... Para obtener más información, consulta Autorización y ACL en la documentación de Apache Kafka.

  4. Configura las propiedades del cliente de Kafka y la dirección de inicio. En tu aplicación cliente de Kafka, configura las siguientes propiedades para usar el almacén de claves para una conexión SSL. Además, asegúrate de usar la dirección de arranque correcta con el puerto 9192. Si deseas obtener más información para configurar un cliente, consulta Inicio rápido: Crea un clúster de Managed Service para Apache Kafka y conecta un cliente.

    security.protocol=SSL
ssl.keystore.location=KEYSTORE_LOCATION
ssl.keystore.password=KEYSTORE_PASSWORD
bootstrap.servers=CLUSTER_BOOTSTRAP_ADDRESS

    Reemplaza lo siguiente:

    • KEYSTORE_LOCATION: Es la ruta de acceso al archivo .jks.

    • KEYSTORE_PASSWORD: Es la contraseña del almacén de claves.

    • CLUSTER_BOOTSTRAP_ADDRESS: Es la dirección de inicio del clúster. Para encontrar la dirección de inicio, consulta Cómo ver los detalles del clúster. Asegúrate de agregar el número de puerto como 9192.

Protege la configuración de tu cliente

En el ejemplo anterior, se almacenan contraseñas y claves privadas de forma local, por lo que no lo recomendamos para entornos de producción. Para la producción, controla tus secretos de cliente de forma segura. Las opciones incluyen las siguientes:

  • Almacena el almacén de claves y su contraseña como secretos en Secret Manager de Google Cloud y recupéralos en el tiempo de ejecución en el código de tu aplicación.

  • Si implementas tu aplicación en GKE, usa el complemento de Secret Manager para activar los secretos en el sistema de archivos de tu aplicación durante el tiempo de ejecución.

Supervisa la mTLS

Puedes supervisar el estado de las actualizaciones de certificados de mTLS con métricas y registros en Cloud Monitoring y Cloud Logging.

Para supervisar de forma proactiva el estado de las actualizaciones de certificados de mTLS, usa la métrica managedkafka.googleapis.com/mtls_truststore_update_count en Monitoring. Esta métrica contabiliza los intentos de actualización del almacén de confianza y también incluye una etiqueta STATUS, que puede ser SUCCESS o un motivo de falla, como CA_POOL_FETCH_ERROR.

El servicio de Managed Service para Apache Kafka intenta actualizar el almacén de confianza una vez por hora para cada clúster. Te recomendamos que crees una alerta que se active cuando esta métrica informe un recuento persistente de errores durante más de tres horas, ya que esto podría indicar un error de configuración que requiere intervención manual.

Las actualizaciones del almacén de confianza consumen la cuota de la API de Certificate Authority Service. Es importante que comprendas lo siguiente:

  • El proceso de actualización llama al método FetchCaCerts, que está sujeto a la cuota de API requests per minute per region.

  • Este uso de la cuota se atribuye a tu proyecto que contiene el grupo de CA al que se hace referencia, y no al proyecto de Managed Service for Apache Kafka.

  • El límite predeterminado es de 400 consultas por segundo (QPS) por región. Dada la baja frecuencia de una solicitud por clúster por hora, es poco probable que estas actualizaciones del almacén de confianza hagan que superes esta cuota.

También puedes hacer un seguimiento de las actualizaciones del almacén de confianza viendo los registros en Logging. Busca las siguientes entradas de registro para confirmar que las actualizaciones se realizaron correctamente:

  • Managed Service for Apache Kafka updated the mTLS trust store

  • Added root CA certificate to trust store

¿Qué sigue?

Apache Kafka® es una marca registrada de The Apache Software Foundation o sus afiliados en Estados Unidos y otros países.