Keycloak Auditing & Event Logging: The Complete Guide

Last updated: May 2026

Keycloak records two categories of events — user/login events and admin events — configurable per realm under Realm Settings > Events. You enable them, select which event types to capture, set a retention window, and forward them to external systems via the Event Listener SPI for long-term audit trails and real-time alerting. Without explicit configuration, events fire but are not persisted to the database and are only written to the server log by the built-in jboss-logging listener.

This guide covers everything you need to build a production-grade auditing pipeline on Keycloak 26.x: why event logging matters for security and compliance, the two event models and how to enable them, built-in listeners, database storage and its limits, the Event Listener SPI, forwarding to SIEM and syslog, alerting on suspicious patterns, log integrity, compliance mapping, and a practical checklist.

Why Audit Logging Matters

Identity systems are the front door of your infrastructure. Every authentication attempt, every token grant, every change to a user’s roles or a realm’s configuration passes through Keycloak. Without a complete, tamper-resistant record of those events, you cannot answer the fundamental questions that security and compliance teams ask:

• Who authenticated, from where, and when?
• Which administrator changed this client’s redirect URI last Tuesday?
• Was this user’s account locked before or after the attacker escalated privileges?

The OWASP Logging Cheat Sheet and NIST SP 800-92 both identify identity and access events as among the highest-priority log sources in any system. Regulations including GDPR, HIPAA, SOC 2, and PCI-DSS each require demonstrable evidence of access monitoring and log retention. Without it, you cannot pass an audit, respond to an incident effectively, or detect insider threats.

Skycloak’s built-in audit log capabilities surface these events in a managed UI without adding load to your Keycloak database. The Insights dashboard provides visual analytics over authentication patterns, making it practical to spot anomalies before they become incidents.

The Two Keycloak Event Types

Keycloak emits events through two separate systems, each with a different data model and a different audience.

Login Events (User Events)

Login events capture end-user activity: authentication attempts, logouts, token grants, registrations, profile changes, and consent operations. They are the primary signal for security monitoring and brute-force detection. Each event carries:

• type — the event identifier (e.g., LOGIN, LOGIN_ERROR, LOGOUT)
• realmId / realmName — the realm where the event occurred
• clientId — the application involved
• userId — the user involved (absent for unauthenticated attempts)
• sessionId — the session, useful for correlating events across a session
• ipAddress — the source IP address
• time — epoch milliseconds
• details — a map of event-specific key/value pairs (e.g., auth_method, username, redirect_uri)
• error — for error events, a machine-readable error code

Common event types worth capturing for security purposes:

Event type	Why it matters
LOGIN	Successful authentication baseline
LOGIN_ERROR	Failed attempts; the raw signal for brute-force detection
LOGOUT	Session termination
REGISTER	New account creation; watch for enumeration patterns
UPDATE_PASSWORD	Credential change; correlate with SEND_RESET_PASSWORD
SEND_RESET_PASSWORD	Password reset initiated
UPDATE_TOTP / REMOVE_TOTP	MFA changes; high-value account takeover indicator
VERIFY_EMAIL	Email verification events
CODE_TO_TOKEN_ERROR	Token exchange failures; possible replay attempts
REFRESH_TOKEN_ERROR	Expired or reused refresh tokens
REVOKE_GRANT	Consent revocation

Admin Events

Admin events record changes made through the Admin Console or Admin REST API. Where login events tell you what users did, admin events tell you what administrators changed. They use a different structure:

• operationType — CREATE, UPDATE, DELETE, or ACTION
• resourceType — what was changed: USER, CLIENT, ROLE, GROUP, REALM, IDENTITY_PROVIDER, etc.
• resourcePath — the specific resource (e.g., users/uuid-123, clients/client-uuid/client-secret)
• authDetails — who made the change: the admin’s user ID, client, IP address, and realm
• representation — an optional JSON snapshot of the resource after the change

The representation field is controlled by the Include representation toggle in Admin Events Settings. When enabled, Keycloak stores the full JSON body of the changed resource alongside the event. This is invaluable for reconstructing what a configuration looked like before a change, but it significantly increases database storage. Enable it selectively — or only when forwarding events to an external store with adequate capacity.

Key admin event resource types to monitor:

