Skip to content

How to send Keycloak events as a webhook

silver imac on brown wooden table

Keycloak is a powerful IAM provider that offers numerous out-of-the-box features. In this blog post, we will discuss how to extend user jessylenne existing work on sending Keycloak webhook events to a third-party provider using Docker and Makefile, making the process more accessible to developers who aren’t primarily Java programmers.

Prerequisites

  • Basic understanding of Git
  • Basic understanding of Keycloak, Docker, and Makefile
  • Access to a Keycloak instance

Resources

The original git repository provides a helpful README, detailing the process of building, deploying, and consuming the webhook event. However, as someone who isn’t primarily a Java programmer, setting up the dependencies and development environment manually can be a hassle. Ideally, I’d like to run Java and use Maven as my dependency manager with minimal setup.

My contribution is to build a Dockerfile and a Makefile so that fellow developers that are already using Docker can simply run one make command to generate the Java build output (JAR files) and go along their merry way.

To streamline this process, I’ve created a Dockerfile and a Makefile for fellow developers already utilizing Docker. This addition allows you to execute a single make command to generate the Java build output (JAR files), making the entire process more efficient and user-friendly.

Feel free to access my fork of the repository here.

Usage

There’s really only two steps: build and deploy.

Build

First, clone my fork of the repository that contains the Dockerfile and Makefile changes.

Note: There won’t be any need to customize the source files. You will simply inject the target webhook URL and username and password using XML later (see deployment stage).

To build the jar files, on the root directory of the project, run the command make package-image. This runs the build process for the keycloak webhook event project, and then subsequently, this copies the resulting JAR files to the mvn-output folder at the root directory of the project.

If you encounter any issues during building of the output image, such as in the case of permission issues, simply grant ownership of the mvn-output directory to the current $USER. This is explained in the README.

Deployment

To use the newly generated Keycloak plugin (packaged as a .jar file), you simply need to upload the file to your keycloak’s instance and configure your Keycloak instance configuration settings (specific to this plugin).

User Jessylenne describes the deployment process simply:

Copy the event-listener-http-jar-with-dependencies.jar to {KEYCLOAK_HOME}/standalone/deployments

Edit standalone.xml to configure the Webhook settings. Find the following section in the configuration.

User jessylenne, on deployments

The following enables you to customize the target of the webhook.

<spi name="eventsListener">
    <provider name="mqtt" enabled="true">
        <properties>
            <property name="serverUri" value="http://127.0.0.1:8080/webhook"/>
            <property name="username" value="auth_user"/>
            <property name="password" value="auth_password"/>
            <property name="topic" value="my_topic"/>
        </properties>
    </provider>
</spi>

That’s all to it. Your keycloak instance should recognize the change. If not, simply restart your keycloak instance to detect your plugin, and you should be receiving webhook events at your target service!

Explore, Learn, and Thrive: Tech and Gaming with Darren

Hello, reader! I’m Darren, and I’m passionate about technology, learning, and gaming. My articles cater to mid to senior-level software engineers seeking to expand their knowledge and skills.

Through sharing our experiences and lessons learned (including our mistakes), we can inspire, support, and empower the next generation of engineering problem solvers. Documenting these insights also helps me reinforce their importance and ensure they remain in my memory.

In my blog, you’ll find a collection of mental models designed to help you tackle challenges in both your engineering career and personal life. Additionally, I share personal reflections and short stories, exploring parallels between competitive gaming and workplace performance.

Join me on this journey to learn and grow together!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.