Events & Audit

Two types of events

Keycloak records two distinct categories of events:

• Login events — actions performed by end-users: successful logins, failed login attempts, token refreshes, logouts, password resets, and more. These are stored per-realm and are the primary audit trail for user activity.
• Admin events — actions performed by administrators in the admin console or via the Admin REST API: realm creation, client registration, user updates, role assignments, and so on.

Both types are disabled by default. You must enable them explicitly.

Enabling events in the admin console

Enable login events

1. Open the admin console and select your realm.
2. Click Realm settings in the left sidebar.
3. Click the Events tab.
4. Under User events settings, toggle Save events to On.
5. Set Expiration (e.g., 7 days) to prevent unbounded growth in the database.
6. Optionally, expand Saved types to restrict which event types are stored.
7. Click Save.

Enable admin events

1. On the same Events tab, scroll to Admin events settings.
2. Toggle Save events to On.
3. Optionally enable Include representation to store the full JSON payload of each change (useful for detailed audits, but increases storage).
4. Click Save.

Viewing events

After events are enabled, they accumulate in real time.

Login events: In the left sidebar, click Events. The User events sub-tab shows a paginated list of login events with timestamp, user, IP address, and event type. Use the search filters to narrow by event type (e.g., LOGIN_ERROR) or date range.

Admin events: Click the Admin events sub-tab. Each entry shows the operation type (CREATE, UPDATE, DELETE), the resource type (e.g., USER, CLIENT), and optionally the before/after representation.

Querying events via the Admin REST API

You can also fetch events programmatically:

curl -s "https://localhost:8080/admin/realms/my-app/events?type=LOGIN_ERROR&max=20" \
  -H "Authorization: Bearer ${TOKEN}" \
  | jq .

Copy curl ⧉

Replace my-app with your realm name and \${TOKEN} with a valid admin token.

Event listeners

Beyond storing events in the database, Keycloak supports event listeners — plugins that react to events in real time. Two built-in listeners are useful immediately:

Listener	What it does
jboss-logging	Logs events to the Keycloak server log (enabled by default)
email	Sends an email to the user on events like LOGIN_ERROR

To enable a listener:

1. Go to Realm settings > Events > Event listeners.
2. Add the listener name from the drop-down.
3. Click Save.

For custom integrations (e.g., sending events to a webhook or a message queue), you can implement a Keycloak SPI (EventListenerProvider) and deploy it as a provider JAR.

🔐 Enable events before an incident, not after

Enable login and admin events before you go live — they are your audit trail. Enabling them after an incident means you have already lost the data you need to investigate. Set a sensible expiration (7–30 days) to keep storage under control.

Trade-offs

Option	Benefit	Cost
Store admin events with “Include representation”	Captures the full before/after JSON payload of every change — ideal for audits that need to know exactly what changed	Significantly increases storage use, especially in realms where admins change configuration often
Short expiration (7 days)	Keeps storage bounded with no manual archiving	If an incident needs investigating further back than 7 days, the data may already be gone
Long expiration, or export outside the system	Supports compliance/audit requirements that need a long history (e.g. SOC2)	Increases storage cost and requires a separate archive/export mechanism

Common mistakes

• Not enabling events until something goes wrong — events are disabled by default, and many teams only turn them on after an incident, leaving no data to investigate. Enable them before going live.
• Never setting an expiration — letting events accumulate indefinitely in the database makes the table grow until it affects Keycloak’s own performance. Set an expiration that matches your audit needs.
• Enabling “Include representation” on every realm without considering storage cost — this stores the full JSON payload of every change in every realm, including realms that don’t need that level of detail, adding unnecessary storage overhead.

Real-world example

SOC2 / compliance audits — organisations that need to pass SOC2 or a similar compliance standard commonly configure admin events to store the full representation, then periodically export them to a SIEM or external log aggregator to prove every identity-related change is recorded.

Security incident response — security teams use login events to investigate which accounts were targeted by credential stuffing, filtering by the LOGIN_ERROR event type and time window through the Admin REST API instead of paging through the console screen by screen.

What is the difference between login events and admin events in Keycloak?

Login events are for admins; admin events are for end-users Login events record end-user actions; admin events record administrator actions There is no difference — they are stored in the same log Login events are permanent; admin events expire automatically

Where in the admin console do you enable event storage?

Clients > Sessions Realm settings > Events Users > Attributes Authentication > Flows

What does enabling "Include representation" for admin events do?

It shows the UI screenshots of each admin action It stores the full JSON payload of each admin change for detailed auditing It sends admin events to an external webhook automatically It enables GDPR anonymisation of event data

Which built-in event listener sends an email to the user on login errors?

jboss-logging webhook email syslog

Submit

Mark as complete