Falco Keycloak plugin

This repository contains a Falco plugin for sourcing and extracting Keycloak events. If you want to use this plugin you also have to configure keycloak to export events by installing the keycloak falco exporter plugin.

Architecture

The integration with Keycloak requires:

• Keycloak with the falco exporter configured and installed.
• This Falco plugin installed and configured. The configuration needs at least to expose an HTTP endpoint in order to let Keycloak forward its user/admin events. What type of events are forwarded are configured on Keycloak side.
• Optional: Falco JSON plugin for accessing arbitrary JSON fields in user/admin events.

sequenceDiagram
    participant Keycloak
    participant Falco
    participant Falco Sidekick

    Note right of Keycloak: Install and configure <br/>Falco exporter plugin
    Keycloak->>Falco: HTTP POST <falco url><br/>User or Admin event

    Note right of Falco: Install keycloak <br/>source event and <br/>field extractor plugin.<br/>Configure to listen on <br/>some port, e.g. 7080.
    Falco-->>Falco: Evaluate custom <br/>keycloak rules based on keycloak event.<br/>For example, admin [email protected] has <br/>manually deleted an user, or<br>user *@company.com has done a LOGIN<br/>with an IP that is not recognized <br/>by company policy.
    Falco->> Falco Sidekick: Trigger rule forwarded to Falco <br/>Sidekick, handle however you like...

Loading

Installation

With falcoctl:

falcoctl index add keycloak https://raw.githubusercontent.com/mattiaforc/falco-keycloak-plugin/main/index.yaml

falcoctl artifact install keycloak

# At this moment there are no default rules, only a few helpful macros to get started. 
# I'm open to suggestions about default rules that we could include with this plugin, so feel free to submit a PR or open a issue! 
falcoctl artifact install keycloak-rules

Configuration

The plugin embeds a webserver that listens on a configurable port and accepts POST requests. The webserver of the plugin can be configuted as part of the plugin's init configuration and open parameters.

An example of a simple Falco configuration for using this plugin and the JSON plugin as well (as you can also see inside the docker-compose.yml example in the Keycloak exporter repository, mounting this falco.yaml configuration file):

plugins:
  - name: keycloak
    library_path: /usr/share/falco/plugins/libkeycloak.so
    init_config: ''
    open_params: 'http://0.0.0.0:7080/keycloak'
  - name: json
    library_path: libjson.so
    init_config: ""

load_plugins:
  - keycloak
  - json # This is not stricty required for the keycloak plugin to work

Possible configurations that can be passed inside the init_config stanza are:

• sslCertificate: If you plan to expose the listener using HTTPS, this is the certificate (defaults to /etc/falco/falco.pem).
• sslKey: If you plan to expose the listener using HTTPS, this is the key (defaults to /etc/falco/key.pem).

The init config simply takes the URL that the listener will listen on: you can choose an arbitrary port and path, simply remember to configure the Keycloak exporter accordingly.

Event source and supported fields

The keycloak plugin implements event sourcing and field extraction for Keycloak user events and admin events. The event source is keycloak.

Supported fields

NAME	TYPE	ARG	DESCRIPTION
keycloak.eventID	string	None	The ID of the keycloak event.
keycloak.error	string	None	The event error, if any.
keycloak.realmID	string	None	The ID of the realm.
keycloak.user.eventType	string	None	The event type.
keycloak.user.clientID	string	None	The ID of the client.
keycloak.user.userID	string	None	The ID of the user.
keycloak.user.sessionID	string	None	The user session ID.
keycloak.user.ipAddress	string	None	The user IP address.
keycloak.admin.authDetails.realmID	string	None	The authentication realmID for this AdminEvent.
keycloak.admin.authDetails.clientID	string	None	The authentication clientID for this AdminEvent.
keycloak.admin.authDetails.userID	string	None	The authenticated userID that triggered this AdminEvent.
keycloak.admin.authDetails.ipAddress	string	None	The IP address of the user that triggered this AdminEvent.
keycloak.admin.resourceType	string	None	The resource the AdminEvent was triggered for.
keycloak.admin.operationType	string	None	The type of the AdminEvent operation.
keycloak.admin.resourcePath	string	None	The resource path for the AdminEvent.

Other than these fields, you can access the arbitrary JSON metadata that keycloak sends in the event, the Details for user events and Representation for admin events - by using Falco JSON plugin. This is because the fields are defined as an arbitrary Map<String, String> in Keycloak, so this plugin just allows you to access its raw values.

For example, if you want to create a rule every time an admin action is made on a user, you can access the subject user's email for example in the Representation field:

rule: Keycloak admin event
desc: Received keycloak admin event
condition: kc_adm_evt
output: Action made on user=%json.value[/Representation/username] by user %keycloak.admin.authDetails.userID with IP=%keycloak.admin.authDetails.ipAddress
priority: DEBUG
source: keycloak
tags: [keycloak, keycloak_admin]

The same thing goes for user event Details, accessing it with %json.value[/Details/<field>].

Another example of a rule that is triggered for every user event (useful for debugging):

rule: Keycloak user event
desc: Received keycloak user event
condition: kc_usr_evt
output: event type=%keycloak.user.eventType for user=%keycloak.user.userID on realm=%keycloak.realmID and client=%keycloak.user.clientID with IP=%keycloak.user.ipAddress
priority: DEBUG
source: keycloak
tags: [keycloak, keycloak_user]

Development

The best way to develop this plugin is to clone the Keycloak plugin as well and to use the docker-compose.yml and the keycloak sample configuration provided there. Otherwise the plugin development is pretty standard - once you have Go installed you can simply start to alter the plugin.

Requirement:

• Go >= 1.22

For building the plugin:

make

Contributing

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