Keycloak audit logs help SaaS teams understand who did what, when an action happened, and which account or system performed it. Authentication tells you that someone successfully logged in. It doesn't automatically give you a complete record of what happened after that login.
Imagine a customer reports that an employee's account was removed, an administrator's permissions changed, or access to a sensitive resource was modified. Your application may confirm that the person had an active session, but can your team identify who made the change, when it happened, and whether it was intentional?
This is where audit logging becomes essential. As a SaaS product grows, more people gain access to administrative dashboards, customer data, configuration settings, and internal tools. Without a reliable audit trail, investigating an unexpected change can turn into a frustrating search across application logs, identity systems, and support conversations.
Keycloak provides useful event logging capabilities for authentication activity and administrative operations. Understanding what these events capture, how to configure them, and where their limitations lie helps SaaS teams build a clearer record of activity across their identity infrastructure.
TL;DR
Keycloak audit logs help SaaS teams track authentication activity and administrative changes, including who performed an action, what happened, and when it occurred. To build a useful audit trail, enable user and admin events, configure retention, and centralize logs for easier investigation.
Here are the key things to know:
- User events: Track logins, logouts, failed authentication attempts, and credential changes.
- Admin events: Identify administrative operations such as role assignments, user updates, and configuration changes.
- Event details: Enable Include Representation to capture additional information about administrative requests.
- Centralized logging: Send relevant events to a logging platform to investigate activity across your infrastructure.
- Application-level auditing: Record business actions inside your SaaS because Keycloak doesn't capture every operation performed within your application.
With the right combination of identity events and application audit logs, your team can build a clearer history of activity and investigate security incidents with more confidence.
Authentication Events and Administrative Events: What's the Difference?
Keycloak audit logs cover two important types of activity: events generated by users during authentication and actions performed by administrators through the Keycloak Admin Console or Admin REST API.
Both matter when you're investigating a security issue, but they answer different questions.
User events: What happened during authentication?
User events record activity associated with authentication and account operations. Examples include:
- Successful logins and logout events.
- Failed login attempts caused by incorrect credentials.
- Password updates and credential changes.
- Account registration and profile updates.
- Password reset and email verification attempts.
Keycloak provides different event types for these operations, and administrators can select which ones to save through the User events settings.
These records help your team investigate suspicious sign-in activity, repeated authentication failures, and changes to user credentials.
For example, if a customer reports that someone accessed their account without permission, your team can inspect the user's login history and look for unusual activity. A failed login followed by a successful login from an unfamiliar IP address may provide useful context for the investigation.
User events help establish what happened during authentication, including the event type, timestamp, and available user or client details.
Admin events: Who changed your identity configuration?
Administrative events record operations performed through Keycloak's administrative interfaces. They can help you identify who changed a configuration, which resource was affected, and what operation was performed.
Examples include:
- Creating, updating, or deleting a user.
- Assigning or removing roles.
- Changing client configurations.
- Updating realm settings.
- Modifying groups and identity-related resources.
Consider a situation where a customer suddenly gains administrator permissions. A successful login event won't explain how that happened. An admin event can help your team trace the role assignment back to the administrative operation that changed the user's permissions.
Keycloak also provides an Include Representation option for admin events. When enabled, it records the JSON representation sent through the Admin REST API, giving administrators more detail about the changes made. This can increase database storage usage, so teams should account for the additional data when configuring event retention.
One important detail when investigating admin events is how Keycloak identifies the administrator who performed an operation. The event's authDetails field contains authentication details such as the realm, client, user ID (userId), and IP address. Keycloak records the administrator's user ID, not their name. To identify the person behind the change, your team needs to use that ID to find the corresponding account in the Keycloak Users section.
How to Enable Keycloak Audit Logs
Keycloak supports event logging out of the box, but successful user events and administrative actions are not automatically saved in the Admin Console. You need to enable the event types your team wants to record.
You can configure both from the realm's event settings.
Enable user events
To save authentication and account activity:
- Open the Keycloak Admin Console.
- Select Realm settings.
- Open the Events tab.
- Select User events settings.
- Turn Save events ON.
- Set the event expiration period.
- Use Add saved types to select the additional event types you want to store.
- Save your changes.
Once enabled, open the Events section and select User events to review recorded activity. You can also filter the events to investigate a specific user or event type.
Enable administrative events
To record changes made by administrators:
- Open Realm settings.
- Select Events.
- Open Admin events settings.
- Turn Save events ON.
- Enable Include Representation to store the JSON representation of administrative requests, providing additional details about the changes made.
- Save your changes.
You can then open Events β Admin events to inspect the recorded operations.
One detail deserves attention: enabling admin events records the operations, while enabling Include Representation adds the request representation for more detailed investigation. This additional information can increase database storage requirements, so set an appropriate retention policy and monitor storage usage.
What Should a Useful Audit Log Record?
Collecting events is a good starting point, but a long list of timestamps and event names won't help much when your team needs to investigate an incident. Useful audit records need enough context to explain what happened and connect the action to the person or system responsible.
For a SaaS application, an audit record should capture as many of these details as the event makes available:
- Actor: The user, administrator, or service account responsible for the action.
- Action: The operation performed, such as login, role assignment, account update, or deletion.
- Target: The user, client, group, realm, or resource affected.
- Timestamp: When the operation occurred, with a consistent timezone.
- Result: Whether the operation succeeded or failed.
- Source details: Available context such as the client, IP address, or request information.
For example, imagine an administrator changes a customer's role from viewer to admin. A useful record should help your team identify the administrator who made the change, the affected account, the operation, and its timestamp.
That context makes it possible to answer practical questions during an investigation: Was the change authorized? Did the administrator make it intentionally? Were other accounts modified around the same time?
Keycloak's user and admin events provide identity-related information, while the level of detail available depends on the event and its configuration. Your application can add the business context that identity logs cannot capture on their own.
Centralize Your Keycloak Audit Logs
Keeping audit events inside Keycloak is useful when an administrator needs to inspect a recent login or configuration change. However, as a SaaS product grows, your team may need to investigate activity across several systems at once.
For example, a security incident could involve a suspicious login, a change to a user's permissions, and an unusual request to your application. If each system stores its own records in a separate place, connecting those events takes time.
Centralized logging gives your team one place to collect and analyze this information.
Keycloak supports event listeners that process user and administrative events. Its built-in Logging Event Listener writes error events to the server log at the WARN level and other events at DEBUG. Since DEBUG messages aren't included in server logs by default, teams that need successful events in their logs must configure the appropriate logging levels. Custom event listeners can also forward event data to external systems, allowing teams to integrate Keycloak activity into their existing logging infrastructure.
A typical setup might look like this:
- Keycloak generates a user or administrative event.
- An event listener processes the event.
- The event reaches your centralized logging platform.
- Your team searches, filters, and correlates it with application and infrastructure logs.
- Alerts notify the appropriate people when defined security conditions occur.
Platforms such as Elasticsearch, OpenSearch, and Splunk can help teams search and analyze logs from multiple services. The right destination depends on your existing infrastructure and how your team handles security monitoring.
The main benefit is context. Your engineers can compare a Keycloak role change with application activity around the same timestamp, making it easier to reconstruct what happened during an incident.
Audit Log Retention, Access, and Security
An audit trail is useful only when the records remain available, trustworthy, and accessible to the right people. Logging everything without a retention or access policy can create its own security and operational problems.
Three areas deserve attention.
Set a clear retention period
Keycloak lets administrators configure how long saved event records remain available through the event expiration setting. Choose a retention period that supports your investigation needs and fits your storage capacity.
For longer retention, send relevant records to a centralized logging platform with its own retention policy. This also helps preserve historical activity when older events expire from Keycloak's event store.
Protect audit records from unauthorized changes
Audit logs can contain sensitive information about users, administrators, clients, and infrastructure. Access to these records should be restricted to people who need them for security investigations or operational work.
Your logging platform should also have appropriate access controls and safeguards against unauthorized deletion or modification. A record that an administrator can quietly alter or remove provides limited value during a security investigation.
Avoid collecting unnecessary sensitive data
More detail does not always mean a better audit trail. Enabling Include Representation for admin events can capture JSON request details, which may increase storage usage and expose information that needs careful handling.
Review the information your team collects, restrict access, and apply appropriate retention rules. Your goal is to preserve enough context to investigate activity without retaining unnecessary sensitive data.
Where Keycloak Audit Logs End and Application Auditing Begins
Keycloak can tell you about authentication and administrative operations within your identity infrastructure. However, it cannot automatically explain every action a user performs inside your SaaS product.
This distinction also matters during SaaS user offboarding, where teams need to track account deactivation, session termination, and permission removal through a reliable user deprovisioning process.
Imagine a customer support agent logs in successfully, opens a customer account, changes its billing details, and exports a report. Keycloak can record the authentication activity, but the business operations happen inside your application.
Your application needs its own audit trail for actions such as:
- Creating, updating, or deleting customer records.
- Changing subscription plans or billing details.
- Exporting or downloading sensitive information.
- Inviting users or changing their application permissions.
- Updating organization settings.
- Approving or rejecting important business operations.
These records should identify the authenticated user, the action, the affected resource, and the timestamp. For sensitive operations, recording the previous and updated values can also help explain exactly what changed.
This is where the two audit layers work together. Keycloak provides identity-related activity, while your application records business-level actions. Combining both gives your team a more complete picture of what happened across a customer account.
Managing Keycloak Audit Logging with Skycloak
Running Keycloak in production means keeping your identity infrastructure reliable while maintaining control over how users, administrators, and applications access your SaaS platform. Audit logging is an important part of that responsibility. Your team needs visibility into authentication activity, administrative changes, and the configuration decisions that affect access across your environment.
Skycloak provides managed Keycloak hosting for SaaS teams that want the flexibility and control of Keycloak without having to operate the underlying hosting infrastructure themselves.
Skycloak includes:
- Unlimited users on all plans: There are no user-count restrictions as your SaaS grows.
- Full Keycloak admin access: Your team retains access to Keycloak's administrative features and configuration settings.
- Four hosting regions: Deploy in the US, EU, Canada, or Australia.
- Realm exports: Export your realm configuration for backup, migration, or other operational needs.
- 21-day free trial: Try Skycloak without a credit card.
Audit Logging Features by Plan
Skycloak's audit logging features depend on the selected plan:
- User events: Included from the Launch plan onward.
- Admin events: Included from the Business plan onward, with 30 days of retention on Business and 90 days on Enterprise.
- SIEM integration: Available on Enterprise, allowing teams to send audit events to external platforms such as Splunk.
These plan differences allow SaaS teams to choose the level of audit visibility and event retention that fits their requirements. For a complete breakdown, visit Skycloak's audit logs feature page.
If you're looking for managed Keycloak hosting with the flexibility to manage your own identity configuration, explore Skycloak's hosting options.
You can also explore Skycloak's pricing plans to compare the available options and choose the setup that fits your SaaS requirements.
Frequently Asked Questions
Does Keycloak have built-in audit logging?
Yes. Keycloak includes built-in event logging for user activity and administrative operations. User events cover activities such as logins, logouts, and credential changes, while admin events record operations performed through the Admin Console and Admin REST API. You can enable both from Realm settings β Events.
Are Keycloak audit logs enabled by default?
Keycloak does not automatically save all user and administrative events in its event store. Administrators need to enable Save events in the user event settings and Save events in the admin event settings. You can also configure which user event types to retain and how long to store them.
Can Keycloak show who changed a user's roles?
Yes. Keycloak records administrative operations such as role assignments and user updates through admin events. Enabling Include Representation adds the JSON representation of the administrative request, providing more detail about the operation. This helps administrators investigate permission changes and identify the account responsible for the action.
Can Keycloak send audit logs to an external monitoring platform?
Yes. Keycloak supports event listeners that can process user and administrative events. Its built-in logging listener can write event information to server logs, while custom event listeners can integrate with external logging and monitoring systems. This allows teams to bring identity activity into a centralized environment for searching, analysis, and alerting.
Can I use Skycloak to manage my Keycloak infrastructure?
Yes. Skycloak provides managed Keycloak hosting with unlimited users on all plans and full administrative access to Keycloak. Audit logging features depend on the selected plan: user events are included from Launch onward, admin events from Business onward with 30 days of retention on Business and 90 days on Enterprise, and SIEM integration is available on Enterprise. Skycloak also offers hosting regions in the US, EU, Canada, and Australia, supports realm exports, and includes a 21-day free trial without a credit card.
Final Thoughts
A successful login tells you that authentication worked. When something goes wrong, your team needs more context: who made the change, which account was affected, when the operation happened, and what actually changed.
Keycloak audit logs give SaaS teams a practical way to track authentication activity and administrative operations across their identity infrastructure. Enabling the right events, configuring retention, and centralizing relevant records can make security investigations much easier.
Your application also has a responsibility to record business-level activity. When identity events and application audit trails work together, your team gets a clearer view of what happens across customer accounts and administrative workflows.
As your SaaS grows, that visibility becomes an important part of maintaining accountability, investigating incidents, and protecting customer data.
| Thanks for reading! ππ» I hope you found this useful β Please react and follow for more π Made with π by Hadil Ben Abdallah |
  
