Apache Kafka 4.1.0 mit Keycloak OAuth2-Authentifizierung

Produktionsreifes Apache Kafka 4.1.0 (KRaft-Modus) mit Keycloak 26.1.1 OAuth2/OIDC-Authentifizierung unter Verwendung des Strimzi-Kafka-Images.

Warum dieses Projekt vs. kafka-oauth-keycloak-tls-demo

Dies ist eine Weiterentwicklung des vorherigen POC mit erheblichen Verbesserungen:

• Strimzi OAuth 0.17.0 (statt 1.0.0) – stabile Produktionsversion, gebündelt im Strimzi-Kafka-0.48.0-Image
• Kein benutzerdefinierter Docker-Build erforderlich – verwendet das offizielle Strimzi-Image mit vorinstalliertem OAuth, eliminiert die Dockerfile-Komplexität
• CVE-2025-27817-Bewusstsein – dokumentiert die URL-Allowlist-Einschränkung und warum Strimzi OAuth diese umgeht
• Vereinfachte Architektur – einzelner KRaft-Kombinationsmodus (Broker+Controller), keine Split-Architektur
• librdkafka-Client-Fokus – getestet mit confluent-kafka-python (funktioniert ohne URL-Allowlist-Probleme), nicht mit nativen Java-Clients
• Umfassende technische Dokumentation – Produktions-Checkliste, Fehlerbehebung, Leistungsoptimierung, Principal-Mapping-Details
• Saubereres Zertifikatsmanagement – enthaltene Beispielzertifikate für sofortiges Testen
• Automatisierte Keycloak-Einrichtung – skriptierte Realm-/Client-/Mapper-Erstellung mit Audience-Konfiguration
• Funktionierende Python-Testsuite – validiert die OAuth-End-to-End-Nachrichtenzustellung
• Explizite Issuer-URL-Behandlung – dokumentiert die Dualität von interner vs. externer URL für Token-Endpunkt vs. Issuer-Validierung

Architektur

• Kafka-Distribution: Strimzi-Kafka-Image 0.48.0 (enthält Apache Kafka 4.1.0 + Strimzi OAuth 0.17.0 vorinstalliert)
• Kafka-Version: Apache Kafka 4.1.0 (KRaft-Kombination aus Broker+Controller)
• OAuth-Bibliothek: Strimzi Kafka OAuth 0.17.0 (im Image gebündelt, umgeht die CVE-2025-27817-URL-Allowlist-Einschränkung)
• OAuth-Anbieter: Keycloak 26.1.1
• Sicherheit: SASL_SSL (OAuth) für externe Clients, PLAINTEXT für Inter-Broker, SSL mit selbstsignierter CA

CVE-2025-27817-Kontext

Apache Kafka 4.0.0+ führte eine URL-Allowlist (org.apache.kafka.sasl.oauthbearer.allowed.urls) als JVM-Systemeigenschaft ein, um die SSRF-/beliebige-Dateilesen-Schwachstelle zu beheben. Dies bricht die Standard-OAuth-Nutzung in nativen Apache-Kafka-Clients.

Lösung: Die Strimzi-Kafka-OAuth-Bibliothek implementiert diese Einschränkung nicht und ermöglicht so die OAuth-Funktionalität mit Kafka 4.1.0.

Voraussetzungen

• Docker Compose
• Python 3.x mit uv (für Tests)
• OpenSSL (für die Zertifikatserstellung)

Schnellstart

# SSL-Zertifikate generieren
cd kafka-security
./generate-certs.sh
cd ..

# Dienste starten
docker compose up -d

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

# Keycloak-Realm und Clients einrichten
./scripts/setup-keycloak.sh

# OAuth-Producer testen
source ~/.venv/bin/activate
uv pip install confluent-kafka
python tests/quick_test.py

Netzwerktopologie

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

SSL-Konfiguration

CA-Struktur

• Root-CA: kafka-security/ca-cert + ca-key
• Broker-Keystore: kafka-security/broker/kafka.server.keystore.jks (enthält Serverzertifikat + privaten Schlüssel)
• Broker-Truststore: kafka-security/broker/kafka.server.truststore.jks (enthält CA-Zertifikat)
• Passwort: changeit (alle Keystores/Truststores)

Zertifikatsdetails

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

# Gültigkeit: 3650 Tage
# Schlüsselalgorithmus: RSA 2048-Bit
# Signaturalgorithmus: SHA256withRSA

Keycloak-OAuth-Konfiguration

Realm: kafka-realm

Clients

kafka-broker (vertraulich)

• Client-ID: kafka-broker
• Client-Secret: Automatisch generiert von setup-keycloak.sh
• Zweck: OAuth-Authentifizierung zwischen Brokern
• Mapper:
  • Audience-Mapper: fügt kafka-broker zum JWT-aud-Anspruch hinzu
  • Benutzername-Mapper: enthält preferred_username im Token

kafka-producer (vertraulich)

• Client-ID: kafka-producer
• Client-Secret: Automatisch generiert
• Zweck: Externe Producer-Clients
• Grant: client_credentials
• Mapper: Wie bei kafka-broker

kafka-consumer (vertraulich)

• Client-ID: kafka-consumer
• Client-Secret: Automatisch generiert
• Zweck: Externe Consumer-Clients
• Grant: client_credentials
• Mapper: Wie bei kafka-broker

Token-Endpunkt

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

JWT-Token-Struktur

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

Kafka-Konfiguration

KRaft-Modus (kraft-config.properties)

# Knotenidentität
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

# SASL-Mechanismus
sasl.enabled.mechanisms=OAUTHBEARER

# Strimzi-OAuth-Handler (pro Listener für 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

# OAuth-Konfiguration über 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";

Wichtige Strimzi-OAuth-Parameter

• oauth.client.id: Client-Kennung für die Token-Beschaffung
• oauth.client.secret: Client-Secret für die Token-Beschaffung
• oauth.token.endpoint.uri: Keycloak-Token-Endpunkt (Broker verwendet internen Hostnamen keycloak:8080)
• oauth.valid.issuer.uri: Erwarteter JWT-Issuer (muss mit dem Token-iss-Anspruch übereinstimmen, verwendet externes localhost:8080)
• oauth.jwks.endpoint.uri: JWKS-Endpunkt für die JWT-Signaturvalidierung
• oauth.username.claim: JWT-Anspruch für die Principal-Extraktion

Autorisierung

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

Hinweis: Derzeit permissiv für Tests. In der Produktion sollten ACLs verwendet werden.

Client-Konfiguration

Python-Producer (confluent-kafka)

from confluent_kafka import Producer