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 Click Events in the menu. Click the Config tab. Event Configuration Toggle Save Events to ON . Save Events 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 You can filter events using the Filter button. Login Events Filter In this example, we filter only Login events. Click Update to run the filter. 14.1.1. Event types Login events: Event Description 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: Event Description 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: You can use the Logging Event Listener to protect against hacker bot attacks: Parse the log file for the LOGIN_ERROR event. Extract the IP Address of the failed login event. 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: Edit the standalone.xml file. 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: Click Events from the menu. Click the Config tab. Click the Event Listeners field. 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 Click Events in the menu. Click the Config tab. Event configuration Toggle Save Events to ON in the Admin Events Settings section. Red Hat Single Sign-On displays the Include Representation switch. Admin event configuration 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 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 Click Filter to view specific events. Admin event filter

Commands:
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
<subsystem xmlns="urn:jboss:domain:logging:..."> <logger category="org.keycloak.events"> <level name="DEBUG"/> </logger> </subsystem>
<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>
<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>
<spi name="eventsStore"> <provider name="jpa" enabled="true"> <properties> <property name="max-detail-length" value="1000"/> </properties> </provider> </spi>