|
|---|
Top comments (20)
This is an important distinction, especially for SaaS teams. A successful login only tells part of the story. Knowing who changed a role, modified an account, or accessed sensitive resources is just as important when investigating security issues. I also like that you highlighted the gap between Keycloak events and application-level auditing. Both layers need to work together to give teams a reliable picture of what's happening.
Thanks! That's exactly the point. Authentication is only one part of the security world. When something goes wrong, having a clear trail of both identity-related events and actions inside the application can save teams a lot of time and guesswork.
Glad you found that distinction valuable!
The two-layer point is the part most teams miss. Keycloak can tell you who logged in, but not who changed an invoice.
On the app side, if youβre on .NET, an EF Core SaveChanges interceptor is a clean way to do it. It sees every changed entity with its original and current values, so you get before and after auditing without adding code to every service.
One thing Iβd add on integrity: give the appβs database user INSERT only on the audit table, no UPDATE or DELETE. Then even a bug or a compromised app canβt quietly rewrite history.
I like the point about restricting database permissions on the audit table. Even if you're capturing all the right events, you still need to make sure those records can't be quietly changed or deleted. And the EF Core interceptor is a practical approach for .NET teams. It makes application-level auditing much easier to maintain without spreading that logic across every service.
Thanks Hadil. For stricter setups, some teams also ship audit events to a separate store, so even a database admin canβt change them. For most apps, INSERT only already closes the biggest gap.
The detail about Keycloak recording the administrator's user ID instead of a name caught my attention β that is the kind of thing that wastes an hour in an incident if you do not know it in advance. Good practical write-up.
Exactly! It's one of those small details that can save you quite a bit of time when you're investigating an incident. Having the user ID is useful, but knowing that you still need to look up the corresponding account to identify the administrator makes the whole process more clear.
Exactly, that lookup step is the part people skip. The user ID alone does not name anyone until you match it in the Users section, so during an incident that extra step is where the time goes. Good point about keeping the admin events and the lookup together.
Absolutely! And that's exactly why having both pieces of information readily accessible makes such a difference. During an incident, nobody wants to spend extra time trying to figure out who an ID belongs to. It's a small detail, but it can make the investigation much smoother.
The before/after values part is where it gets fun in the EU. Once the audit log keeps the old and new email or address, it's a second copy of personal data with its own retention, and every GDPR deletion request now has to answer what happens to the log. Do you redact values after some time, or keep the full trail and treat the log as personal data too?
That's an important point, especially for SaaS products handling customer data in the EU. It's easy to focus on capturing enough information for investigations and overlook the privacy implications of keeping those records. I think audit logs need their own retention and data protection policies, with careful consideration of what information actually needs to be preserved. Keeping a useful history shouldn't mean holding on to every piece of personal data indefinitely.
Agreed. What I see most often is that retention gets decided for the main database and the audit log just inherits "forever" because nobody owns it. Thanks for the article, it's a good checklist to go through.
Authentication answering "who got in" is not the same as answering "who removed that account" or "who changed that role." Those are different records, and customers notice the gap the first time something goes wrong.
A useful audit line names the actor, the action, the target, and enough before/after detail that a support person can reconstruct the event without reading raw logs.
At Ascendra Ventures we put that trail into the acceptance criteria for SaaS and admin builds. Login is table stakes. Prove-who-did-what is what makes the product operable after launch.
Do you store that trail as first-class events, or do you reconstruct it from server logs when a ticket lands?
I completely agree that reconstructing what happened from scattered server logs after a support ticket arrives can quickly become a headache. Having audit events as a first-class part of the application makes a difference, especially when you need to give customers clear answers. Building this into acceptance criteria from the start is a great practice.
The two-layer point is the one most teams miss β Keycloak tells you who logged in, not who changed an invoice. umerfarooqofficial's EF Core interceptor is the neat version of that on .NET, it sees original and current values without code in every service. Do you run the audit table permissions locked down too, or is that the part teams usually leave for later?
I'd definitely put audit table permissions on the checklist from the beginning. It's easy to focus on capturing every change and forget about protecting the records themselves. Restricting updates and deletes helps preserve the integrity of the audit trail, which is just as important when you're investigating an incident.
The distinction between "login succeeded" and "who changed the permission after that" is the part most early SaaS dashboards skip. Curious how noisy Keycloak's audit stream got once you had more than a handful of admin users β did you filter by realm/client early, or drown first?
Good question! I think filtering becomes important pretty quickly as the number of users and administrative actions grows. Filtering by event type, user, and other available details can make investigations much easier. I'd also recommend centralizing the logs early, so teams can search and correlate activity without having to dig through everything manually. It's much easier to build that habit before the audit stream gets overwhelming!
the line that a successful login event will not explain how a customer got admin rights is the useful framing, since the role assignment lives in admin events and nobody looks there first. one gap i would flag with Include Representation: it stores the request payload, so you want to scrub secrets and personal data before those events land in a central log. also the app level audit trail matters more than people expect, because keycloak never sees the business action. where do you draw the line on retention, keep admin events longer than login events?
That's a good catch about Include Representation! Capturing the request payload gives you more context, but it also means being careful about what gets stored and forwarded to external logging platforms. Scrubbing sensitive information before it reaches centralized logs is definitely worth considering.
As for retention, I think it makes sense to define different policies based on the type of event and its investigation value. Administrative changes may need a longer history than routine login activity, depending on the application's security and compliance requirements. The important thing is to make those decisions deliberately, with privacy and storage considerations in mind.