Home

Awesome

Keycloak events Falco exporter

To use this exporter, you also have to configure Falco by installing and configuring the Falco keycloak plugin.

Keycloak compatibility

Each release workflow runs and builds the plugin against multiple keycloak versions to ensure compatibility. This is the compatibility matrix:

plugin \ keycloakv21v22v23v24v25v26
0.1.0
0.1.1
0.2.0

Installation

Download the plugin (preferred) or build locally.

Copy the spi-falco-event-<version>.jar into $KEYCLOAK_HOME/providers folder. If you're already pre-building and optimizing keycloak, once placed the .jar in that folder you would run:

/opt/keycloak/bin/kc.sh build

and then you can start keycloak with

/opt/keycloak/bin/kc.sh start --optimized

Otherwise, you can simply run start and Keycloak will configure the new plugin at start time.

You can see a working example of a Dockerfile keycloak customization (./Dockerfile) that will first build the plugin (without needing Maven/Java installed), then from a keycloak base image it will launch the keycloak build script to add the Falco provider.

Once you have Keycloak running with the exporter installed and configured, you can enable the Falco event listener for your realm by going into the Realm settings, under the tab Events you will now be able to select falco, amongst other event listeners.

Configuration

Properties can be set via environment variables (preferred, for example FALCO_ENDPOINT) or as parameters when starting keycloak (for example --spi-events-listener-falco-falcoEndpoint).

You can see all the keycloak events here (note that this link points to the latest keycloak version. Be sure to check the documentation for your keycloak version) and in the keycloak source code.

Development

Prerequisites:

To build the plugin locally, run:

mvn clean install

The resulting .jar plugin will be inside target/spi-falco-event-<version>.jar.

The easiest way to test and develop this plugin consists in:

At this point you can access Keycloak on http://localhost:8080, and Falco sidekick ui on http://localhost:2802. You can check the hack folder for Falco/Keycloak configuration and default rules. Keycloak comes shipped with a test realm where Falco events are enabled by default, so for example, creating a new user under that realm would trigger an event that would be forwarded to Falco.

If you simply want to test this extension without needing to configure/start Falco, then you can run docker-compose --profile extra up -d that will also run an echo-server container on port 7080. Change the FALCO_ENDPOINT variable in the keycloak container inside docker-compose.yml to point to echo-server:7080 and you will see every forwarded event HTTP request logged inside the echo-server container. In that case, you can ignore all the Falco containers.

Contributing

PRs and issues are very welcome, feel free to open them or reach out to me directly.