Apache Kafka 4.1.0 com Autenticação OAuth2 via Keycloak

Apache Kafka 4.1.0 pronto para produção (modo KRaft) com autenticação OAuth2/OIDC via Keycloak 26.1.1 usando a imagem Kafka do Strimzi.

Por que Este Projeto vs kafka-oauth-keycloak-tls-demo

Esta é uma evolução do POC anterior com melhorias significativas:

• Strimzi OAuth 0.17.0 (vs 1.0.0) - versão estável de produção incluída na imagem Strimzi Kafka 0.48.0
• Sem necessidade de build Docker personalizado - usa a imagem oficial Strimzi com OAuth pré-instalado, eliminando a complexidade do Dockerfile
• Consciência do CVE-2025-27817 - documenta a restrição da lista de permissões de URL e por que o Strimzi OAuth a contorna
• Arquitetura simplificada - modo KRaft combinado único (broker+controller), não arquitetura dividida
• Foco no cliente librdkafka - testado com confluent-kafka-python (funciona sem problemas de lista de permissões de URL), não clientes Java nativos
• Documentação técnica abrangente - checklist de produção, solução de problemas, ajuste de desempenho, detalhes de mapeamento de principal
• Gerenciamento de certificados mais limpo - certificados de exemplo incluídos para testes imediatos
• Configuração automatizada do Keycloak - criação de realm/client/mapper via script com configuração de audiência
• Suíte de testes Python funcional - valida a entrega de mensagens OAuth de ponta a ponta
• Tratamento explícito da URL do emissor - documenta a dualidade de URL interna vs externa para endpoint de token vs validação de emissor

Arquitetura

• Distribuição Kafka: Imagem Strimzi Kafka 0.48.0 (inclui Apache Kafka 4.1.0 + Strimzi OAuth 0.17.0 pré-empacotado)
• Versão Kafka: Apache Kafka 4.1.0 (KRaft combinado broker+controller)
• Biblioteca OAuth: Strimzi Kafka OAuth 0.17.0 (incluída na imagem, contorna a restrição de lista de permissões de URL do CVE-2025-27817)
• Provedor OAuth: Keycloak 26.1.1
• Segurança: SASL_SSL (OAuth) para clientes externos, PLAINTEXT para inter-broker, SSL com CA autoassinada

Contexto do CVE-2025-27817

O Apache Kafka 4.0.0+ introduziu uma lista de permissões de URL (org.apache.kafka.sasl.oauthbearer.allowed.urls) como propriedade de sistema JVM para corrigir a vulnerabilidade de SSRF/leitura arbitrária de arquivos. Isso quebra o uso padrão de OAuth em clientes Apache Kafka nativos.

Solução: A biblioteca Strimzi Kafka OAuth não implementa essa restrição, permitindo a funcionalidade OAuth com Kafka 4.1.0.

Pré-requisitos

• Docker Compose
• Python 3.x com uv (para testes)
• OpenSSL (para geração de certificados)

Início Rápido

# Gerar certificados SSL
cd kafka-security
./generate-certs.sh
cd ..

# Iniciar serviços
docker compose up -d

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

# Configurar realm e clientes do Keycloak
./scripts/setup-keycloak.sh

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

Topologia de Rede

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

Configuração SSL

Estrutura da CA

• CA Raiz: kafka-security/ca-cert + ca-key
• Keystore do Broker: kafka-security/broker/kafka.server.keystore.jks (contém certificado do servidor + chave privada)
• Truststore do Broker: kafka-security/broker/kafka.server.truststore.jks (contém certificado da CA)
• Senha: changeit (todos os keystores/truststores)

Detalhes do Certificado

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

# Validade: 3650 dias
# Algoritmo de chave: RSA 2048 bits
# Algoritmo de assinatura: SHA256withRSA

Configuração OAuth do Keycloak

Realm: kafka-realm

Clientes

kafka-broker (confidencial)

• Client ID: kafka-broker
• Client Secret: Gerado automaticamente por setup-keycloak.sh
• Finalidade: Autenticação OAuth inter-broker
• Mappers:
  • Mapper de audiência: adiciona kafka-broker à claim aud do JWT
  • Mapper de nome de usuário: inclui preferred_username no token

kafka-producer (confidencial)

• Client ID: kafka-producer
• Client Secret: Gerado automaticamente
• Finalidade: Clientes produtores externos
• Grant: client_credentials
• Mappers: Mesmos do kafka-broker

kafka-consumer (confidencial)

• Client ID: kafka-consumer
• Client Secret: Gerado automaticamente
• Finalidade: Clientes consumidores externos
• Grant: client_credentials
• Mappers: Mesmos do kafka-broker

Endpoint de Token

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

Estrutura do 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"
}

Configuração do Kafka

Modo KRaft (kraft-config.properties)

# Identidade do nó
node.id=1
process.roles=broker,controller
controller.quorum.voters=1@kafka-broker:29093

# Listeners
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

# Mecanismo SASL
sasl.enabled.mechanisms=OAUTHBEARER

# Handlers Strimzi OAuth (por listener para 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

# Configuração OAuth via 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";

Principais Parâmetros Strimzi OAuth

• oauth.client.id: Identificador do cliente para aquisição de token
• oauth.client.secret: Segredo do cliente para aquisição de token
• oauth.token.endpoint.uri: Endpoint de token do Keycloak (o broker usa o hostname interno keycloak:8080)
• oauth.valid.issuer.uri: Emissor JWT esperado (deve corresponder à claim iss do token, usa localhost:8080 externo)
• oauth.jwks.endpoint.uri: Endpoint JWKS para validação de assinatura JWT
• oauth.username.claim: Claim JWT para extração do principal

Autorização

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

Nota: Atualmente permissivo para testes. Produção deve usar ACLs.

Configuração do Cliente

Produtor Python (confluent-kafka)

from confluent_kafka import Producer