Chapter 15. Auditing and Events
Red Hat Single Sign-On provides a rich set of auditing capabilities. Every single login action can be recorded and stored in the database and reviewed in the Admin Console. All admin actions can also be recorded and reviewed. There is also a Listener SPI with which plugins can listen for these events and perform some action. Built-in listeners include a simple log file and the ability to send an email if an event occurs.
15.1. Login Events
Login events occur for things like when a user logs in successfully, when somebody enters in a bad password, or when a user account is updated. Every single event that happens to a user can be recorded and viewed. By default, no events are stored or viewed in the Admin Console. Only error events are logged to the console and the server’s log file. To start persisting you’ll need to enable storage. Go to the Events left menu item and select the Config tab.
Event Configuration
To start storing events you’ll need to turn the Save Events switch to on under the Login Events Settings.
Save Events
The Saved Types field allows you to specify which event types you want to store in the event store. The Clear events button allows you to delete all the events in the database. The Expiration field allows you to specify how long you want to keep events stored. Once you’ve enabled storage of login events and decided on your settings, don’t forget to click the Save button on the bottom of this page.
To view events, go to the Login Events tab.
Login Events
As you can see, there’s a lot of information stored and, if you are storing every event, there are a lot of events stored for each login action. The Filter button on this page allows you to filter which events you are actually interested in.
Login Event Filter
In this screenshot, we’re filtering only Login events. Clicking the Update button runs the filter.
15.1.1. Event Types
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 have changed.
- Remove TOTP - TOTP has been removed from an account.
- Send Verify Email - An 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.
15.1.2. Event Listener
Event listeners listen for events and perform an action based on that event. There are two built-in listeners that come with Red Hat Single Sign-On: Logging Event Listener and Email Event Listener.
The Logging Event Listener writes to a log file whenever an error event occurs and is enabled by default. Here’s an example log message:
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
This logging is very useful if you want to use a tool like Fail2Ban to detect if there is a hacker bot somewhere that is trying to guess user passwords. You can parse the log file for LOGIN_ERROR and pull out the IP Address. Then feed this information into Fail2Ban so that it can help prevent attacks.
The Email Event Listener sends an email to the user’s account when an event occurs. The Email Event Listener only supports the following events at the moment:
- Login Error
- Update Password
- Update TOTP
- Remove TOTP
To enable the Email Listener go to the Config tab and click on the Event Listeners field. This will show a drop down list box where you can select email.
You can exclude one or more events by editing the standalone.xml, standalone-ha.xml, or domain.xml that comes with your distribution and adding for example:
<spi name="eventsListener">
<provider name="email" enabled="true">
<properties>
<property name="exclude-events" value="["UPDATE_TOTP","REMOVE_TOTP"]"/>
</properties>
</provider>
</spi>
See the Server Installation and Configuration Guide for more details on where the standalone.xml, standalone-ha.xml, or domain.xml file lives.
15.2. Admin Events
Any action an admin performs within the admin console can be recorded for auditing purposes. The Admin Console performs administrative functions by invoking on the Red Hat Single Sign-On REST interface. Red Hat Single Sign-On audits these REST invocations. The resulting events can then be viewed in the Admin Console.
To enable auditing of Admin actions, go to the Events left menu item and select the Config tab.
Event Configuration
In the Admin Events Settings section, turn on the Save Events switch.
Admin Event Configuration
The Include Representation switch will include any JSON document that is sent through the admin REST API. This allows you to view exactly what an admin has done, but can lead to a lot of information stored in the database. The Clear admin events button allows you to wipe out the current information stored.
To view the admin events go to the Admin Events tab.
Admin Events
If the Details column has a Representation box, you can click on that to view the JSON that was sent with that operation.
Admin Representation
You can also filter for the events you are interested in by clicking the Filter button.
Admin Event Filter
