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
To start storing events you’ll need to turn the
Save Events switch to on under the
Login Events Settings.
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.
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 - 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.
- 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 Logging Event Listener logs events to the
org.keycloak.events logger category. By default debug log events are not included in server logs.
To include debug log events in server logs, edit the
standalone.xml file and change the log level used by the Logging Event listener. Alternately, you can configure the log level for
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>
Valid values for the log levels are
The Email Event Listener sends an email to the user’s account when an event occurs.
Currently, the Email Event Listener supports the following events:
- 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
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>
You can also set up a maximum length of the Event detail stored in the database by editing
domain.xml. This setting can be useful in case some field (e.g. redirect_uri) is very long. Here is an example of defining the maximum length.:
<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 where the
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
Admin Events Settings section, turn on the
Save Events switch.
Admin Event Configuration
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.
Details column has a
Representation box, you can click on that to view the JSON that was sent with that operation.
You can also filter for the events you are interested in by clicking the
Admin Event Filter