Resource type	What to watch
REALM	Settings changes (brute force policies, token lifetimes)
CLIENT	Redirect URI changes, secret rotations
USER	Role assignments, status changes (disabled/enabled)
ROLE	New roles, role membership changes
IDENTITY_PROVIDER	IdP configuration changes
AUTHENTICATION_FLOW	Flow modifications (can affect all users)

Enabling Events: Admin Console

All event configuration lives at Realm Settings > Events in the Keycloak Admin Console (Keycloak 26.x, Quarkus distribution).

Enable Login Events

1. Navigate to Realm Settings > Events.
2. Select the User events settings tab.
3. Toggle Save events to On. This persists events to the EVENT_ENTITY table.
4. In Event types saved, select the event types you want to retain in the database. The default is all types; for a lean DB footprint, select only the types you actively query.
5. Set Expiration to the number of seconds events should live in the database (e.g., 604800 for 7 days). Events older than the expiration are purged on the next cleanup pass.
6. Click Save.

Enable Admin Events

1. Under the same Events page, select the Admin events settings tab.
2. Toggle Save events to On.
3. Toggle Include representation as needed (see the note above on storage implications).
4. Set Expiration for admin events independently of user events.
5. Click Save.

Configure Event Listeners

Event listeners determine where events are sent regardless of whether database storage is enabled. They are configured under Realm Settings > Events > Event listeners.

The jboss-logging listener is active by default. It writes error events (and only error events, at WARN level) to the Keycloak server log. To log successful events, you must adjust the log level for the org.keycloak.events category — though for production monitoring, sending events to an external system via a custom listener is the better approach.

To add a custom listener, type its provider ID into the Event listeners field and save. The listener must be deployed as a JAR in Keycloak’s providers/ directory and registered via the SPI service loader.

Enabling Events: Realm Export / API

For environments managed through infrastructure-as-code or the Admin REST API, you can enable events in the realm representation:

{
  "eventsEnabled": true,
  "eventsExpiration": 604800,
  "eventsListeners": ["jboss-logging", "your-custom-listener"],
  "enabledEventTypes": [
    "LOGIN", "LOGIN_ERROR", "LOGOUT", "REGISTER",
    "UPDATE_PASSWORD", "SEND_RESET_PASSWORD",
    "UPDATE_TOTP", "REMOVE_TOTP",
    "CODE_TO_TOKEN_ERROR", "REFRESH_TOKEN_ERROR"
  ],
  "adminEventsEnabled": true,
  "adminEventsDetailsEnabled": true
}

Apply with the Admin REST API:

curl -s -X PUT 
  -H "Authorization: Bearer ${ADMIN_TOKEN}" 
  -H "Content-Type: application/json" 
  -d @realm-events-config.json 
  "https://your-keycloak-host/admin/realms/your-realm"

The adminEventsDetailsEnabled field corresponds to Include representation in the UI.

The Built-In jboss-logging Listener

Keycloak ships with one event listener enabled by default: jboss-logging. It writes events to the Keycloak application log via JBoss Logging, which in the Quarkus distribution outputs to stdout (and to a file if file logging is configured).

By default, only error events are logged at WARN level. Successful events are logged at DEBUG level and are suppressed in most production log configurations. To surface successful events in your log output:

# quarkus.properties or via environment variable
quarkus.log.category."org.keycloak.events".level=DEBUG

Or via the KC_LOG_LEVEL environment variable:

KC_LOG_LEVEL=org.keycloak.events:DEBUG

The jboss-logging listener is appropriate for basic operational visibility. For a production security pipeline, it should be complemented by a custom listener that forwards events to an external system rather than relying on log scraping.

Database Storage: The EVENT_ENTITY Table

When Save events is enabled, Keycloak persists events to the EVENT_ENTITY table in its database. Admin events go to ADMIN_EVENT_ENTITY.

These tables have a straightforward schema: one row per event, with columns for each of the fields described above. The details map is stored as a serialized string in older Keycloak versions; in Keycloak 25+ it is stored in a separate EVENT_ENTITY_DETAILS table joined by event ID.

Why Database Storage Does Not Scale for Long-Term Retention

