events

SUMMARY.adoc

@@ -85,6 +85,8 @@
  .. link:topics/user-federation/ldap.adoc[LDAP/AD Integration]
  .. link:topics/user-federation/custom.adoc[Custom Providers]
  . link:topics/events.adoc[Auditing and Events]
+ .. link:topics/events/login.adoc[Login Events]
+ .. link:topics/events/admin.adoc[Admin Events]
  . link:topics/export-import.adoc[Export and Import]
  . link:topics/account.adoc[User Account Service]
  . link:topics/security-vulnerabilities.adoc[Security Vulnerabilities]

topics/events.adoc

@@ -1,84 +1,7 @@
-= Auditing and Events
+== Auditing and Events
 
-Keycloak provides an Events SPI that makes it possible to register listeners for user related events, for example user logins.
-There are two interfaces that can be implemented, the first is a pure listener, the second is a events store which listens for events, but is also required to store events.
-An events store provides a way for the admin and account management consoles to view events. 
+{{book.project.name}} 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
+in which plugins can listen for these events and perform some action.  Built in ones include a simple log file and the ability
+to send an email if an event occurs.
 
-== 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 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. 
-
-== Event Listener
-
-Keycloak comes with an Email Event Listener and a JBoss Logging Event Listener.
-The Email Event Listener sends an email to the users account when an event occurs.
-The JBoss Logging Event Listener writes to a log file when an events occurs. 
-
-The Email Event 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: 
-
-[source]
-----
-"eventsListener": {
-    "email": {
-        "exclude-events": [ "UPDATE_TOTP", "REMOVE_TOTP" ]
-    }
-}
-----        
-
-== Event Store
-
-Event Store 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 events to JPA and Mongo. 
-
-You can specify events to include or exclude by editing `standalone/configuration/keycloak-server.json`, and adding for example: 
-
-[source]
-----
-"eventsStore": {
-    "jpa": {
-        "exclude-events": [ "LOGIN", "REFRESH_TOKEN", "CODE_TO_TOKEN" ]
-    }
-}
-----        
-
-== Configure Events Settings for Realm
-
-To enable persisting of events for a realm you first need to make sure you have a event store provider registered for Keycloak.
-By default the JPA event store provider is registered.
-Once you've done that open the admin console, select the realm you're configuring, select `Events`.
-Then click on `Config`.
-You can enable storing events for your realm by toggling `Save Events` to ON.
-You can also set an expiration on events.
-This will periodically delete 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 event listeners to the `Listeners` select box.
-This will allow you to enable any registered event listeners with the realm. 

topics/events/admin.adoc

@@ -0,0 +1,37 @@
+
+=== 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 {{book.project.name}} REST interface.  {{book.project.name}}
+audits the admin APIs be storing these REST invocations.  These REST invocations 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
+image:../../{{book.images}}/login-events-config.png[]
+
+In the `Admin Events Settings` section, turn on the `Save Events` switch.
+
+.Admin Event Configuration
+image:../../{{book.images}}/admin-events-settings.png[]
+
+The `Include Representation` switch will include any JSON document that is sent to the admin REST API when they are being
+invoked upon.  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
+image:../../{{book.images}}/admin-events.png[]
+
+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
+image:../../{{book.images}}/admin-events-representation.png[]
+
+You can also filter for the events you are interested in by clicking the `Filter` button.
+
+.Admin Event Filter
+image:../../{{book.images}}/admin-events-filter.png[]
+
+

topics/events/login.adoc

@@ -0,0 +1,107 @@
+
+=== Login Events
+
+Login events occur for things like when a user logs in successfully, when somebody enters in a bad password, when a user account
+is updated.  Really every single event that happens to a user can be recorded and viewed.  By default, no events are stored
+or are viewable 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
+image:../../{{book.images}}/login-events-config.png[]
+
+To start storing events you'll need to turn the `Save Events` switch to on under the `Login Events Settings`.
+
+.Save Events
+image:../../{{book.images}}/login-events-settings.png[]
+
+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` file allows you to specify how long you want
+to keep events stored for.  Once you've enabled storage of login events and decided on you settings, don't forget to click
+the `Save` button on the button of this page.
+
+To view events, go to the `Login Events` tab.
+
+.Login Events
+image:../../{{book.images}}/login-events.png[]
+
+As you can see, there's a lot of information stored and, if you are storing every event, there's 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
+image:../../{{book.images}}/login-events-filter.png[]
+
+In this screenshot, we're filtering only `Login` events.  Clicking the `Update` button runs the filter.
+
+
+==== 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 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.
+
+==== Event Listener
+
+Event listeners listen for events and perform an action based on that event.  There are two built in
+ones that come with {{book.project.name}}: Logging Event Listener and an 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, feed this information
+into Fail2Ban so that it do what it does to prevent attacks.
+
+The Email Event Listener sends an email to the users 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 `keycloak-server.json` that comes with your distribution and adding for example:
+
+[source]
+----
+"eventsListener": {
+    "email": {
+        "exclude-events": [ "UPDATE_TOTP", "REMOVE_TOTP" ]
+    }
+}
+----
+
+See the link:{{book.installguide.link}}[book.installguide.name}}] for more details on where the `keycloak-server.json` file lives.
+
+
+