Keycloak Event Listener for RabbitMQ

Что делает расширение

Keycloak передаёт слушателю каждое событие пользователя (LOGIN, LOGOUT, REGISTER, LOGIN_ERROR, …) и каждое событие администратора (создан пользователь, выдана роль, изменён клиент, …) в тех realm, где вы его включили.

После коммита транзакции запроса слушатель публикует по одному JSON-сообщению на событие в обменник (exchange), по умолчанию amq.topic, с ключом маршрутизации вроде KK.EVENT.CLIENT.<realm>.<SUCCESS|ERROR>.<client>.<event type>.

Каждый потребитель привязывает свою очередь нужными ключами: все события, один realm, только ошибки, только изменения от администраторов.

Для кого

Для команд, у которых работает Keycloak 26, а другим сервисам нужно реагировать на его события: синхронизация пользователей, которая следит за регистрациями и изменениями аккаунтов, оповещения об ошибках входа, реакция на удаление пользователей администраторами. Если вы пользуетесь расширением aznamier, ваши потребители продолжат работать без изменений.

Установка

Скачайте и проверьте jar-файл

В каждом релизе есть jar-файл и файл keycloak-to-rabbit.sha256, оба собраны в CI из тега релиза. Проверьте jar-файл до установки: Keycloak запускает jar-файлы провайдеров со всеми своими правами.

VERSION=4.1.0
BASE=https://github.com/Mizzle-Studio/keycloak-event-listener-rabbitmq/releases/download/v$VERSION
curl -fLO "$BASE/keycloak-to-rabbit-$VERSION.jar"
curl -fLO "$BASE/keycloak-to-rabbit.sha256"
sha256sum --check keycloak-to-rabbit.sha256

На macOS проверка — shasum -a 256 --check keycloak-to-rabbit.sha256. С версии 4.1.0 в релизах есть ещё SBOM и подписанная аттестация происхождения сборки (build provenance); её проверяет GitHub CLI:

gh attestation verify keycloak-to-rabbit-$VERSION.jar --repo Mizzle-Studio/keycloak-event-listener-rabbitmq

Установите его в Keycloak

1. Положите jar-файл в каталог providers/ Keycloak (/opt/keycloak/providers/ в контейнерном образе) и удалите старые jar-файлы keycloak-to-rabbit. Если Keycloak запускается с --optimized, выполните kc.sh build.
2. Укажите слушателю ваш брокер (см. Настройка) и перезапустите Keycloak.
3. Включите слушатель в каждом realm: Realm settings › Events › Event listeners, добавьте keycloak-to-rabbitmq и нажмите Save. Или через kcadm.sh (список заменяет текущий):

kcadm.sh update realms/myrealm -s 'eventsListeners=["jboss-logging","keycloak-to-rabbitmq"]'

Для своего образа Keycloak в руководстве по установке есть Dockerfile, который при сборке скачивает jar-файл релиза и проверяет его контрольную сумму, а также примеры для Keycloak Operator и Helm-чартов.

Попробуйте в Docker Compose

Keycloak, RabbitMQ и слушатель на вашей машине: когда образы скачаны, всё готово примерно за полминуты.

git clone https://github.com/Mizzle-Studio/keycloak-event-listener-rabbitmq.git
cd keycloak-event-listener-rabbitmq/examples/docker-compose
docker compose up -d --wait

Войдите как демо-пользователь alice и прочитайте событие из очереди keycloak-events:

curl -s -o /dev/null -w '%{http_code}\n' \
  -d client_id=demo-app -d username=alice -d password=alice -d grant_type=password \
  http://localhost:8080/realms/demo/protocol/openid-connect/token

curl -s -u demo:demo -H 'content-type: application/json' \
  -d '{"count":1,"ackmode":"ack_requeue_false","encoding":"auto"}' \
  http://localhost:15672/api/queues/%2F/keycloak-events/get

Вторая команда выведет сообщение: ключ маршрутизации KK.EVENT.CLIENT.demo.SUCCESS.demo-app.LOGIN, свойства AMQP и событие в JSON. Интерфейс RabbitMQ открывается на http://localhost:15672 (demo / demo), а docker compose down -v всё удаляет. Это не продакшн-конфигурация: Keycloak работает в режиме разработки, пароли демонстрационные.

Настройка

Каждый параметр берётся из конфигурации провайдера Keycloak (spi-events-listener-keycloak-to-rabbitmq-<name>), затем из переменной окружения KK_TO_RMQ_<NAME>, затем из значения по умолчанию. При старте слушатель пишет в лог значение каждого параметра, пароли скрыты.

Задавайте параметры переменными KK_TO_RMQ_*, в командной строке (--spi-events-listener-keycloak-to-rabbitmq-use_tls=true) или в keycloak.conf и сохраняйте подчёркивания в именах: Keycloak 26.8 игнорирует переменные KC_SPI_… для пяти параметров с подчёркиванием в имени. Все способы, TLS и примеры — в руководстве по настройке.

Совместимость

