keycloak-scim/topics/events.adoc

= Auditing and Events

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. 

== Event types

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. 

== Event Listener

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: 

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

== Event Store

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: 

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

== Configure Events Settings for Realm

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.