Building an Event Listener SPI (Plugin) for KeyCloak
Tags: java, keycloak, computerscience
Published: 2019-12-20 15:30:09

In this blog, I will talk about how to build an event listener plugin (called an SPI) for KeyCloak

So, what is **Keycloak**?

**Keycloak** is an Open Source Identity and Access Management Framework built by **RedHat**. It provides a lot of advanced features like SSO, Social Auth, support for multiple auth protocols, etc. Read more here: [https://www.keycloak.org/](https://www.keycloak.org/)
 
But one of the most important features is the ability to extend any functionality of KeyCloak by simply building a plugin.  

During my internship this summer, we needed to log all the events of users (and admins) happening within KeyCloak and send them to external systems for analysis. This is needed in many situations. _(one example is if you are using an external [SIEM](https://en.wikipedia.org/wiki/Security_information_and_event_management) to log and analyze incidents)_.

By default, KeyCloak logs don't contain user/admin events. And even if we enable that, it would be difficult to build an external system which monitors and parses the logs to extract required events. **Instead, we can build a plugin for KeyCloak to hook into the system and do _"something"_ whenever an event occurs _(In our case, fire external API calls)_**

So, let's build one :)  

> **_Note_**: The entire code for the event listener is available here. {% github https://github.com/adwait-thattey/keycloak-event-listener-spi no-readme %}

_I would be using [Maven](https://maven.apache.org/) here for managing dependencies and building project._

So let's get the [pom.xml](https://github.com/adwait-thattey/keycloak-event-listener-spi/blob/master/sample_event_listener/pom.xml) sorted out first.

_(If you are not familiar with Maven, we use a **pom.xml** file in Maven to list all the project details including all the dependencies)_
 
{% gist https://gist.github.com/adwait-thattey/72fd74473a3db8c1b61a856e0574326c file=pom.xml %}

_(if the above gist is not visible, you can find the file [here](https://github.com/adwait-thattey/keycloak-event-listener-spi/blob/master/sample_event_listener/pom.xml)_

In `pom.xml`, we define the parent details, project name `Sample Event Listener`), version, artifact-id (here `sample_event_listener`), dependencies and build configuration. 

---

The next step is to implement the SPI. For this, we need to implement 2 classes. `Provider` and `ProviderFactory`

so let's create our package in `src/main/java`. 
Here the package name is `com.coderdude.sampleeventlistenerprovider.provider`   
`coderdude` :  because my dev alias is coderdude :D  
`sampleeventlistenerprovider`: Could be shorter but let's leave it at that  
`provider`: The last provider is there because there can potentially be other modules that you use in your provider.

Now this package is going to contain the 2 above discussed classes.
The `Provider` class contains the actual logic of the plugin. The `ProviderFactory` is a wrapper that initializes the provider. **The difference is important**. 
- The `Factory` is initialized only when KeyCloak is started. A new instance of `Provider` is created by `Factory` every time required. _(In our case every time an event occurs)_
- Only 1 instance of `Factory` will exist. Multiple providers can exist at the same time (say 2 events occur at the same time). 
- Providers are destroyed as soon as they complete their tasks. The Factory exists as long as KeyCloak is running. 
- Any error in Factory will crash KeyCloak. An error in Provider will simply go to the logs and rest of Keycloak will function normally  

So let's start by creating a Provider. 
The name of the class will be `SampleEventListenerProvider` which implements the `EventListenerProvider` interface _(This interface is provided by KeyCloak)_

```java
package com.coderdude.sampleeventlistenerprovider.provider;

import org.keycloak.events.Event;
import org.keycloak.events.EventListenerProvider;
import org.keycloak.events.admin.AdminEvent;

import java.util.Map;


public class SampleEventListenerProvider implements EventListenerProvider {

    public SampleEventListenerProvider() {
    }

    
}
```

_Keep these imports for now. We will need them._
So here, we are just going to print all the events to the console. All events are provided by 2 classes: `org.keycloak.events.Event` and `org.keycloak.events.admin.AdminEvent` 
The normal events occur whenever a normal user does something. Admin events occur when administrators do something.   
We need to write appropriate methods to convert these class objects to readable strings. 
Here is the method to build string for an `Event`

We are capturing all the parameters, errors and details. (hence the map, because the details is an array)

```java
private String toString(Event event) {

        StringBuilder sb = new StringBuilder();


        sb.append("type=");

        sb.append(event.getType());

        sb.append(", realmId=");

        sb.append(event.getRealmId());

        sb.append(", clientId=");

        sb.append(event.getClientId());

        sb.append(", userId=");

        sb.append(event.getUserId());

        sb.append(", ipAddress=");

        sb.append(event.getIpAddress());


        if (event.getError() != null) {

            sb.append(", error=");

            sb.append(event.getError());

        }


        if (event.getDetails() != null) {

            for (Map.Entry<String, String> e : event.getDetails().entrySet()) {

                sb.append(", ");

                sb.append(e.getKey());

                if (e.getValue() == null || e.getValue().indexOf(' ') == -1) {

                    sb.append("=");

                    sb.append(e.getValue());

                } else {

                    sb.append("='");

                    sb.append(e.getValue());

                    sb.append("'");

                }

            }

        }


        return sb.toString();

    }
``` 

Of course, this is a very naive implementation. What we actually did was define methods to wrap these events in other objects and make API calls to external systems. But this will work for now. 
We can build a similar method for `AdminEvent`. You will find it in the main full code.

Once this is done, we need to override 2 methods provided by the 
`EventListenerProvider` interface. These are `onEvent` and `close`.  
Here it is

```java
    @Override
    public void onEvent(Event event) {

        System.out.println("Event Occurred:" + toString(event));
    }

    @Override
    public void onEvent(AdminEvent adminEvent, boolean b) {

        System.out.println("Admin Event Occurred:" + toString(adminEvent));
    }

    @Override
    public void close() {

    }
```

The `onEvent` is the actual method called whenever an event occurs. We need to overload onEvent twice to capture both `Event` and `AdminEvent`. 
Finally, the `close` method is called just before the class is destroyed. Sort of like a destructor. We need to override it even if we don't need to use it.

You can find the full class code (along with string implementation for AdminEvent) [here](https://github.com/adwait-thattey/keycloak-event-listener-spi/blob/master/sample_event_listener/src/main/java/com/coderdude/sampleeventlistenerprovider/provider/SampleEventListenerProvider.java)

--- 
Next step is to implement the `ProviderFactory`
The name of the class is  `SampleEventListenerProviderFactory` which implements `EventListenerProviderFactory`  
Here is the code: 

{% gist https://gist.github.com/adwait-thattey/72fd74473a3db8c1b61a856e0574326c file=SampleEventListenerProviderFactory.java %}

_(if the above gist is not visible, you can find the file [here](https://github.com/adwait-thattey/keycloak-event-listener-spi/blob/master/sample_event_listener/src/main/java/com/coderdude/sampleeventlistenerprovider/provider/SampleEventListenerProviderFactory.java)_

We override multiple methods here. The main ones are the `create` and `getId`. The create method should initialize and return an instance of provider (in our case `SampleEventListenerProvider`). The `getId` should return a string with the name of the plugin

---
The next and the final task is to provide a link to our class. For this we need to create resources. 
create a folder named `resources` in `src/main` (alongside `java` folder) 
Now create the following file in `resources/META-INF/services/` named `org.keycloak.events.EventListenerProviderFactory` . Note that full path to location of file is `src/main/resources/META-INF/services/org.keycloak.events.EventListenerProviderFactory` 

This file just contains one line with the package and name of our factory class
```java
com.coderdude.sampleeventlistenerprovider.provider.SampleEventListenerProviderFactory
```

That's it. We have written the plugin. Now let's build and package it.
_I have used maven to build and package_

Once packaging is complete, you should see the `jar` and `sources` in the target directory 
Here is my final directory structure
![Directory Structure](https://thepracticaldev.s3.amazonaws.com/i/m2ku1yozov524hdv4qt4.png)


We will only need the `sample-event-listener.jar`

-- 
Now it's time to deploy the plugin to KeyCloak.

Let's get setup with a KeyCloak first. You will find the getting started guide here [https://www.keycloak.org/docs/latest/getting_started/index.html](https://www.keycloak.org/docs/latest/getting_started/index.html). 

Quickly download and create an admin user and login to KeyCloak. 
Now let's create a new realm named `newrealm` and add a user named `newuser001` in the new realm.


![Create new User Snap](https://adwait-thattey.github.io/assets/blogs/keycloak_plugin/Screenshot_20191219_191638.png)

Let's also create a password for this new user

![Set New User password](https://adwait-thattey.github.io/assets/blogs/keycloak_plugin/Screenshot_20191219_191654.png)

**It's time to deploy our awesome plugin**

The deployment process is pretty straightforward. We need to copy the `sample-event-listener.jar` to `$KEYCLOAK_DIR/standalone/deployments/` where $KEYCLOAK_DIR is the main KeyCloak directory (after unzipping)

KeyCloak supports hot-reloading. So as soon we copy the jar file, keycloak should reload and deploy the plugin. But just to be sure, let's restart the Keycloak server.

You should see a line like this 
```
Deployed "sample-event-listener.jar" (runtime-name : "sample-event-listener.jar")
```

![Set New User password](https://adwait-thattey.github.io/assets/blogs/keycloak_plugin/Screenshot_20191220_170051.png) 

Now we need to allow this plugin to listen to events.
Go to `newrealm->manage->events->config` or this url `/auth/admin/master/console/#/realms/newrealm/events-settings` **Make sure to replace newrealm with the name of the realm you created**

In the config, event-listeners, add `sample_event_listener` to the list and hit save.

![Set New User password](https://adwait-thattey.github.io/assets/blogs/keycloak_plugin/Screenshot_20191220_170208.png)

Now our plugin should be able to capture all events.

---
Lets test this

Login to the newrealm using the user that was created above.

You should see an event occuring in the console
```
17:03:01,797 INFO  [stdout] (default task-5) Event Occurred:type=LOGIN, realmId=newrealm, clientId=account, userId=efc09972-6166-4ed6-9ca0-15c030e47f54, ipAddress=127.0.0.1, auth_method=openid-connect, auth_type=code, redirect_uri=http://localhost:8180/auth/realms/newrealm/account/login-redirect, consent=no_consent_required, code_id=78db58ed-3c99-4d42-aced-b69873c59f12, username=newuser001
```

Logout should also be captured
```
17:03:51,211 INFO  [stdout] (default task-5) Event Occurred:type=LOGOUT, realmId=newrealm, clientId=null, userId=efc09972-6166-4ed6-9ca0-15c030e47f54, ipAddress=127.0.0.1, redirect_uri=http://localhost:8180/auth/realms/newrealm/account/
```

Trying to login with incorrect password is also captured (because we were also capturing errors)
```
17:04:04,505 WARN  [org.keycloak.events] (default task-5) type=LOGIN_ERROR, realmId=master, clientId=security-admin-console, userId=null, ipAddress=127.0.0.1, error=user_not_found, auth_method=openid-connect, auth_type=code, redirect_uri=http://localhost:8180/auth/admin/master/console/#/realms/newrealm/users, code_id=59a85ee0-a8f6-4fad-8667-f72de2da18fd, username=newuser001
```

Looks like this in my console
![Set New User password](https://adwait-thattey.github.io/assets/blogs/keycloak_plugin/Screenshot_20191220_170423.png)


Voilà! Our plugin is able to capture events

---
Wrapping Up:

Once again, the entire code is available here:
{% github https://github.com/adwait-thattey/keycloak-event-listener-spi no-readme %}

This is a very basic example. We can do lots more. There is a lot more useful information that keycloak events provide that can be captured. Like current realm, ip address of the person trying to login, access token IDs if it is an api login, etc.

---

If you liked this blog, hit like :)

Bye!

Adwait Thattey,  
[https://adwait-thattey.github.io/](https://adwait-thattey.github.io/)