The database-backed event store is appropriate for short-term operational lookup — reviewing what happened to a user account in the past week, for example. It is not appropriate as a compliance archive. Three issues make long-term DB storage impractical:

1. Volume: A realm with thousands of daily active users generates millions of events per month. Even with selective event type filtering, the tables grow quickly.
2. Query performance: The EVENT_ENTITY table has limited indexing. Queries over long time ranges or complex filter combinations degrade as the table grows.
3. No integrity guarantees: Anyone with database access can modify or delete rows. This is not acceptable for compliance evidence.

Set Expiration to a short window (7-30 days) for operational use, and rely on an external system for long-term retention and compliance-grade storage.

The Event Listener SPI

The Event Listener SPI is Keycloak’s extension point for custom event processing. Every event — both user events and admin events — passes through all registered listeners synchronously before the response is returned to the client. This means listener code must be non-blocking or complete quickly to avoid adding latency to authentication flows.

A custom listener implements two Java interfaces:

• EventListenerProvider — the per-event handlers: onEvent(Event event) for user events and onEvent(AdminEvent event, boolean includeRepresentation) for admin events
• EventListenerProviderFactory — creates listener instances, reads configuration from Config.Scope, and returns a stable provider ID used to register the listener in the Admin Console

Deploy the listener as a JAR in /opt/keycloak/providers/, then run /opt/keycloak/bin/kc.sh build to register it with Quarkus’s augmented classpath. The listener then appears as an option in Realm Settings > Events > Event listeners.

For a deep dive into building custom SPI providers, see the Keycloak custom SPI development guide. For complete webhook listener code examples including HMAC signing and retry logic, see Keycloak event streaming and webhooks.

Forwarding Events to External Systems

Database storage handles short-term lookups. External forwarding handles everything else: long-term retention, cross-system correlation, real-time alerting, and compliance archiving. Keycloak supports three primary forwarding mechanisms.

HTTP Webhook

A webhook listener posts events as JSON payloads to an HTTP endpoint. This is the most flexible approach and integrates directly with SIEM platforms that expose a REST ingest API (Splunk HEC, Datadog Log Intake, Elastic Logstash HTTP input), as well as with automation platforms and custom downstream services.

Skycloak’s managed platform provides a built-in webhook event listener with HMAC verification, configurable batch intervals, and event type filtering — no custom SPI development required. For full configuration steps, see Forward Keycloak Events to SIEM via Skycloak HTTP Webhook.

Key security requirements for webhook endpoints:

• The endpoint must be reachable over HTTPS. Keycloak event payloads contain user identifiers and IP addresses.
• Authenticate incoming requests with a shared secret (Bearer token or HMAC signature). Reject any request that does not carry a valid credential.
• Return a 2xx response quickly. Process asynchronously if the downstream operation is slow.

Syslog

Syslog (RFC 5424) is the standard protocol for log transport in traditional enterprise environments and is natively understood by most SIEM platforms — Splunk, IBM QRadar, Elastic, Datadog, and others. A Keycloak syslog listener formats events as structured syslog messages and forwards them over TCP with TLS (port 6514).

For production deployments, always use TLS over TCP. UDP syslog offers no delivery guarantee and transmits event data in cleartext. For full configuration and SIEM-specific parsing guidance, see Integrating Skycloak Security Logs Using Syslog.

Message Queues (Kafka, RabbitMQ)

For high-throughput environments or architectures that require fan-out to multiple downstream consumers, a message queue provides durability, ordering per partition, and the ability to replay events. A Kafka listener publishes each event as a message to a topic (keycloak-user-events, keycloak-admin-events). Downstream consumers — a SIEM connector, a compliance archiver, an alerting service — subscribe independently.

The tradeoff is operational complexity. Running Kafka adds infrastructure that must be sized, monitored, and maintained. For most teams, webhooks or syslog deliver the required functionality with lower overhead.

Alerting on Suspicious Events

Event collection without alerting is a compliance exercise, not a security one. The value of Keycloak’s event system lies in its ability to feed real-time alerting. The following event patterns warrant immediate notification.

Brute Force and Credential Attacks

Alert when a single user account or source IP generates more than a threshold number of LOGIN_ERROR events within a short time window. A starting point:

