Apache Kafka 4.1.0 con autenticazione OAuth2 Keycloak

Apache Kafka 4.1.0 pronto per la produzione (modalità KRaft) con autenticazione OAuth2/OIDC Keycloak 26.1.1 utilizzando l'immagine Kafka Strimzi.

Perché questo progetto vs kafka-oauth-keycloak-tls-demo

Questa è un'evoluzione del POC precedente con miglioramenti significativi:

• Strimzi OAuth 0.17.0 (vs 1.0.0) - versione di produzione stabile inclusa nell'immagine Strimzi Kafka 0.48.0
• Nessuna build Docker personalizzata richiesta - utilizza l'immagine Strimzi ufficiale con OAuth preinstallato, elimina la complessità del Dockerfile
• Consapevolezza CVE-2025-27817 - documenta la restrizione della allowlist URL e perché Strimzi OAuth la bypassa
• Architettura semplificata - modalità combinata KRaft singola (broker+controller), non architettura divisa
• Focus sul client librdkafka - testato con confluent-kafka-python (funziona senza problemi di allowlist URL), non client Java nativi
• Documentazione tecnica completa - checklist di produzione, risoluzione dei problemi, ottimizzazione delle prestazioni, dettagli sul mapping dei principal
• Gestione certificati più pulita - certificati di esempio inclusi per test immediati
• Setup Keycloak automatizzato - creazione scriptata di realm/client/mapper con configurazione audience
• Suite di test Python funzionante - valida la consegna dei messaggi OAuth end-to-end
• Gestione esplicita dell'URL issuer - documenta la dualità URL interno vs esterno per token endpoint vs validazione issuer

Architettura

