Events Logging in Keycloak is the built-in system for recording security-relevant occurrences as structured, timestamped records — rather than relying solely on unstructured server log files that are hard to search and easy to lose track of. Instead of scrolling through raw application logs hoping to find “did this user log in yesterday?”, Events Logging gives you a queryable, filterable record purpose-built for exactly that kind of question.

Keycloak splits Events Logging into two distinct categories, each capturing a different kind of activity:

It’s worth noting upfront: Keycloak doesn’t persist events to a searchable store automatically out of the box in every configuration — capturing and retaining them for later review is a deliberate setting administrators typically need to enable, covered in detail in the chapters ahead.

flowchart TB
    Action["User or Admin Action"] --> EventSPI["Event Listener SPI"]
    EventSPI --> DefaultLogger["Default: Server Log Listener"]
    EventSPI --> EventStore["Event Store Listener (if enabled)"]
    EventSPI --> CustomListener["Custom Listener (e.g. Kafka, email, SIEM)"]
    EventStore --> Database["Persistent Event Database"]
    Database --> AdminConsole["Admin Console: Events Tab"]
    Database --> API["Admin REST API: Query Events"]
    

Let’s unpack each component in this pipeline.

The Event Listener SPI

Every relevant occurrence in Keycloak passes through a pluggable Service Provider Interface (SPI) for events. This design means Keycloak itself doesn’t hardcode what happens with an event — instead, one or more registered “listeners” each get a chance to do something with it, from simple logging to forwarding it somewhere entirely custom.

The Default Log Listener

Out of the box, Keycloak includes a listener that writes event information into the server’s own log output — useful for basic visibility, but not ideal for structured querying or long-term retention compared to a dedicated store.

The Event Store Listener

When enabled, this listener persists events into a queryable backing store, which is exactly what powers the searchable Events tab in the Admin Console — letting administrators filter by user, date range, event type, and more.

Custom Listeners

Because the SPI is pluggable, organizations can add custom listener implementations that forward events elsewhere entirely — into a centralized security information and event management (SIEM) system, a message queue like Kafka, or an alerting pipeline that notifies a security team of specific suspicious patterns in near real time.

Anatomy of a User Event

A typical User Event record includes: the event type (such as LOGIN, LOGIN_ERROR, LOGOUT, or UPDATE_PASSWORD), a timestamp, the realm it occurred in, the user’s internal ID, the client application involved, the IP address the request originated from, and, for errors, a specific error reason code.

Anatomy of an Admin Event

An Admin Event captures a bit more structurally: the operation type (create, update, or delete), the resource path affected (such as which specific user or client was modified), the administrator who performed it, and — if configured — a full representation of the resource’s data before and after the change.

Selective Event Type Capture

Administrators can choose exactly which event types get saved — for example, capturing every login attempt while ignoring less security-relevant events, or vice versa — rather than being forced into an all-or-nothing capture policy.

Representation Capture for Admin Events

Admin Events can optionally include the full JSON representation of the affected resource, both before and after the change. This is extremely valuable for detailed auditing, but it also means sensitive data present in that resource could end up stored in the event record — a consideration covered further in the Security chapter.

Protect the Event Store Like Any Sensitive Database

Because events can reveal login patterns, IP addresses, and administrative changes, access to the stored event data should be restricted to those who genuinely need it — treating it with the same care as any other security-sensitive data store.

Be Deliberate About Representation Capture

Enabling full before/after representation capture for Admin Events is powerful for auditing, but if the affected resources contain sensitive attributes, those details end up duplicated inside the event log too — worth reviewing carefully before enabling broadly across sensitive realms.

Use Events to Detect Brute-Force and Credential-Stuffing Patterns

Reviewing LOGIN_ERROR event patterns — many failures against one account, or one IP address attempting logins across many different accounts — can surface exactly the kind of automated attack pattern that’s easy to miss in raw application logs but stands out clearly in structured event data.

Forward Critical Events to a Centralized Monitoring System

For organizations with a dedicated security monitoring function, forwarding Keycloak events to a centralized SIEM via a custom listener allows correlation with other systems’ activity — often revealing attack patterns invisible when Keycloak’s events are reviewed in isolation.

Good Pattern: Enable Both Categories Deliberately

Turn on both User Events and Admin Events persistence with intention, considering what each realm actually needs to audit, rather than leaving one category off simply because it wasn’t the default.

Good Pattern: Tune Retention to Actual Need

Set retention periods based on genuine compliance or investigative requirements — long enough to be useful during a real incident review, but not indefinitely accumulating data with no clear purpose.

Good Pattern: Pair Logging with Alerting

Combine stored events with active alerting on specific concerning patterns — repeated failed logins, unusual administrative changes — rather than treating Events Logging as a purely passive archive.

Common Mistakes to Avoid

• Assuming events are stored by default: Persistence to a searchable store is a setting that typically needs to be explicitly enabled.
• Ignoring Admin Events entirely: Focusing only on User Events misses the equally important record of what administrators themselves changed.
• Never testing the review workflow: Enabling event capture without ever practicing how an actual investigation would use it leaves teams unprepared when a real incident occurs.
• Overlooking sensitive data in representation capture: Enabling detailed Admin Event representations without considering what data they might duplicate and retain.