85 lines
3.3 KiB
Text
85 lines
3.3 KiB
Text
|
= 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.
|