JBoss.org Community Documentation

- Prev
- Next

## Chapter 17. Audit

Keycloak provides an Audit SPI that makes it possible to register listeners for events in the system. There are two interfaces that can be implemented, the first is a pure listener, the second is a provider which listens for events as well as providing a query over persisted events. If a realm has a audit provider registered it's possible to view events for the realm through the admin console and account management.

## 17.1. Events

Login events:

- Login - A user has logged in
- Register - A user has registered
- Logout - A user has logged out
- Code to Token - An application/client has exchanged a code for a token
- Refresh Token - An application/client has refreshed a token

Account events

- Social Link - An account has been linked to a social provider
- Remove Social Link - A social provider has been removed from an account
- Update Email - The email address for an account has changed
- Update Profile - The profile for an account has changed
- Send Password Reset - A password reset email has been sent
- Update Password - The password for an account has changed
- Update TOTP - The TOTP settings for an account has changed
- Remove TOTP - TOTP has been removed from an account
- Send Verify Email - A email verification email has been sent
- Verify Email - The email address for an account has been verified

For all events there is a corresponding error event.

## 17.2. Audit Listener

Keycloak comes with an Email Audit Listener and a JBogg Logging Audit Listener. The Email Audit Listener sends an email to the users account when an event occurs. The JBoss Logging Audit Listener writes to a log file when an events occurs.

The Email Audit Listener only supports the following events at the moment:

- Login Error
- Update Password
- Update TOTP
- Remove TOTP

You can exclude one or more events by editing `standalone/configuration/keycloak-server.json` and adding for example:

    "audit-listener": {
        "email": {
            "exclude-events": [ "UPDATE_TOTP", "REMOVE_TOTP" ]
        }
    }

## 17.3. Audit Provider

Audit Providers listen for events and is expected to persist the events to make it possible to query for them later. This is used by the admin console and account management to view events. Keycloak includes providers to persist audit events to JPA and Mongo. For production you will most likely want to use a separate database for audit events. You may even want to use a RDBMS for your model, and Mongo for your audit.

You can specify events to include or exclude by editing `standalone/configuration/keycloak-server.json`, and adding for example:

    "audit": {
        "jpa": {
            "exclude-events": [ "LOGIN", "REFRESH_TOKEN", "CODE_TO_TOKEN" ]
        }
    }

## 17.4. Configure Audit Settings for Realm

To enable audit for a realm you firstly need to make sure you have a audit provider registered for Keycloak. By default the JPA audit provider is registered. Once you've done that open the admin console, select the realm you're configuring, select `Audit`. Then click on `Config`. You can enable audit for your realm by toggling `Enabled` to ON. You can also set an expiration on audit events. This will deleted events from the database that are older than the specified time.

To configure listeners for a realm on the same page as above add one or more audit listeners to the `Audit Listeners` select box. This will allow you to enable any registered Audit Listeners with the realm.

- PrevChapter 16. Admin REST API
- Top of page
- Front page
- NextChapter 18. Authentication SPI