Chapter 14. Configuring auditing to track events

Red Hat Single Sign-On includes a suite of auditing capabilities. You can record every login and administrator action and review those actions in the Admin Console. Red Hat Single Sign-On also includes a Listener SPI that listens for events and can trigger actions. Examples of built-in listeners include log files and sending emails if an event occurs.

14.1. Login events

You can record and view every event that affects users. Red Hat Single Sign-On triggers login events for actions such as successful user login, a user entering an incorrect password, or a user account updating. By default, Red Hat Single Sign-On does not store or display events in the Admin Console. Only the error events are logged to the Admin Console and the server’s log file.

To start saving events, enable storage.

Procedure

  1. Click Events in the menu.
  2. Click the Config tab.

    Event Configuration

    Event Configuration

  3. Toggle Save Events to ON.

    Save Events

    Save Events

  4. Specify the events to store in the Saved Types field.

You can click the Clear events button to delete all events.

Specify the length of time to store events in the Expiration field. When you enable login event storage and enable your settings, click the Save button.

Click the Login Events tab to view the events.

Login Events

Login Events

You can filter events using the Filter button.

Login Events Filter

Login Events Filter

In this example, we filter only Login events. Click Update to run the filter.

14.1.1. Event types

Login events:

EventDescription

Login

A user logs in.

Register

A user registers.

Logout

A user logs out.

Code to Token

An application, or client, exchanges a code for a token.

Refresh Token

An application, or client, refreshes a token.

Account events:

EventDescription

Social Link

A user account links to a social media provider.

Remove Social Link

The link from a social media account to a user account severs.

Update Email

An email address for an account changes.

Update Profile

A profile for an account changes.

Send Password Reset

Red Hat Single Sign-On sends a password reset email.

Update Password

The password for an account changes.

Update TOTP

The Time-based One-time Password (TOTP) settings for an account changes.

Remove TOTP

Red Hat Single Sign-On removes TOTP from an account.

Send Verify Email

Red Hat Single Sign-On sends an email verification email.

Verify Email

Red Hat Single Sign-On verifies the email address for an account.

Each event has a corresponding error event.

14.1.2. Event listener

Event listeners listen for events and perform actions based on that event. Red Hat Single Sign-On includes two built-in listeners, the Logging Event Listener and Email Event Listener.

14.1.2.1. The logging event listener

When the Logging Event Listener is enabled, this listener writes to a log file when an error event occurs.

An example log message from a Logging Event Listener:

11:36:09,965 WARN  [org.keycloak.events] (default task-51) type=LOGIN_ERROR, realmId=master,
                    clientId=myapp,
                    userId=19aeb848-96fc-44f6-b0a3-59a17570d374, ipAddress=127.0.0.1,
                    error=invalid_user_credentials, auth_method=openid-connect, auth_type=code,
                    redirect_uri=http://localhost:8180/myapp,
                    code_id=b669da14-cdbb-41d0-b055-0810a0334607, username=admin

You can use the Logging Event Listener to protect against hacker bot attacks:

  1. Parse the log file for the LOGIN_ERROR event.
  2. Extract the IP Address of the failed login event.
  3. Send the IP address to an intrusion prevention software framework tool.

The Logging Event Listener logs events to the org.keycloak.events log category. Red Hat Single Sign-On does not include debug log events in server logs, by default.

To include debug log events in server logs:

  1. Edit the standalone.xml file.
  2. Change the log level used by the Logging Event listener.

Alternately, you can configure the log level for org.keycloak.events.

For example, to change the log level add the following:

<subsystem xmlns="urn:jboss:domain:logging:...">
    ...
    <logger category="org.keycloak.events">
        <level name="DEBUG"/>
    </logger>
</subsystem>

To change the log level used by the Logging Event listener, add the following:

<subsystem xmlns="urn:jboss:domain:keycloak-server:...">
    ...
    <spi name="eventsListener">
      <provider name="jboss-logging" enabled="true">
        <properties>
          <property name="success-level" value="info"/>
          <property name="error-level" value="error"/>
        </properties>
      </provider>
    </spi>
</subsystem>

The valid values for log levels are debug, info, warn, error, and fatal.

14.1.2.2. The Email Event Listener

The Email Event Listener sends an email to the user’s account when an event occurs and supports the following events:

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

Procedure

To enable the Email Listener:

  1. Click Events from the menu.
  2. Click the Config tab.
  3. Click the Event Listeners field.
  4. Select email.

You can exclude events by editing the standalone.xml, standalone-ha.xml, or domain.xml configuration files included in your distribution. For example:

<spi name="eventsListener">
  <provider name="email" enabled="true">
    <properties>
      <property name="exclude-events" value="[&quot;UPDATE_TOTP&quot;,&quot;REMOVE_TOTP&quot;]"/>
    </properties>
  </provider>
</spi>

You can set a maximum length of the Event detail in the database by editing the standalone.xml, standalone-ha.xml, or domain.xml configuration files. This setting is useful if a field (for example, redirect_uri) is long. For example:

<spi name="eventsStore">
    <provider name="jpa" enabled="true">
        <properties>
            <property name="max-detail-length" value="1000"/>
        </properties>
    </provider>
</spi>

See the Server Installation and Configuration Guide for more details on the location of the standalone.xml, standalone-ha.xml, or domain.xml files.

14.2. Admin events

You can record all actions that are performed by an administrator in the Admin Console. The Admin Console performs administrative actions by invoking the Red Hat Single Sign-On REST interface and Red Hat Single Sign-On audits these REST invocations. You can view the resulting events in the Admin Console.

To enable auditing of Admin actions:

Procedure

  1. Click Events in the menu.
  2. Click the Config tab.

    Event configuration

    Event Configuration

  3. Toggle Save Events to ON in the Admin Events Settings section. Red Hat Single Sign-On displays the Include Representation switch.

    Admin event configuration

    Admin Event Configuration

  4. Toggle Include Representation to ON.

The Include Representation switch includes JSON documents sent through the admin REST API so you can view the administrators actions. To clear the database of stored actions, click Clear admin events.

To view the admin events, click the Admin Events tab.

Admin events

Admin Events

If the Details column has a Representation button, click the Representation button to view the JSON Red Hat Single Sign-On sent with the operation.

Admin representation

Admin Representation

Click Filter to view specific events.

Admin event filter

Admin Event Filter