From 4cccb5ca1011f6b8bc619b6f887ea26f54626652 Mon Sep 17 00:00:00 2001 From: Stan Silvert Date: Mon, 6 Jun 2016 16:22:28 -0400 Subject: [PATCH 1/2] Minor updates for events chapter. --- topics/events.adoc | 2 +- topics/events/admin.adoc | 2 +- topics/events/login.adoc | 50 ++++++++++++++++++++-------------------- 3 files changed, 27 insertions(+), 27 deletions(-) diff --git a/topics/events.adoc b/topics/events.adoc index 13140a778b..30dc418b85 100755 --- a/topics/events.adoc +++ b/topics/events.adoc @@ -2,6 +2,6 @@ {{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 +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. diff --git a/topics/events/admin.adoc b/topics/events/admin.adoc index de76b6c09e..1ba6d12088 100644 --- a/topics/events/admin.adoc +++ b/topics/events/admin.adoc @@ -3,7 +3,7 @@ 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. +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. diff --git a/topics/events/login.adoc b/topics/events/login.adoc index 62f02cee24..e09b0bda7d 100644 --- a/topics/events/login.adoc +++ b/topics/events/login.adoc @@ -1,9 +1,9 @@ === 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 +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 @@ -15,16 +15,16 @@ To start storing events you'll need to turn the `Save Events` switch to on under 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. +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 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 +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 @@ -37,31 +37,31 @@ In this screenshot, we're filtering only `Login` events. Clicking the `Update` 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 +* 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 +* 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. ==== 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. +listeners that come with {{book.project.name}}: 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: @@ -76,8 +76,8 @@ Here's an example log message: ---- 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. +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 users account when an event occurs. The Email Event Listener only supports the following events at the moment: From a96793cb459663bbdfb9d8d6406e7c32f8abed9e Mon Sep 17 00:00:00 2001 From: Stan Silvert Date: Mon, 6 Jun 2016 16:24:27 -0400 Subject: [PATCH 2/2] More minor updates to events chapter. --- topics/events/admin.adoc | 3 +-- topics/events/login.adoc | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/topics/events/admin.adoc b/topics/events/admin.adoc index 1ba6d12088..c0a734c3ab 100644 --- a/topics/events/admin.adoc +++ b/topics/events/admin.adoc @@ -15,8 +15,7 @@ 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 +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. diff --git a/topics/events/login.adoc b/topics/events/login.adoc index e09b0bda7d..c048fb1406 100644 --- a/topics/events/login.adoc +++ b/topics/events/login.adoc @@ -79,7 +79,7 @@ This logging is very useful if you want to use a tool like Fail2Ban to detect if 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 users account when an event occurs. +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