Keycloak out of the box provides a lot of value as an IAM provider. On this blog post, I will talk about how I extended user jessylenne existing work on sending Keycloak webhook events to a third party provider.

Resources

The original git repository has a convenient README available, explaining how to build, deploy, and consume the webhook event. However, because I am not primarily a Java programmer, I prefer not to have to manually install the dependencies and development environment needed to run the project. Specifically, I need to be able to run Java and use Maven as my dependency manager.

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.

You can access my fork 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!