eventType="LOGIN_ERROR"
| stats count by details.username, ipAddress
| where count > 10 in 5 minutes

Keycloak has a built-in brute force protection mechanism (configurable under Realm Settings > Security Defenses > Brute Force Detection) that locks accounts after a configurable number of failures. However, it operates per-realm and does not cover distributed attacks across multiple usernames from a shared IP, which your external alerting can catch.

Privilege Escalation

Alert on any admin event that assigns elevated roles to a user, particularly roles in the realm-management client (e.g., manage-users, realm-admin):

eventType="admin_event" AND operationType="CREATE"
AND resourceType="REALM_ROLE_MAPPING"

New grants of any admin-level role in production should correlate with a change management ticket. If they do not, treat them as incidents.

Admin Configuration Changes

Any modification to authentication flows, realm settings, or client redirect URIs in production should be logged and reviewed. These changes can silently weaken security posture:

• Disabling MFA requirements
• Extending token lifetimes
• Adding unauthorized redirect URIs
• Modifying or disabling brute force protection

Alert on admin_event with resourceType in AUTHENTICATION_FLOW, REALM, or CLIENT and operationType in UPDATE or DELETE.

Unusual Token Activity

Spikes in REFRESH_TOKEN_ERROR or CODE_TO_TOKEN_ERROR may indicate token replay attempts or a misconfigured integration. Baseline normal volumes first, then alert on deviations greater than two standard deviations from the 7-day average.

New Admin User Grants

Alert whenever a new user receives any role in the master realm or receives manage-realm in any realm. These events should be rare and expected.

For a broader discussion of insider threats and IAM security controls, see Reducing Insider Risk with IAM Security Measures.

Log Integrity and Tamper Resistance

Audit logs are only legally and operationally useful if they cannot be modified undetected. Keycloak’s database-backed event store provides no integrity guarantees — anyone with write access to the database can alter or delete rows. For compliance-grade audit trails, enforce integrity at the storage layer:

• Write-once storage: Archive events to an immutable store (AWS S3 Object Lock, Azure Blob immutability policies, or a dedicated WORM-capable log management system). Once written, records cannot be modified or deleted within the retention period.
• Log signing: Some SIEM platforms and log management systems support hash chaining or digital signatures over log batches, allowing detection of gaps or modifications.
• Separate credentials: The account that writes events to the archive should have no read or delete permissions. Separate the write path from the query path.
• Monitor the pipeline itself: Set up an alert for gaps in log delivery. A 15-minute silence during business hours is worth investigating. An undetected gap in your audit trail is indistinguishable from log deletion.
• Access controls on raw logs: Restrict access to raw event storage to security and compliance personnel. Developers and operations engineers should query logs through an interface that provides audit trails of its own.

Compliance Mapping

The table below maps common compliance requirements to Keycloak event configuration. It is not exhaustive and should be reviewed with your legal and compliance team.

Framework	Key requirement	Keycloak configuration
SOC 2 (CC6, CC7)	Monitor logical access; detect anomalies	Enable login and admin events; alert on LOGIN_ERROR, role changes, and admin config changes
GDPR (Art. 32)	Demonstrate appropriate security measures; support data subject access	Retain admin events for user data changes; log UPDATE_PROFILE, DELETE_ACCOUNT
HIPAA (45 CFR 164.312)	Audit controls; activity review	Enable all event types; retain for 6 years in external archive
PCI-DSS (Req. 10)	Log all access to cardholder data; retain for 12 months	Forward events to immutable external store; alert on LOGIN_ERROR thresholds
NIST 800-53 (AU family)	Audit record generation, review, and protection	Enable events, forward to SIEM, implement log integrity controls

Skycloak achieved SOC 2 Type I certification, establishing that its event capture and security controls meet the standard’s requirements. See the SOC 2 announcement for details.

Practical Configuration Checklist

Use this checklist when deploying or auditing a Keycloak realm for production.

Enable and scope events

• [ ] Login events enabled with Save events toggled On
• [ ] Admin events enabled with Save events toggled On
• [ ] Include representation evaluated — enabled only if you have external storage with capacity
• [ ] Event types scoped to those relevant to security and compliance (not necessarily all types)
• [ ] Expiration set to 7-30 days for DB storage (operational window only)

