Keycloak Event Listener SHOGun

A Keycloak Service Provider Interface (SPI) implementation listening to a selection of Keycloak events and notifying a SHOGun instance about it via the appropriate webhook.

A (largely) adaptation of https://github.com/jessylenne/keycloak-event-listener-http SPI.

Compatibility

Currently, the extension has been tested against Keycloak version 25, but it should also work with older (and probably newer) versions.

Development

Requirements

To build the extension the following tools are required:

• Java 17
• mvn

Build

To build the extension just execute:

mvn clean package

Usage

Installation

Copy the target/event-listener-shogun-jar-with-dependencies.jar (available after it has been built) file to your {KEYCLOAK_HOME}/providers directory.

If you are working in a Docker environment you might want to mount the /opt/keycloak/providers folder as a volume and copy the target to the host directory instead, e.g.:

(…)
volumes:
  - ./my-keycloak/providers/event-listener-shogun-jar-with-dependencies.jar:/opt/keycloak/providers/event-listener-shogun-jar-with-dependencies.jar
(…)

Configuration

The plugin can be configured using a set of environment variables:

Environment Variable	Description	Default
SHOGUN_WEBHOOK_EVENT_TYPES	A comma-separated list of user event types to listen to. See here for a list of available types.	-
SHOGUN_WEBHOOK_OPERATION_TYPES	A comma-separated list of admin operation types to listen to. See here for a list of available types.	CREATE,DELETE
SHOGUN_WEBHOOK_RESOURCE_TYPES	A comma-separated list of admin resource types to listen to. See here for a list of available types.	USER,GROUP,GROUP_MEMBERSHIP
SHOGUN_WEBHOOK_URIS	A comma-separated list of SHOGun webhook URIs to notify. By default, the plugin expects a single SHOGun instance running at http://shogun-boot:8080/webhooks/keycloak. This path can be adjusted if the instance is available at a different host (e.g. http://my-shogun-boot:8080/webhooks/keycloak) and/or if multiple instances of SHOGun should be notified, e.g. in a clustered environment.	http://shogun-boot:8080/webhooks/keycloak
SHOGUN_WEBHOOK_CLIENT_ID	The client ID to use for the SHOGun webhook.	shogun-boot
SHOGUN_WEBHOOK_USE_AUTH	Whether to use authentication for the webhook or not.	true

Registration in Keycloak

1. Go to the "Realm settings" in your Keycloak realm.
2. Select the "Events" tab and add shogun-webhook to the "Event listeners".
3. Save the settings.
4. Add/Update/Delete a user/group, your webhook should be called.