Keycloak HTTP Webhook Provider

A Keycloak provider that forwards keycloak events to one or multiple URLs. Events can also be routed to different URLs per realm.

How to build

mvn clean install

How to install

Copy the provider to the correct directory:

cp target/keycloak_http_webhook_provider.jar /opt/keycloak/standalone/deployments/

Next, add the provider as an event listener on your Keycloak instance. For instance:

/opt/jboss/keycloak/bin/kcadm.sh update events/config -s eventsListeners+=http_webhook \
    --no-config --server http://localhost:8080/auth --user admin --password admin --realm master

How to configure

The provider expects a single environment variable called KEYCLOAK_WEBHOOK_CONFIG_FILE, which should contain a path to the configuration file. Optionally, KEYCLOAK_WEBHOOK_CONFIG_WATCH can be set to true to make the provider watch the configuration file for changes (e.g. to automatically reload the config when a ConfigMap or Secret in Kubernetes changed).

The configuration files looks like this:

{
    "targets": {
        "example-org": {
            "url": "https://example.org",
            "authorizationHeader": null,
            "requestTimeoutMillis": 5000
        },
        "example-com": {
            "url": "https://example.com",
            "authorizationHeader": null,
            "requestTimeoutMillis": 5000
        }
    },
    "defaultTargets": ["example-com"],
    "routes": {
        "example": ["example-org"]
    }
}

.routes, .defaultTargets and .targets.*.requestTimeoutMillis are optional.

.targets is a mapping from target name to target configuration. Target configurations require at the url field to be present and it must be a valid HTTP(S) URL.

.defaultTargets is a set of target names, to which events are forwarded, if no route matches the realm of an event.

.routes is a mapping from realm names to sets of target names. All events that relate to the given realm name will be forward for every target named.

How to develop

To very quickly start a development instance of Keycloak with Docker, you can ran

keycloak/run-keycloak-container.sh