Keycloak is a powerful, open-source IAM provider that offers numerous out-of-the-box features. At the time of creating this blog post (2021), one key capability that Keycloak lacks is the ability to send webhook events to an external service.

This blog post shows the step-by-step process to enable Keycloak to forward webhook events to a third-party provider.

Prerequisites

• To build the Keycloak plugin: Docker, and Makefile
• To test the newly built plugin: Access to a default-configured, running Keycloak instance

Instructions

1. Clone repository

Clone my repository locally with the command below.

git clone [email protected]:darrensapalo/keycloak-event-listener-http.git

2. Build

You need to build the plugin into a Java archive file, with the file extension .jar.

On the root directory of the project, on your terminal run the following command:

make package-image

This runs the build process for the keycloak webhook event project, and copies the resulting JAR files to the mvn-output folder at the root directory of the project.

Note: 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.

3. Deploy

Now that you have the event-listener-http-jar-with-dependencies.jar file, you need to upload this file to your running keycloak instance and configure your running Keycloak instance’s configuration settings specific to this plugin.

1. Copy the .jar file into {KEYCLOAK_HOME}/standalone/deployments.
2. Edit standalone.xml to configure the Webhook settings. Find the following section in the configuration.

The standalone.xml looks something like this, and you can configure it:

<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>

4. Verify changes

After uploading the .jar file and updating the standalone.xml file, your Keycloak instance should recognize the change. If not, simply restart your Keycloak instance, and you should be able to receive the webhook events at your target service!

References

• https://github.com/darrensapalo/keycloak-event-listener-http