libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases Packages Activity Actions

Merge pull request #26 from ssilvert/events-chapter

Browse source 
Minor updates for events chapter.
This commit is contained in:
Bill Burke 2016-06-07 12:02:50 -04:00
commit 93cc13c87b
3 changed files with 29 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
topics/events.adoc
View file

@ -3,6 +3,6 @@
{{book.project.name}} provides a rich set of auditing capabilities. Every single login action can be recorded and stored in {{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 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. to send an email if an event occurs.

5
topics/events/admin.adoc
View file

@ -3,7 +3,7 @@
Any action an admin performs within the admin console can be recorded for auditing purposes. 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}} 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. To enable auditing of Admin actions, go to the `Events` left menu item and select the `Config` tab.
@ -15,8 +15,7 @@ In the `Admin Events Settings` section, turn on the `Save Events` switch.
.Admin Event Configuration .Admin Event Configuration
image:../../{{book.images}}/admin-events-settings.png[] 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 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
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. 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. To view the admin events go to the `Admin Events` tab.

52
topics/events/login.adoc
View file

@ -1,9 +1,9 @@
=== Login Events === 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 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. Really every single event that happens to a user can be recorded and viewed. By default, no events are stored is updated. 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 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. persisting you'll need to enable storage. Go to the `Events` left menu item and select the `Config` tab.
.Event Configuration .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[] 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` 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 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 for. Once you've enabled storage of login events and decided on you settings, don't forget to click 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 button of this page. the `Save` button on the bottom of this page.
To view events, go to the `Login Events` tab. To view events, go to the `Login Events` tab.
.Login Events .Login Events
image:../../{{book.images}}/login-events.png[] 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. each login action. The `Filter` button on this page allows you to filter which events you are actually interested in.
.Login Event Filter .Login Event Filter
@ -37,31 +37,31 @@ In this screenshot, we're filtering only `Login` events. Clicking the `Update`
Login events: Login events:
* Login - A user has logged in * Login - A user has logged in.
* Register - A user has registered * Register - A user has registered.
* Logout - A user has logged out * Logout - A user has logged out.
* Code to Token - An application/client has exchanged a code for a token * Code to Token - An application/client has exchanged a code for a token.
* Refresh Token - An application/client has refreshed a token * Refresh Token - An application/client has refreshed a token.
Account events: Account events:
* Social Link - An account has been linked to a social provider * Social Link - An account has been linked to a social provider.
* Remove Social Link - A social provider has been removed from an account * Remove Social Link - A social provider has been removed from an account.
* Update Email - The email address for an account has changed * Update Email - The email address for an account has changed.
* Update Profile - The profile for an account has changed * Update Profile - The profile for an account has changed.
* Send Password Reset - A password reset email has been sent * Send Password Reset - A password reset email has been sent.
* Update Password - The password for an account has changed * Update Password - The password for an account has changed.
* Update TOTP - The TOTP settings for an account has changed * Update TOTP - The TOTP settings for an account have changed.
* Remove TOTP - TOTP has been removed from an account * Remove TOTP - TOTP has been removed from an account.
* Send Verify Email - A email verification email has been sent * Send Verify Email - An email verification email has been sent.
* Verify Email - The email address for an account has been verified * Verify Email - The email address for an account has been verified.
For all events there is a corresponding error event. For all events there is a corresponding error event.
==== Event Listener ==== Event Listener
Event listeners listen for events and perform an action based on that event. There are two built in 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. 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: Here's an example log message:
@ -76,10 +76,10 @@ 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 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 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 do what it does to prevent attacks. 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: The Email Event Listener only supports the following events at the moment:
* Login Error * Login Error