Keycloak audit logging starts with knowing which events you need
Keycloak records user events and admin events once they are enabled for a realm. User events capture login activity such as successful sign-ins, failed attempts and logouts, while admin events capture create, update and delete actions made through the admin console or the Administration REST API. Those two streams answer the questions auditors and security teams ask most often: who signed in, from where, and which administrator changed a client, role or user. The configuration decides what is captured, how long it stays in Keycloak, and whether it reaches a SIEM. Those settings should be settled before the first audit request arrives, so the team is not deciding them under pressure.
Teams usually need this in three situations. The first is a regulated access review, where a control owner must show which accounts authenticated during a period and whether privileged changes were approved. The second is incident investigation, where responders trace a suspicious account across sign-ins, failed attempts and the administrator changes that followed. The third is control evidence, where a framework or internal policy asks for proof that authentication and administrative activity are logged and reviewed. Each situation sets a different bar. An investigation needs records that are quick to search, while an access review needs a complete, bounded period that can be exported and explained to an auditor.
Enabling the setting is only the start of the work. Before changing anything in the realm, list the questions the logs must answer and map each one to an event type. Decide which user event types are stored, whether admin events should include the representation of the changed object, and which realms are in scope. Representations give investigators the before and after content of a client, role or user, but they can also place personal data or configuration secrets into the log store. That trade-off needs sign-off from security and privacy owners, and the answer may differ between a production realm and a test realm.
Next, confirm the system of record. Keycloak can keep events in its own database, forward them to a SIEM through a custom event listener built on the Listener SPI, or do both. Write down who owns each store, how long events must be kept, and who is allowed to read them. Then check that the forwarding component is maintained for the Keycloak version you run, since listener code is yours to test during upgrades. Finally, test the full chain before an audit window opens: generate a successful sign-in, a failed sign-in and an administrator change, then confirm each one appears in the expected store with the fields your investigators need. Ask any implementation partner to show that test result in writing.
Which Keycloak event settings fit which audit requirement
This table compares the main Keycloak event settings for login and admin audit trails, with the storage, data sensitivity and build effort each one adds. Read each row against the evidence your auditors expect, then confirm exact setting names and defaults in the server administration guide for your Keycloak version. The main takeaway is that the database alone can hold events for a bounded period, while long-term retention and tamper resistance usually need forwarding.
| Setting | When it fits | What it costs |
|---|---|---|
| User event capture and event types | Auditors ask who signed in, from where, and whether sign-in failed, including logouts and account changes made by users. | Each enabled event type adds rows to the events table. Failed sign-ins and token events can be high volume, so storage grows with user count. Recent upgrade notes say login failures are persisted by default in 26.8, so check volume after upgrading. |
| Admin event capture | Auditors ask who changed realms, clients, users, roles or identity providers, and when those changes happened. | Volume is usually far lower than user events, but every administrator action is recorded. Confirm that admin events are switched on separately from user events in your version. |
| Include admin event representations | Auditors need before-and-after detail for a changed object, not only a record that a change occurred. | Stored JSON can contain personal data, attributes and configuration detail, which raises the sensitivity of the database and any export. Decide who can read these records and whether exports are restricted before enabling it. |
| Event expiration in the database | Your retention policy sets a fixed period, and the Keycloak database is the only place events are kept for that period. | Shorter expiration limits database growth but removes evidence sooner, so exports must run before events expire. Confirm whether the expiration setting applies to user and admin events in the same way. |
| Forwarding through a custom Listener SPI provider | Events must reach a SIEM or central log store with separate retention, access control and alerting outside the Keycloak database. | This needs a custom provider built against the Listener SPI, deployed into the server and retested on each upgrade. The design must also decide what happens to events when the receiving system is unavailable. Confirm the interface details for your version. |
What Keycloak records for logins and administrator changes
Keycloak keeps two different kinds of record, and auditors usually ask for each one separately. User events cover authentication activity: logins, logouts, token requests and failed attempts made by people and applications. Admin events cover changes made to the realm: create, update and delete operations performed through the admin console or the Administration REST API, such as adding a user, editing a client's redirect URIs or assigning a role. Each category is enabled separately, so turning on one does not capture the other. Confirm in the server administration guide for your version where each setting lives, which realm it applies to, and which event types each category covers.
An admin event can include a representation, which is the JSON body of the object that was sent to or changed in Keycloak. Including it is what gives the record its evidence value: you can show what a client or user looked like before and after an edit, not only that an edit occurred. The same content raises the sensitivity of the stored data. A representation for a user or a client can carry personal data and configuration values your security team may treat as secrets. Decide event type by event type whether the extra detail is worth the exposure, and confirm with your security and privacy owners who can query the stored JSON, how the event store is protected, and how it is classified.
The Keycloak 26.8 upgrade notes state that login failures are persisted to the database by default. Failed attempts are often the most useful signal for spotting password guessing or credential stuffing, so keeping them has real value, but it also means the event table grows with every failed attempt. Before you upgrade, measure the current size and growth rate of your event tables, confirm how and when old events are removed, and check that the database backup window and storage capacity can absorb the change. If your existing policy assumed only successful logins were stored, review the new default against that policy and against your data minimization commitments before production traffic reaches the new version.
Before you map any control to a Keycloak event, list the exact event types your version records and the fields each one carries. Event type names can change between releases, so a control mapping written from an older list may point at events that no longer exist or miss ones that were added. Build the list in a test realm: perform each action the control describes, export the resulting events, and confirm that each one shows the expected user, client, timestamp and other fields you rely on. Keep the version number, the realm settings and the exported sample as evidence, and write the control mapping from that verified list.
How to enable and verify Keycloak audit events
This sequence turns on login and admin event capture for each Keycloak realm, sets how long events are kept, and uses test activity to prove each record names the actor, time, realm and target. It ends with forwarding to your SIEM, a persistence test and a documented baseline that change control can enforce.
Decide the event scope for each realm
Before changing any setting, the security or compliance owner lists each realm and states which of its activity must be recorded, such as sign-ins to customer-facing applications and administrative changes in the admin console. Realms that hold workforce identities often need a different scope from customer realms, so write the decision for each realm separately. The step is done when the scope document names every realm, its owner and the events it must capture, and a reviewer has checked the list against the applications that depend on each realm.
Enable user events and chosen event types
In each realm's event settings, the platform team turns on user events and selects the event types that match the scope from the previous step. Login success, login error and logout cover most sign-in investigations, but compare the full list with what the audit team expects before saving. To check the setting, sign in with a test account and confirm the record appears in the user events list with the expected client, user and IP address fields populated.
Enable admin events and decide on representations
In the same settings area, turn on admin events and decide whether to store representations. A representation captures the request body of an administrative change, which helps reviewers see exactly what changed, but it can also hold personal data or secrets from user and client records. Confirm that position with the privacy and security owners first. To verify, make a test change such as adding a role to a test user, then confirm the admin event shows the acting administrator, time, realm and target resource.
Set event expiration to match retention policy
Set event expiration so that stored events are kept for the period your retention policy requires. Ask the audit or compliance owner for that period in writing, since it should come from policy rather than from a default someone remembers. Verify by confirming the expiration value is saved, then checking in a non-production realm that events older than the configured period are removed on the schedule your team has documented.
Trigger test logins and admin changes
Generate a controlled set of activity in a test realm: a successful sign-in, a failed sign-in with a wrong password, and an administrative change such as creating a test group. For each resulting record, confirm the actor, time, realm and target are present and match what you did. Failed logins need particular attention, because the record should show the attempted username and error type while the password itself does not appear. Keep the test results as evidence of what the configuration captures.
Confirm events reach the forwarding target
Confirm that the same events arrive at the forwarding target, which is typically a SIEM. Keycloak sends events to a listener provider that is registered per realm, so check that the listener is active in each realm and that the fields your analysts need are present in the forwarded data. Confirm the listener's behavior against your Keycloak version before you rely on it. To verify, repeat the test logins and the admin change, search for each event in the target, and compare its timestamp and realm name with the Keycloak record.
Test persistence through restart and failover
In a non-production environment that matches production's database and clustering layout, restart the Keycloak nodes and fail over the database, then repeat the test activity. Confirm that events recorded before each disruption are still present and that new events are written after recovery. Ask the database team which failover method they will use and whether replication is synchronous, since Keycloak's supported high availability designs require a synchronously replicated database. Record any gap as a finding and resolve it before production use.
Record settings as change-controlled configuration
Store the realm event settings, the listener configuration and the test results in your change management system, with a named owner for each setting. Route any later change to event types, representations, expiration or forwarding through the same approval path, and repeat the verification tests after each change. The step is complete when a reviewer can compare the current configuration with the approved baseline and find no unexplained differences.
How to forward Keycloak events to a SIEM through the Listener SPI
The Listener SPI is the route to choose when stored events in Keycloak are not enough and a security operations team needs them in a SIEM. A custom event listener receives Keycloak events as they are produced and can send them to an external system. That capability has a cost: your team writes, tests, packages and maintains the listener code. Before committing, decide which event types the listener must forward, such as failed logins from the user events settings and resource changes from admin events, and confirm that someone on your team can own that code for the life of the deployment. Illustrative example: a listener that forwards only login error and admin resource events to the SIEM, while the full set stays in the database for investigators.
Transport is the first design decision. Syslog is widely supported by SIEM platforms and is simple to operate, but plain UDP gives no delivery acknowledgment, so choose a TCP or TLS-protected syslog path if the events are audit evidence. HTTPS to an ingestion API carries structured payloads and authentication, but it ties the listener to the SIEM vendor's endpoints, rate limits and token handling. A message queue separates Keycloak from SIEM availability and lets several consumers read the same stream, at the cost of running another stateful service in your environment. Ask the SIEM team which transports they will operate, monitor and patch, and record that answer before writing any listener code.
Field mapping and delivery behavior need written answers. Map Keycloak event attributes, including event type, realm, client ID, user ID, IP address and error, to the SIEM's field names, and decide how admin event representations are stored or trimmed, since they can contain sensitive configuration. Decide whether timestamps are sent in UTC and whether each event carries a unique identifier so duplicates can be detected. Then define what happens when the SIEM is unreachable: buffer locally with a bounded queue, retry with backoff, or drop. Dropped events create gaps in audit evidence, so test the behavior by stopping the SIEM in a non-production realm and checking what arrives afterward.
Wazuh is one SIEM option. Its indexer stores alerts as a full-text search and analytics engine, and the Wazuh server accepts syslog from agentless sources through collection. The available documentation does not establish how Wazuh ingests custom Keycloak event payloads, so confirm this with the Wazuh documentation and a proof of concept before committing. Check whether the decoders and rules can parse your field layout, and whether the indexer receives raw events or only alerts derived from them. Packaging and upgrades belong in the same plan: the listener is deployed alongside Keycloak and must be rebuilt and retested for each Keycloak release, so keep it in version control, pin its build, and include it in every upgrade test.
Protecting audit data and the people it describes
Audit events are useful to an assessor only if they are complete, protected, and reviewed by someone other than the people they record. The cards below cover the data events contain, who can reach them, how they travel to the SIEM, and the custom code that moves them there. Each card names one control and a question to put to your team or vendor before go-live.
Personal data in events and representations
Admin events can include representations of users, clients, and realm settings, and user events can record identifiers and IP addresses. Decide which fields are written to the event store and forwarded to the SIEM, and whether any must be masked, dropped, or minimized first. Ask the team to show sample admin event payloads from a test realm, and to confirm the retention period that applies to personal data in each store.
Read access to the event store and SIEM
Anyone who can query the event store or the SIEM can reconstruct who signed in, from where, and which administrators changed what. Limit read access to named roles, keep those roles separate from Keycloak administrator roles, and log the queries and exports that reviewers run. Confirm which accounts can export raw events and whether that access is reviewed on a set schedule.
Tamper resistance for stored records
Audit value depends on records that cannot be silently edited or deleted. Keycloak administrators and database operators may be able to reach the tables that hold events, so identify who holds update and delete rights on those tables and on the SIEM indexes. Confirm that the SIEM or a write-once store keeps its own copy of forwarded events, and that any deletion of audit data is itself recorded.
TLS on every forwarding path
Events forwarded from a listener to a SIEM, log collector, or message broker can cross networks that include shared segments. Require TLS on each hop, including the listener's connection to its endpoint, and confirm that certificates are validated against a trusted authority. Ask how the listener behaves when a connection fails: whether it retries, queues, or drops events, and whether a gap in delivery is detected and alerted.
Separation of duties for log reviewers
The people who administer Keycloak should not be the only people who review what they did. Assign log review to a group with read-only access to the SIEM and no rights to change realms, clients, or users. Confirm that changes made by a Keycloak administrator are visible to a reviewer outside that administrator's team, and that each review is recorded with a date and an outcome.
Listener code in the patch cycle
A custom Listener SPI provider runs inside the Keycloak process and handles every event it receives, so a defect or unpatched dependency there can affect both sign-in and audit coverage. Keep the listener in source control, build it against the Keycloak version you run, and apply the same patch, review, and test steps used for Keycloak upgrades. Confirm who approves listener changes and how the code is tested against the next Keycloak release before rollout.
How long Keycloak keeps events and what that does to the database
The retention decision for Keycloak events is a database capacity decision as well as a compliance one. Login and admin events are written to the Keycloak database when event storage is enabled, and they accumulate until something removes them. The realm's event expiration setting controls how long stored events are kept before the server deletes them. Keycloak does not decide how long audit evidence must exist. That period comes from your organization's records policy and from the regulators and contracts that apply to your systems. Take the number from those documents and set it deliberately instead of accepting whatever the fresh realm happens to use.
Keeping events in Keycloak supports short-term investigation. An administrator can search recent sign-in failures or a changed client setting without leaving the identity platform. It is a poor place for long-term evidence, because every retained event adds rows to tables that the same database serves for sign-in traffic. Longer retention is usually handled by exporting events to a system built for storage and search. The Listener SPI is the mechanism for that: a custom event listener receives events as they occur and can forward them to a SIEM or log store, so the record outlives the Keycloak expiration window. The trade-off is that the export pipeline becomes part of the audit trail and needs its own monitoring, alerting and failure handling.
The supported production databases are listed in the Keycloak database guide: MariaDB, Microsoft SQL Server, MySQL, Oracle Database, PostgreSQL (14 to 18), EnterpriseDB Advanced, Amazon Aurora PostgreSQL and Azure SQL. Confirm which version of your chosen engine you will run, and confirm that your team has tested event table growth on it. Event volume grows with sign-in activity, administrator actions and whether representations are stored, so size the tables from your own login rates and expected admin activity rather than from a generic estimate. Plan sizing, backups and purge jobs together. Backup windows and restore times depend on table size, and a large purge can add load to the database during business hours. Schedule purges outside peak periods, run a restore test that includes event tables, and confirm that backup retention covers the period your policy sets.
Before go-live, answer three questions in writing. Which event types must be retained, and for how long, according to our policy? Which system holds the copy that outlives Keycloak's expiration setting, and who can query it? How will we detect a failed export, so events are not lost silently during the gap? Record the answers next to the realm configuration and the purge schedule. Then confirm with your auditors that the exported copy and the Keycloak purge schedule together meet the stated period. Auditors typically test whether evidence exists for the full retention period, not whether a setting was changed once, so the operating records for the export pipeline matter as much as the configuration.
Limits to confirm before you promise audit coverage
Keycloak audit logging depends on the version, topology, administrative paths and SIEM design you choose. Each card names one limit to test before you describe coverage to an auditor or customer, and each check should be confirmed in the Keycloak documentation, in a test environment that matches production, and with the audit firm or certification body for your framework.
Event types and fields in your version
The login and admin event types, and the fields recorded for each, are defined by the Keycloak release you run, so a control mapping written for one version can drift after an upgrade. List the events your control needs, such as successful and failed logins, credential changes and client or role changes, and check each one against your version's documentation and a test realm. Record the exact fields captured, including user, client, realm and source address, so the evidence contains what the control requires.
Coverage across administrative paths
Administrators can change Keycloak through the admin console, the Administration REST API and, when run on Kubernetes, through custom resources managed by the Keycloak Operator. Confirm that admin events are produced for each path you permit, and test the same change through every path. Changes applied by an operator reconciliation, a realm import or a scripted API call may be recorded differently or not at all, so decide which paths production policy allows and restrict the rest.
Behavior in multi-node and multi-site clusters
Keycloak can run as a single cluster spread across availability zones or as a multi-site design, and event behavior may differ between these topologies. Confirm which nodes write events, whether every node records the same events, and how a node restart or site failover affects events that are in flight. Test a login on each node and a failover during an active session. Include the synchronously replicated database that both supported high availability designs require in the same review.
SIEM delivery guarantees
Forwarding events to a SIEM through a Listener SPI provider is code your team owns, and Keycloak does not provide built-in guarantees that each event reaches the SIEM. The provider must handle timeouts, retries, ordering and buffering, and it must not block sign-in when the SIEM is unreachable. Ask what happens to events during a SIEM outage or a node restart, test with the SIEM stopped, and confirm how gaps are detected, for example through sequence checks or record counts against the database.
Events alone do not prove control operation
An event log shows that something happened, but an auditor also needs evidence that a control was designed, applied and operated across the audit period. A record of failed logins does not show that lockout policy was approved, enforced consistently or reviewed. Plan evidence beyond events, including configuration exports, change approvals, access reviews and periodic test results. Ask the audit firm or certification body for your framework which evidence they accept and over what period.
Questions teams ask before enabling Keycloak audit events
What drives the cost of setting up Keycloak audit event logging?
Cost follows scope, and the main drivers are the number of realms, the event types you enable, the SIEM you forward to, and whether a listener must be built. Each realm needs its own event configuration, review and testing, so more realms means more work. Event types differ in volume and in what they reveal, so choosing which login and admin events matter is a design task in its own right. SIEM integration depends on the target's ingestion format, parsing rules and access model. A custom listener built on the Listener SPI adds development, packaging, upgrade testing and performance checks. Most of the cost is one-time build and testing, while upgrades, rule changes and evidence refreshes recur. Ask for a quote that lists each component separately, states assumptions about realms and event types, and names who owns the SIEM side.
How long does a Keycloak audit logging project usually take?
Duration depends on scope, and no single timeline fits every environment. Enabling user and admin event settings in one realm is a short configuration task, while a listener that must be built, tested in a non-production environment and promoted through change control adds several stages. Other drivers include the number of realms, how quickly your SIEM team can confirm the event format, how long change approvals take, and whether your auditors want a review of the evidence before the work closes. Confirm the schedule in the written scope, including which dependencies sit with your team, such as SIEM access, test accounts and approval windows. A schedule that names those dependencies is easier to hold than one that only lists DeployOpen's tasks.
What does a Keycloak audit logging project need from our team?
The work needs a few named people and access, and missing any of them is the most common source of delay. Plan for the following:
- A SIEM owner who can confirm the ingestion format, accept the events and set parsing and alert rules.
- Access to a non-production Keycloak environment for testing, plus read access to the production configuration so the current state can be documented.
- A written retention policy that states how long login and admin events must be kept and where.
- Sample audit requests from internal audit or the external auditor, showing the exact records and periods they expect to see.
- A change approval path for production configuration and any listener deployment.
These inputs let the scope be fixed in writing before build work starts.
Can our own team enable Keycloak audit events without outside help?
Yes, a capable team can usually enable user and admin event settings and check that events appear in the admin console. That step is configuration, and it is a reasonable first move for most teams. The work gets harder in two places. Listener development requires Java, familiarity with Keycloak's SPI model, packaging, error handling so events are not silently dropped, and testing after every Keycloak upgrade. Evidence mapping requires knowing which control requirements in your framework the logs must support and what an auditor will test. Many teams enable settings internally, then ask a partner to review the event design, build the forwarding path or prepare the evidence pack. Whichever path you choose, run the first forwarding test in staging and compare sample login and admin actions against what arrives in the SIEM.
Do we need a custom listener to send Keycloak events to our SIEM?
Not always, and the answer depends on what your SIEM accepts and what your Keycloak version supports. Confirm the export and forwarding options documented for your version before assuming a custom build is needed. A custom listener is useful when the SIEM needs a specific format, transport or authentication method that the built-in options do not cover. The Listener SPI lets custom code receive events as they are produced and send them onward. Building one means deciding how to handle SIEM outages, whether to buffer or retry, how to avoid duplicates, and how to keep personal data out of logs where it is not needed. Each Keycloak upgrade also requires retesting the listener, so the maintenance plan should be part of the quote from the start.
Will an auditor accept audit evidence that DeployOpen prepares for us?
DeployOpen prepares systems, configuration and evidence, but it does not issue audit reports, attestations or certifications. Independent auditors and certification bodies decide whether your evidence meets their criteria. Typical evidence includes exported event settings, documented retention configuration, sample event records, forwarding test results, access records for administrators and a mapping from each control requirement to the artifact that supports it. Ask your auditor early to review the evidence format and the sample requests, so the pack matches what they will test. Any statement that a particular auditor will accept a specific package should come from that auditor, not from the implementation partner.
How should we set retention for Keycloak login and admin events?
Retention should come from your written policy and your audit requirements, not from a default setting alone. Keycloak keeps events in its database for a period you configure, and long-term retention usually belongs in the SIEM or another log store with its own access controls and backups. Confirm how your Keycloak version expires stored events, how the database growth affects sizing, and whether the SIEM copy is the record your auditors will examine. Set separate periods for login events and admin events if your policy requires it. Test the expiry and the forwarding path together, because a short database retention period is only safe if the SIEM copy already exists.
What usually goes wrong when forwarding Keycloak events to a SIEM?
Most problems appear during testing or after an upgrade, and several are predictable. Events can be lost during a SIEM outage if nothing buffers or retries them. Retries can create duplicates that distort counts. Clocks that differ across cluster nodes make timelines hard to reconstruct. Event types that were never enabled leave gaps that look like missing activity. Logs can also collect personal data or sensitive fields that the retention policy does not allow. Finally, a custom listener can break after a Keycloak upgrade if nobody retests it. To catch these issues, run scripted test logins and admin changes in staging, compare counts in the SIEM, check timestamps across nodes and repeat the test after each upgrade.
How DeployOpen scopes and delivers Keycloak audit logging
DeployOpen treats Keycloak audit logging as a designed control that you can explain to an auditor. We agree login and admin event settings, storage, retention and SIEM forwarding in writing, then build and document them inside your own infrastructure. Engagements are fixed-scope, so deliverables and timelines are settled before work starts.
How we scope
- Written scope lists which login and admin event types are recorded, and why each one matters to your auditors.
- Scope settles whether representations are stored with admin events, and who may read them.
- Retention periods, storage location and the SIEM or log platform receiving events are confirmed before build.
How we build
- Configure realm user and admin event settings, with event listeners and expiration set to the agreed values.
- Build a listener that forwards login and admin events from Keycloak to your SIEM through the Listener SPI.
- Test each event type end to end, including delivery failures, field mapping and timestamp handling in your SIEM.
How we hand over
- Documentation covers the event configuration, listener code or deployment, field mapping and retention settings.
- A runbook explains how to query admin activity, verify forwarding and respond to a failed log pipeline.
- Handover includes a walkthrough with administrators and the security team who will own the logs.
How we support
- Ongoing support is available as a retainer, covering configuration changes and Keycloak upgrades that touch event logging.
- Upgrade checks confirm event settings and the SIEM listener still work after Keycloak upgrades.
- Retainers can include periodic verification that expected login and admin events reach the SIEM.
