Apache Kafka 4.1.0 с аутентификацией Keycloak OAuth2

Production-ready Apache Kafka 4.1.0 (режим KRaft) с аутентификацией Keycloak 26.1.1 OAuth2/OIDC с использованием образа Strimzi Kafka.

Почему этот проект вместо kafka-oauth-keycloak-tls-demo

Это эволюция предыдущего POC со значительными улучшениями:

• Strimzi OAuth 0.17.0 (вместо 1.0.0) — стабильная production-версия, встроенная в образ Strimzi Kafka 0.48.0
• Не требуется пользовательская сборка Docker — используется официальный образ Strimzi с предустановленным OAuth, что устраняет сложность Dockerfile
• Осведомлённость о CVE-2025-27817 — документировано ограничение списка разрешённых URL и причина, по которой Strimzi OAuth обходит его
• Упрощённая архитектура — единый комбинированный режим KRaft (брокер+контроллер), а не разделённая архитектура
• Фокус на клиенте librdkafka — протестировано с confluent-kafka-python (работает без проблем со списком разрешённых URL), а не с нативными Java-клиентами
• Комплексная техническая документация — производственный чек-лист, устранение неполадок, настройка производительности, детали маппинга principal
• Более чистое управление сертификатами — включены примеры сертификатов для немедленного тестирования
• Автоматизированная настройка Keycloak — скриптовое создание realm/клиента/маппера с настройкой аудитории
• Работающий набор тестов Python — проверяет сквозную доставку сообщений через OAuth
• Явная обработка URL эмитента — документирована двойственность внутреннего и внешнего URL для токен-эндпоинта и проверки эмитента

Архитектура

• Дистрибутив Kafka: образ Strimzi Kafka 0.48.0 (включает Apache Kafka 4.1.0 + предустановленный Strimzi OAuth 0.17.0)
• Версия Kafka: Apache Kafka 4.1.0 (KRaft, комбинированный брокер+контроллер)
• Библиотека OAuth: Strimzi Kafka OAuth 0.17.0 (встроена в образ, обходит ограничение списка разрешённых URL CVE-2025-27817)
• Провайдер OAuth: Keycloak 26.1.1
• Безопасность: SASL_SSL (OAuth) для внешних клиентов, PLAINTEXT для межброкерного взаимодействия, SSL с самоподписанным CA

Контекст CVE-2025-27817

Apache Kafka 4.0.0+ ввёл список разрешённых URL (org.apache.kafka.sasl.oauthbearer.allowed.urls) как системное свойство JVM для устранения уязвимости SSRF/произвольного чтения файлов. Это нарушает стандартное использование OAuth в нативных клиентах Apache Kafka.

Решение: библиотека Strimzi Kafka OAuth не реализует это ограничение, что обеспечивает функциональность OAuth с Kafka 4.1.0.

Предварительные требования

• Docker Compose
• Python 3.x с uv (для тестирования)
• OpenSSL (для генерации сертификатов)

Быстрый старт

# Генерация SSL-сертификатов
cd kafka-security
./generate-certs.sh
cd ..

# Запуск сервисов
docker compose up -d

# Проверка Keycloak
curl http://localhost:8080/health/ready

# Настройка realm и клиентов Keycloak
./scripts/setup-keycloak.sh

# Тест OAuth-продюсера
source ~/.venv/bin/activate
uv pip install confluent-kafka
python tests/quick_test.py

Сетевая топология

keycloak:8080 (HTTP) ←→ kafka-broker:9093 (SASL_SSL/OAuth)
                      ↔ kafka-broker:19092 (PLAINTEXT/межброкерный)
                      ↔ kafka-broker:29093 (PLAINTEXT/контроллер KRaft)

Конфигурация SSL

Структура CA

• Корневой CA: kafka-security/ca-cert + ca-key
• Хранилище ключей брокера: kafka-security/broker/kafka.server.keystore.jks (содержит сертификат сервера + закрытый ключ)
• Хранилище доверия брокера: kafka-security/broker/kafka.server.truststore.jks (содержит сертификат CA)
• Пароль: changeit (все хранилища ключей/доверия)

Детали сертификата

# Сертификат брокера
CN=kafka-broker
SAN=DNS:kafka-broker,DNS:localhost,IP:127.0.0.1

# Срок действия: 3650 дней
# Алгоритм ключа: RSA 2048 бит
# Алгоритм подписи: SHA256withRSA

Конфигурация OAuth Keycloak

Realm: kafka-realm

Клиенты

kafka-broker (конфиденциальный)

• Client ID: kafka-broker
• Client Secret: автоматически генерируется setup-keycloak.sh
• Назначение: межброкерная OAuth-аутентификация
• Мапперы:
  • Маппер аудитории: добавляет kafka-broker в claim aud JWT
  • Маппер имени пользователя: включает preferred_username в токен

kafka-producer (конфиденциальный)

• Client ID: kafka-producer
• Client Secret: автоматически генерируется
• Назначение: внешние клиенты-продюсеры
• Grant: client_credentials
• Мапперы: те же, что у kafka-broker

kafka-consumer (конфиденциальный)

• Client ID: kafka-consumer
• Client Secret: автоматически генерируется
• Назначение: внешние клиенты-потребители
• Grant: client_credentials
• Мапперы: те же, что у kafka-broker

Токен-эндпоинт

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-токена

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

Конфигурация Kafka

Режим KRaft (kraft-config.properties)

# Идентификатор узла
node.id=1
process.roles=broker,controller
controller.quorum.voters=1@kafka-broker:29093

# Слушатели
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
sasl.enabled.mechanisms=OAUTHBEARER

# Обработчики Strimzi OAuth (для каждого слушателя 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 через 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";

Ключевые параметры Strimzi OAuth

• oauth.client.id: идентификатор клиента для получения токена
• oauth.client.secret: секрет клиента для получения токена
• oauth.token.endpoint.uri: токен-эндпоинт Keycloak (брокер использует внутреннее имя хоста keycloak:8080)
• oauth.valid.issuer.uri: ожидаемый эмитент JWT (должен совпадать с claim iss токена, используется внешний localhost:8080)
• oauth.jwks.endpoint.uri: эндпоинт JWKS для проверки подписи JWT
• oauth.username.claim: claim JWT для извлечения principal

Авторизация

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

Примечание: в настоящее время разрешающая конфигурация для тестирования. В production следует использовать ACL.

Конфигурация клиента

Python-продюсер (confluent-kafka)

from confluent_kafka import Producer