Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/yakovlev-alexey/keycloak-sentry-logger

A Keycloak Event Listener that logs errors or all events to Sentry
https://github.com/yakovlev-alexey/keycloak-sentry-logger

keycloak keycloak-provider sentry sentry-integration

Last synced: about 5 hours ago
JSON representation

A Keycloak Event Listener that logs errors or all events to Sentry

Awesome Lists containing this project

README 

        
# Keycloak Sentry Logger



A Keycloak Event Listener that logs errors or all events to Sentry.



## Installation



Use the latest prebuilt `jar` file from the releases tab on GitHub or build the package yourself using `mvn clean package`. In your Dockerfile add `COPY ./dev.yakovlev_alexey-keycloak-sentry-logger-*.jar /opt/keycloak/providers/`.



## Configuration



First you need to set required environment variables for this plugin. At the moment of writing Keycloak would not allow custom event listeners to be configured. So the only source of configuration is the environment.



The package can be configured with the following environment variables:



```

SENTRY_ERRORS_ONLY=

SENTRY_IGNORED_EVENT_TYPES=<';' separated list of event types (commonly upper snakecase) to be ignored>

SENTRY_IGNORED_ERRORS=<';' separated list of error message (commonly lower snakecase) to be ignored>

```

Also, Sentry can be configured with its [standard environment variables](https://docs.sentry.io/platforms/java/configuration/), like `SENTRY_DSN`, `SENTRY_DEBUG`, `SENTRY_RELEASE` etc.



An example configuration might look like this:



```bash

SENTRY_DSN=https://[email protected]/6413214 # make sure to use your own DSN

SENTRY_ERRORS_ONLY=true

SENTRY_RELEASE=31187a77ec1

SENTRY_IGNORED_ERRORS=invalid_user_credentials;expired_code

```



After you launch your Keycloak instance with included `jar` file and updated environment variables make sure to enable `sentry-event-listener` in your realm. To do this enter `Manage > Events > Config > Events Config > Event Listeners` and select `sentry-event-listener` from the dropdown menu.



![](./docs/images/events-configuration.png)



> Note, that it is not a requirement to enable `Save Events` option lower on the configuration page. It only affects past events visibility in Keycloak `Login Events` and `Admin Events` tabs on the same page.



## Usage



When events are sent to Sentry they usually include a Stack Trace with the origin of the event. The event in Sentry will also have Additional Data populated with information that came with the event. This may include `realmId`, `clientId`, `username` and other data specific to particular events.



Events are usually tied to a specific user. In Sentry an id will be shown - this is the id of this user in Keycloak.



If the plugin is used to send all events (not just errors) then event type will be used as the name for the event. This is due to the fact that only error events have a message. However when error only mode is on, the error message will be used as the name for Sentry event. In any configuration event types are stored in tag name `type`.



Admin and login events can be distinguished by the `source` tag. It will be `admin` for admin events and `common` for login events.



## Roadmap



This plugin is being used in a relatively large production. I will continue to improve it if I see places of improvement. At the moment I am looking into making this plugin log certain exceptions from Keycloak.



## Contributing



Anyone is welcome to open issues with enhancement proposals and questions. If you have a specific implementation in mind the project is open to Pull Requests.



## License



[MIT](/LICENSE)