Keycloak: Event Listener SPI & Publish to Kafka

In this post, we will build a basic SPI (Service Provider Interfaces), event listener & publish the events to Kafka. Keycloak SPI allows us to add or customize built-in functionality. Understanding of Kafka is required only for the part where we need to publish the events, if you just want to understand about build SPI, you can skip the Kafka part.

Setup

• Download Keycloak: https://www.keycloak.org/downloads
• Download Kafka: https://kafka.apache.org/downloads
• Java/Maven

Code Repo & Build Steps

git clone https://github.com/akoserwal/keycloak-integrations.git
cd keycloak-spi-kafka/
# build
mvn clean install

WARNING: Deploying an SPI jar with some issue/exception can cause failure with your Keycloak Server run. Also if you register the SPI under events using keycloak UI. If you remove the jar or some issue with your jar code. it will cause issue with your Keycloak instance. Get it working on any experimental server.

Deploying SPI jar into Keycloak

# Copy the Jar to Keycloak deployments
cp keycloak-spi-kafka.jar /keycloak-x.x.x/standalone/deployments

SPI Apps

Building an SPI for Keycloak we need to basically implement two interfaces:

1. Implement: `EventListenerProvider`
2. Implement: `EventListenerProviderFactory`

Create the file META-INF/servies/org.keycloak.events.EventListenerProviderFactory and add the class of your SPI to it i.e io.github.akoserwal.KeycloakCustomEventListenerProviderFactory

Let’s start building the application

I have created KeycloakCustomEventListener which implements EventListenerProvider provider two methods which we need to override: onEvent: Provides arguments

• Event
• AdminEvent

KeycloakCustomEventListenerProviderFactory which implements EventListenerProviderFactory where

• We can registry the KeycloakCustomEventListener
• Set the Id: kafka-event-listener which will be visible in Keycloak Event configuration.

Create a file:

keycloak-spi-kafka/src/main/resources/META-INF/services/org.keycloak.events.EventListenerProviderFactory

io.github.akoserwal.KeycloakCustomEventListenerProviderFactory

That’s all you need, let’s build this application & deploy in the keycloak server.

mvn clean install
# Copy the Jar to Keycloak deployments
cp keycloak-spi-kafka.jar /keycloak-x.x.x/standalone/deployments/

Restart the Keycloak Server

./keycloak-10.0.1/bin/standalone.sh

Verify the jar is deployed

keycloak-spi-kafka.jar.deployed

Login to Keycloak: http://127.0.0.1:8080/auth

You can search for the “kafka-event-listener”. We defined in KeycloakCustomEventListenerProviderFactory

Now try to login again or perform any defined events. With any event trigger, you can see events are logged into the keycloak server logs.

Kafka

Once you download the Kafka server. You can set the Kafka path.

export KAFKA_HOME=<Kafka Installation Directory>/lib/kafka

Start Kafka Server: using zookeeper

zookeeper-server-start /usr/local/etc/kafka/zookeeper.properties & kafka-server-start /usr/local/etc/kafka/server.properties

Producer:

Create a simple producer class that is using the KafkaProducer client & send the event to the Kafka Server.

You can call publishEvent in the OnEvent method. As any event published by the Keycloak. I am publishing “Topic” as Keycloak event type & value as userId. It's up to your use-case.

Producer.publishEvent(event.getType().toString(), event.getUserId());

Event Logs: You can see the topics:

ACTION, CODE_TO_TOKEN, CREATE, LOGIN, REFRESH_TOKEN, UPDATE, UPDATE_PASSWORD, UPDATE_PROFILE.

Kafkacat: Consume the topic LOGIN

You can see the login events: userId

Conclusion

Building SPI can help to enhance the capability of keycloak servers & with events published in Kafka can use to design event-driven architecture. Hope you find this helpful.

Extend version with adding secure communication between keycloak spi & Kafka: https://dzone.com/articles/publish-keycloak-events-to-kafka-with-a-custom-spi

If you like this post, give a Cheer!!!

Follow the Collection: Keycloak for learning more…

Happy Secure Coding ❤