Configure listeners

• [ ] jboss-logging present for baseline log output
• [ ] Custom event listener (webhook, syslog, Kafka) deployed and registered per realm
• [ ] Listener configuration validated: endpoint reachable, authentication credential set, event types filtered appropriately
• [ ] Listener deployed as JAR in providers/ and kc.sh build run after deployment

Forwarding and storage

• [ ] Events forwarding to external system (SIEM, log management, or message queue)
• [ ] TLS enforced on all log transport paths
• [ ] Long-term archive configured (minimum 12 months; 6 years for HIPAA)
• [ ] Write-once storage or log signing implemented for compliance evidence
• [ ] Access controls on raw log storage reviewed and enforced

Alerting

• [ ] Alert on LOGIN_ERROR threshold (per user, per IP) to detect brute force
• [ ] Alert on admin role grants in production
• [ ] Alert on admin configuration changes in production (authentication flows, realm settings, client configs)
• [ ] Alert on log pipeline gaps (silence detection)
• [ ] Alerts tested with synthetic events; thresholds documented

Review

• [ ] Periodic log review scheduled (monthly minimum)
• [ ] Alert thresholds reviewed and tuned after first 30 days
• [ ] Compliance retention verified against external archive

Frequently Asked Questions

How do I enable audit logging in Keycloak?

Navigate to Realm Settings > Events in the Admin Console. Under User events settings, toggle Save events to On to persist login events to the database; under Admin events settings, do the same for admin events. Select which event types to capture, set an expiration window, and ensure at least the jboss-logging listener is in the Event listeners list. For production, add a custom listener that forwards events to an external system rather than relying on database storage alone.

Where does Keycloak store events?

When Save events is enabled, Keycloak stores user events in the EVENT_ENTITY table and admin events in ADMIN_EVENT_ENTITY in its relational database (PostgreSQL or MySQL in production). Events are also written to the application log by the jboss-logging listener. For long-term retention or compliance purposes, forward events to an external SIEM, log management platform, or immutable archive using a custom Event Listener SPI provider or Skycloak’s built-in forwarding capabilities.

How long does Keycloak keep events?

Keycloak retains events in the database for the duration configured by the Expiration setting under Realm Settings > Events. The value is in seconds — for example, 604800 equals 7 days. Events older than the expiration are purged during cleanup cycles. There is no built-in long-term archiving; for compliance retention requirements (1-6 years depending on the framework), forward events to an external system before they expire.

How do I forward Keycloak events to a SIEM?

Keycloak forwards events to external systems via the Event Listener SPI. You can build a custom listener that sends events as JSON to an HTTP endpoint, forwards them via syslog over TLS, or publishes them to a Kafka topic. If you are using Skycloak managed hosting, the platform provides a built-in HTTP webhook listener and syslog forwarding without custom SPI development. See Forward Keycloak Events to SIEM via Skycloak HTTP Webhook for webhook setup and Integrating Skycloak Security Logs Using Syslog for syslog configuration.

What Keycloak events should I capture for security monitoring?

At minimum, capture LOGIN_ERROR (failed authentication), UPDATE_PASSWORD, SEND_RESET_PASSWORD, UPDATE_TOTP, REMOVE_TOTP, and all admin events affecting users, roles, clients, and realm settings. LOGIN and LOGOUT events provide the baseline for session correlation and behavioral analytics. REGISTER events help detect mass account creation patterns. The combination of these types covers the most common attack patterns: credential stuffing, account takeover, privilege escalation, and unauthorized configuration changes.

---

Getting Event Logging Right Without the Overhead

Configuring Keycloak event logging correctly requires enabling the right event types, wiring up an external forwarding pipeline, managing database expiration, implementing alerting rules, and enforcing log integrity at the storage layer. Each of these is a distinct operational concern — and on a self-hosted cluster, all of them are yours to maintain.

Skycloak’s managed Keycloak hosting handles the infrastructure layer so your team can focus on the security outcomes. The built-in Event Viewer provides searchable access to authentication events without adding load to your Keycloak database, and SIEM forwarding via HTTP webhook and syslog is configurable through the dashboard without writing custom SPI code. Review the pricing page to see what is included in each plan.