keycloak auditing

Auditing in Keycloak: How to Catch Them All

by

Keycloak is a robust open-source Identity and Access Management (IAM) solution that not only manages access but also ensures that all security-related events are monitored and recorded. Auditing is a critical aspect of security and compliance in any system, and Keycloak provides comprehensive tools for this purpose. In this blog post, we’ll explore why auditing is important, and how it can be enabled for both users and administrators in Keycloak.

Why is Auditing Important?

  1. Security Monitoring: Auditing allows organizations to monitor and record user activities and system changes. This helps in detecting potential security breaches or malicious activities by providing a trail of user and system actions.
  2. Compliance: Many industries are subject to regulations that require detailed logging of access and changes to sensitive data. Auditing helps in maintaining logs that can be reviewed to ensure compliance with various standards such as GDPR, HIPAA, or PCI-DSS.
  3. Operational Oversight: Auditing provides administrators with insights into how the system is being used. This includes understanding user behavior, which can help in optimizing system performance and user experience.
  4. Accountability: By maintaining an audit trail, organizations can attribute actions to specific individuals, which enhances accountability among users.

For best practices on auditing, see this post.

Keycloak Auditing

Keycloak supports event logging for both admin and user events, providing detailed insights into operations performed within the system.

By default, all events are fired, and each has its corresponding error event. One must decide which events to track, hence the term “capturing” rather than “enabling.” You can capture them using a custom listener or by utilizing the provided jboss-logging and email event listeners.

JBoss will send the error events to the log file. To send more information, restart the server with the required log level set for the listener.

The email listener will send the events to the affected user by email. The supported events are:

  • Login Error
  • Update Password
  • Update Time-based One-time Password (TOTP)
  • Remove Time-based One-time Password (TOTP)

Here’s how you can “capture” and configure auditing events in Keycloak:

Auditing User Event

User events include logins, logouts, and account management activities by the users. To capture user event logging (The UI may vary for certain versions, but the concept is the same):

  1. Log into the Admin Console: Navigate to your Keycloak admin console.
  2. Go to the Realm Settings: Select the realm for which you want to capture the events.
  3. Access the User Events Settings Tab: Click on Events → User events settings.
  4. Configure Event Settings: Here, you can select Save events to store the events in the database and see them on the Events page (we recommend adding an SPI and forward the events elsewhere for such case. It keeps the DB lean). On that same page, you will see all the events fired for user events.
  5. Set up Event Listeners: Ensure that the jboss-logging listener is used at least. This is the framework that will log the actual events. You can also use your own SPI to handle and send the events somewhere else than just a log file.

Auditing Admin Event

Admin events cover actions performed by administrators, such as creating or deleting users, changing roles, or managing realm settings. To capture admin events:

  1. Access Admin Events Settings: Under the same Events → Admin events settings section in your realm settings, you can find settings related to admin events.
  2. Review Logs: Admin event errors are also logged in the server log if jboss-logging is set up as a listener.

Reviewing and Managing Audit Logs

If you decided to save the events in Keycloak, you will be able to review the logs directly from the Keycloak admin console under Events → User events for user events and Events → Admin events for admin events.

For a more robust log management solution, consider exporting these logs to an external system like ELK (Elasticsearch, Logstash, and Kibana) or Splunk for advanced analysis and real-time monitoring. We will take a look of a common setup in another blog post.

Conclusion

Auditing is a critical feature for maintaining the security, compliance, and operational integrity of any identity management system. In Keycloak, enabling and managing auditing is straightforward and provides deep insights into both user and administrative actions. By effectively utilizing the auditing capabilities of Keycloak, you can enhance your organization security posture and ensure compliance with regulatory requirements, all while maintaining a clear oversight of user activities and system changes. You can find out more about auditing in Keycloak here.

Leave a Comment