JBoss.orgCommunity Documentation

Chapter 18. Events

18.1. Event types
18.2. Event Listener
18.3. Event Store
18.4. Configure Events Settings for Realm

Keycloak provides an Events SPI that makes it possible to register listeners for user related events, for example user logins. There are two interfaces that can be implemented, the first is a pure listener, the second is a events store which listens for events, but is also required to store events. An events store provides a way for the admin and account management consoles to view events.

Login events:

  • Login - A user has logged in
  • Register - A user has registered
  • Logout - A user has logged out
  • Code to Token - An application/client has exchanged a code for a token
  • Refresh Token - An application/client has refreshed a token

Account events:

  • Social Link - An account has been linked to a social provider
  • Remove Social Link - A social provider has been removed from an account
  • Update Email - The email address for an account has changed
  • Update Profile - The profile for an account has changed
  • Send Password Reset - A password reset email has been sent
  • Update Password - The password for an account has changed
  • Update TOTP - The TOTP settings for an account has changed
  • Remove TOTP - TOTP has been removed from an account
  • Send Verify Email - A email verification email has been sent
  • Verify Email - The email address for an account has been verified

For all events there is a corresponding error event.

Keycloak comes with an Email Event Listener and a JBoss Logging Event Listener. The Email Event Listener sends an email to the users account when an event occurs. The JBoss Logging Event Listener writes to a log file when an events occurs.

The Email Event Listener only supports the following events at the moment:

  • Login Error
  • Update Password
  • Update TOTP
  • Remove TOTP

You can exclude one or more events by editing standalone/configuration/keycloak-server.json and adding for example:

"eventListener": {
    "email": {
        "exclude-events": [ "UPDATE_TOTP", "REMOVE_TOTP" ]
    }
}

Event Store listen for events and is expected to persist the events to make it possible to query for them later. This is used by the admin console and account management to view events. Keycloak includes providers to persist events to JPA and Mongo.

You can specify events to include or exclude by editing standalone/configuration/keycloak-server.json, and adding for example:

"eventsStore": {
    "jpa": {
        "exclude-events": [ "LOGIN", "REFRESH_TOKEN", "CODE_TO_TOKEN" ]
    }
}

To enable persisting of events for a realm you first need to make sure you have a event store provider registered for Keycloak. By default the JPA event store provider is registered. Once you've done that open the admin console, select the realm you're configuring, select Events. Then click on Config. You can enable storing events for your realm by toggling Save Events to ON. You can also set an expiration on events. This will periodically delete events from the database that are older than the specified time.

To configure listeners for a realm on the same page as above add one or more event listeners to the Listeners select box. This will allow you to enable any registered event listeners with the realm.