• Distribuzione Kafka: immagine Strimzi Kafka 0.48.0 (include Apache Kafka 4.1.0 + Strimzi OAuth 0.17.0 preinstallato)
• Versione Kafka: Apache Kafka 4.1.0 (KRaft combinato broker+controller)
• Libreria OAuth: Strimzi Kafka OAuth 0.17.0 (inclusa nell'immagine, bypassa la restrizione allowlist URL CVE-2025-27817)
• Provider OAuth: Keycloak 26.1.1
• Sicurezza: SASL_SSL (OAuth) per client esterni, PLAINTEXT per inter-broker, SSL con CA autofirmata

Contesto CVE-2025-27817

Apache Kafka 4.0.0+ ha introdotto la allowlist URL (org.apache.kafka.sasl.oauthbearer.allowed.urls) come proprietà di sistema JVM per correggere la vulnerabilità SSRF/lettura file arbitraria. Questo interrompe l'uso OAuth standard nei client Apache Kafka nativi.

Soluzione: la libreria Strimzi Kafka OAuth non implementa questa restrizione, abilitando la funzionalità OAuth con Kafka 4.1.0.

Prerequisiti

• Docker Compose
• Python 3.x con uv (per i test)
• OpenSSL (per la generazione dei certificati)

Avvio Rapido

# Genera i certificati SSL
cd kafka-security
./generate-certs.sh
cd ..

# Avvia i servizi
docker compose up -d

# Verifica Keycloak
curl http://localhost:8080/health/ready

# Configura realm e client Keycloak
./scripts/setup-keycloak.sh

# Test del producer OAuth
source ~/.venv/bin/activate
uv pip install confluent-kafka
python tests/quick_test.py

Topologia di Rete

keycloak:8080 (HTTP) ←→ kafka-broker:9093 (SASL_SSL/OAuth)
                      ↔ kafka-broker:19092 (PLAINTEXT/inter-broker)
                      ↔ kafka-broker:29093 (PLAINTEXT/controller KRaft)

Configurazione SSL

Struttura CA

• CA radice: kafka-security/ca-cert + ca-key
• Keystore broker: kafka-security/broker/kafka.server.keystore.jks (contiene certificato server + chiave privata)
• Truststore broker: kafka-security/broker/kafka.server.truststore.jks (contiene certificato CA)
• Password: changeit (tutti i keystore/truststore)

Dettagli Certificato

# Certificato broker
CN=kafka-broker
SAN=DNS:kafka-broker,DNS:localhost,IP:127.0.0.1

# Validità: 3650 giorni
# Algoritmo chiave: RSA 2048-bit
# Algoritmo firma: SHA256withRSA

Configurazione OAuth Keycloak

Realm: kafka-realm

Client

kafka-broker (confidenziale)

• Client ID: kafka-broker
• Client Secret: generato automaticamente da setup-keycloak.sh
• Scopo: autenticazione OAuth inter-broker
• Mapper:
  • Mapper audience: aggiunge kafka-broker al claim JWT aud
  • Mapper username: include preferred_username nel token

kafka-producer (confidenziale)

• Client ID: kafka-producer
• Client Secret: generato automaticamente
• Scopo: client producer esterni
• Grant: client_credentials
• Mapper: come kafka-broker

kafka-consumer (confidenziale)

• Client ID: kafka-consumer
• Client Secret: generato automaticamente
• Scopo: client consumer esterni
• Grant: client_credentials
• Mapper: come kafka-broker

Token Endpoint

POST http://localhost:8080/realms/kafka-realm/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=kafka-producer
&client_secret=<secret>
&scope=profile email

Struttura Token JWT

{
  "aud": ["kafka-broker", "account"],
  "iss": "http://localhost:8080/realms/kafka-realm",
  "azp": "kafka-producer",
  "preferred_username": "service-account-kafka-producer",
  "scope": "profile email"
}

Configurazione Kafka

Modalità KRaft (kraft-config.properties)

# Identità nodo
node.id=1
process.roles=broker,controller
controller.quorum.voters=1@kafka-broker:29093

# Listener
listeners=SASL_SSL://0.0.0.0:9093,PLAINTEXT://0.0.0.0:19092,CONTROLLER://0.0.0.0:29093
advertised.listeners=SASL_SSL://localhost:9093,PLAINTEXT://kafka-broker:19092
listener.security.protocol.map=SASL_SSL:SASL_SSL,PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
inter.broker.listener.name=PLAINTEXT
controller.listener.names=CONTROLLER

# Meccanismo SASL
sasl.enabled.mechanisms=OAUTHBEARER

# Handler Strimzi OAuth (per listener per SASL_SSL)
listener.name.sasl_ssl.oauthbearer.sasl.login.callback.handler.class=io.strimzi.kafka.oauth.client.JaasClientOauthLoginCallbackHandler
listener.name.sasl_ssl.oauthbearer.sasl.server.callback.handler.class=io.strimzi.kafka.oauth.server.JaasServerOauthValidatorCallbackHandler

# Configurazione OAuth tramite JAAS
listener.name.sasl_ssl.oauthbearer.sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
  oauth.client.id="kafka-broker" \
  oauth.client.secret="<secret>" \
  oauth.token.endpoint.uri="http://keycloak:8080/realms/kafka-realm/protocol/openid-connect/token" \
  oauth.valid.issuer.uri="http://localhost:8080/realms/kafka-realm" \
  oauth.jwks.endpoint.uri="http://keycloak:8080/realms/kafka-realm/protocol/openid-connect/certs" \
  oauth.username.claim="preferred_username";

Parametri Chiave Strimzi OAuth

• oauth.client.id: identificatore client per l'acquisizione del token
• oauth.client.secret: secret client per l'acquisizione del token
• oauth.token.endpoint.uri: token endpoint Keycloak (il broker usa il nome host interno keycloak:8080)
• oauth.valid.issuer.uri: issuer JWT atteso (deve corrispondere al claim iss del token, usa localhost:8080 esterno)
• oauth.jwks.endpoint.uri: endpoint JWKS per la validazione della firma JWT
• oauth.username.claim: claim JWT per l'estrazione del principal

Autorizzazione

authorizer.class.name=org.apache.kafka.metadata.authorizer.StandardAuthorizer
super.users=User:kafka-broker;User:ANONYMOUS
allow.everyone.if.no.acl.found=true

Nota: attualmente permissivo per i test. La produzione dovrebbe usare ACL.

Configurazione Client

Producer Python (confluent-kafka)

from confluent_kafka import Producer