На каждое изменение CI запускает интеграционный тест с настоящими контейнерами Keycloak и RabbitMQ и собранным jar-файлом: на последнем патч-релизе каждой линии Keycloak 26 от 26.0 до 26.7 и на 26.8.1 с RabbitMQ 4.3.6, а также на 26.8.1 с RabbitMQ 3.13. Раз в неделю отдельный workflow проверяет последний релиз и основную ветку на самом новом образе Keycloak, quay.io/keycloak/keycloak:latest; если тест не проходит, открывается issue с меткой keycloak-latest.

Релиз 4.1.0 прошёл интеграционный тест на:

• Keycloak 26.0.8 · RabbitMQ 4.3.6
• Keycloak 26.1.5 · RabbitMQ 4.3.6
• Keycloak 26.2.5 · RabbitMQ 4.3.6
• Keycloak 26.3.5 · RabbitMQ 4.3.6
• Keycloak 26.4.7 · RabbitMQ 4.3.6
• Keycloak 26.5.7 · RabbitMQ 4.3.6
• Keycloak 26.6.4 · RabbitMQ 4.3.6
• Keycloak 26.7.5 · RabbitMQ 4.3.6
• Keycloak 26.8.1 · RabbitMQ 3.13.7
• Keycloak 26.8.1 · RabbitMQ 4.3.6

Формат сообщений

Одно JSON-сообщение на событие. Ключи маршрутизации (из имён realm и клиента удаляются точки; <RESULT> — это SUCCESS или ERROR):

KK.EVENT.CLIENT.<REALM>.<RESULT>.<CLIENT>.<EVENT_TYPE>        события пользователей
KK.EVENT.ADMIN.<REALM>.<RESULT>.<RESOURCE_TYPE>.<OPERATION>   события администраторов

Вход в realm demo через клиент demo-app: ключ маршрутизации KK.EVENT.CLIENT.demo.SUCCESS.demo-app.LOGIN, свойства app_id=Keycloak, content_type=application/json и content_encoding=UTF-8, заголовок __TypeId__ и такое тело (details сокращены):

{
  "@class" : "com.github.aznamier.keycloak.event.provider.EventClientNotificationMqMsg",
  "time" : 1792178809437,
  "type" : "LOGIN",
  "realmId" : "b43f6f2c-1a03-40d4-a3c2-6cd8df8e49b6",
  "clientId" : "demo-app",
  "userId" : "05fce3fd-ee8b-4d27-bbbd-de6f3a29820b",
  "sessionId" : "gIOG9-ZDDp96Liom5YidaEd1",
  "ipAddress" : "172.24.0.1",
  "details" : {
    "auth_method" : "openid-connect",
    "grant_type" : "password",
    "username" : "alice"
  }
}

События администраторов, все поля и точные правила — в описании формата сообщений, а потребители на Spring Boot, Node.js и Python — в примерах потребителей.

Переход с aznamier 3.0.5

Потребителям ничего менять не нужно: на той же версии Keycloak слушатель публикует те же ключи маршрутизации, свойства AMQP, заголовки и поля JSON, что и aznamier/keycloak-event-listener-rabbitmq 3.0.5. Идентификатор провайдера по-прежнему keycloak-to-rabbitmq, поэтому настройки и экспорт realm остаются в силе, а каждый параметр сохраняет своё имя и переменную KK_TO_RMQ_*.

Что меняется на стороне Keycloak:

• Нужны Keycloak не ниже 26.0 и Java не ниже 17; версия 3.0.5 собиралась под Keycloak 21.1.2 и Java 8. Keycloak на WildFly не поддерживается.
• С use_tls=true проверяются сертификат брокера и имя хоста, а при сбое настройки TLS соединения нет — без отката на AMQP без шифрования.
• Пустой vhost (по умолчанию) с версии 4.1.0 означает виртуальный хост RabbitMQ по умолчанию, /. Если с 3.0.5 события доходили при пустом vhost, они шли в виртуальный хост с именем "": перенесите обменник и его очереди в другой виртуальный хост и укажите его имя в vhost.
• В jar-файле только amqp-client 5.37.0; SLF4J и Netty берутся из Keycloak.

Порядок действий:

1. Замените jar-файл в providers/ (или в своём образе) и выполните kc.sh build, если запускаете Keycloak с --optimized.
2. Если используете TLS, убедитесь, что сертификату брокера доверяют и он выпущен на имя хоста из url.
3. Если параметры заданы переменными KC_SPI_…, после обновления проверьте строки лога слушателя configuration:.
4. Перезапустите Keycloak и следите за строками keycloak-to-rabbitmq ERROR.

Подробности и переход с форка focus-shift — в руководстве по переходу.

Частые вопросы

Код, релизы и поддержка

• Репозиторий на GitHubкод, документация и быстрый старт в Docker Compose
• Релизыjar-файл, его контрольная сумма и SBOM
• История измененийчто изменилось в каждом релизе и что сделать при обновлении
• ВопросыDiscussions, раздел Q&A
• Ошибки и идеиissues; форма попросит версии и строки лога слушателя
• Сообщить об уязвимостиприватно, не в публичном issue

Поддерживает Mizzle Studio. Исправления, в том числе по безопасности, выходят для последнего релиза; поддержка — по мере сил.

Исходный слушатель написал aznamier вместе с участниками исходного проекта, лицензия — Apache License 2.0. Keycloak и RabbitMQ — товарные знаки их владельцев; проект с ними не связан и ими не одобрен.