diff --git a/SUMMARY.adoc b/SUMMARY.adoc index 1756c66028..fbd0d546ab 100755 --- a/SUMMARY.adoc +++ b/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] diff --git a/keycloak-images/admin-events-filter.png b/keycloak-images/admin-events-filter.png new file mode 100644 index 0000000000..202b272c0f Binary files /dev/null and b/keycloak-images/admin-events-filter.png differ diff --git a/keycloak-images/admin-events-representation.png b/keycloak-images/admin-events-representation.png new file mode 100644 index 0000000000..b8835f6bcf Binary files /dev/null and b/keycloak-images/admin-events-representation.png differ diff --git a/keycloak-images/admin-events-settings.png b/keycloak-images/admin-events-settings.png new file mode 100644 index 0000000000..7a61526ec9 Binary files /dev/null and b/keycloak-images/admin-events-settings.png differ diff --git a/keycloak-images/admin-events.png b/keycloak-images/admin-events.png new file mode 100644 index 0000000000..33b9e1ef3a Binary files /dev/null and b/keycloak-images/admin-events.png differ diff --git a/keycloak-images/login-events-config.png b/keycloak-images/login-events-config.png new file mode 100644 index 0000000000..193e94f98c Binary files /dev/null and b/keycloak-images/login-events-config.png differ diff --git a/keycloak-images/login-events-filter.png b/keycloak-images/login-events-filter.png new file mode 100644 index 0000000000..839f832134 Binary files /dev/null and b/keycloak-images/login-events-filter.png differ diff --git a/keycloak-images/login-events-settings.png b/keycloak-images/login-events-settings.png new file mode 100644 index 0000000000..464fe4f8e0 Binary files /dev/null and b/keycloak-images/login-events-settings.png differ diff --git a/keycloak-images/login-events.png b/keycloak-images/login-events.png new file mode 100644 index 0000000000..e4d1eddfd4 Binary files /dev/null and b/keycloak-images/login-events.png differ diff --git a/rhsso-images/admin-events-filter.png b/rhsso-images/admin-events-filter.png new file mode 100644 index 0000000000..a18b9b658a Binary files /dev/null and b/rhsso-images/admin-events-filter.png differ diff --git a/rhsso-images/admin-events-representation.png b/rhsso-images/admin-events-representation.png new file mode 100644 index 0000000000..4faa98802e Binary files /dev/null and b/rhsso-images/admin-events-representation.png differ diff --git a/rhsso-images/admin-events-settings.png b/rhsso-images/admin-events-settings.png new file mode 100644 index 0000000000..7829697ffa Binary files /dev/null and b/rhsso-images/admin-events-settings.png differ diff --git a/rhsso-images/admin-events.png b/rhsso-images/admin-events.png new file mode 100644 index 0000000000..0605734664 Binary files /dev/null and b/rhsso-images/admin-events.png differ diff --git a/rhsso-images/login-events-config.png b/rhsso-images/login-events-config.png new file mode 100644 index 0000000000..f70520854b Binary files /dev/null and b/rhsso-images/login-events-config.png differ diff --git a/rhsso-images/login-events-filter.png b/rhsso-images/login-events-filter.png new file mode 100644 index 0000000000..43255677d5 Binary files /dev/null and b/rhsso-images/login-events-filter.png differ diff --git a/rhsso-images/login-events-settings.png b/rhsso-images/login-events-settings.png new file mode 100644 index 0000000000..4b7b6894cf Binary files /dev/null and b/rhsso-images/login-events-settings.png differ diff --git a/rhsso-images/login-events.png b/rhsso-images/login-events.png new file mode 100644 index 0000000000..9d0435cbf6 Binary files /dev/null and b/rhsso-images/login-events.png differ diff --git a/topics/events.adoc b/topics/events.adoc index 35cea88fbc..13140a778b 100755 --- a/topics/events.adoc +++ b/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. diff --git a/topics/events/admin.adoc b/topics/events/admin.adoc new file mode 100644 index 0000000000..de76b6c09e --- /dev/null +++ b/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[] + + diff --git a/topics/events/login.adoc b/topics/events/login.adoc new file mode 100644 index 0000000000..9329fef7a1 --- /dev/null +++ b/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. + + +