KEYCLOAK-15942 Rewording (#56)
* KEYCLOAK-15942 Rewording * Post feedback changes * Post feedback changes * Post feedback changes again
This commit is contained in:
Brian Dooley
Marek Posolda
parent
0bcf8bcc5e
commit
10ecbfe1db
4 changed files with 138 additions and 89 deletions
|
|
@ -1,7 +1,8 @@
|
|||
StylesPath = /Users/bdooley/Documents/code/vale-boilerplate/styles
|
||||
MinAlertLevel = warning
|
||||
MinAlertLevel = error
|
||||
|
||||
Vocab = blog
|
||||
|
||||
|
||||
[*.adoc]
|
||||
BasedOnStyles = IBM, Vale
|
||||
BasedOnStyles = IBM, Vale, write-good
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
|
||||
== Configuring auditing to track events
|
||||
|
||||
{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
|
||||
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.
|
||||
[role="_abstract"]
|
||||
{project_name} includes a suite of auditing capabilities. You can record every login and administrator action and review those actions in the Admin Console. {project_name} 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.
|
||||
|
|
|
|||
|
|
@ -1,36 +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 {project_name} REST interface. {project_name}
|
||||
audits these REST invocations. The resulting events can then be viewed in the Admin Console.
|
||||
You can record all actions that are performed by an administrator in the Admin Console. The Admin Console performs administrative actions by invoking the {project_name} REST interface and {project_name} audits these REST invocations. You can view the resulting events 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:
|
||||
|
||||
.Procedure
|
||||
. Click *Events* in the menu.
|
||||
. Click the *Config* tab.
|
||||
+
|
||||
.Event Configuration
|
||||
image:{project_images}/login-events-config.png[]
|
||||
|
||||
In the `Admin Events Settings` section, turn on the `Save Events` switch.
|
||||
|
||||
image:{project_images}/login-events-config.png[Event Configuration]
|
||||
+
|
||||
. Toggle *Save Events* to *ON* in the *Admin Events Settings* section. {project_name} displays the *Include Representation* switch.
|
||||
+
|
||||
.Admin Event Configuration
|
||||
image:{project_images}/admin-events-settings.png[]
|
||||
image:{project_images}/admin-events-settings.png[Admin Event Configuration]
|
||||
+
|
||||
. Toggle *Include Representation* to *ON*.
|
||||
|
||||
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.
|
||||
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 go to the `Admin Events` tab.
|
||||
To view the admin events, click the *Admin Events* tab.
|
||||
|
||||
.Admin Events
|
||||
image:{project_images}/admin-events.png[]
|
||||
image:{project_images}/admin-events.png[Admin Events]
|
||||
|
||||
If the `Details` column has a `Representation` box, you can click on that to view the JSON that was sent with that operation.
|
||||
If the `Details` column has a *Representation* button, click the *Representation* button to view the JSON {project_name} sent with the operation.
|
||||
|
||||
.Admin Representation
|
||||
image:{project_images}/admin-events-representation.png[]
|
||||
image:{project_images}/admin-events-representation.png[Admin Representation]
|
||||
|
||||
You can also filter for the events you are interested in by clicking the `Filter` button.
|
||||
Click `Filter` to view specific events.
|
||||
|
||||
.Admin Event Filter
|
||||
image:{project_images}/admin-events-filter.png[]
|
||||
|
||||
|
||||
image:{project_images}/admin-events-filter.png[Admin Event Filter]
|
||||
|
|
|
|||
|
|
@ -1,70 +1,111 @@
|
|||
|
||||
=== Login Events
|
||||
|
||||
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.
|
||||
You can record and view every event that affects users. {project_name} triggers login events for actions such as successful user login, a user entering an incorrect password, or a user account updating. By default, {project_name} 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
|
||||
image:{project_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`.
|
||||
|
||||
image:{project_images}/login-events-config.png[Event Configuration]
|
||||
+
|
||||
. Toggle *Save Events* to *ON*.
|
||||
+
|
||||
.Save Events
|
||||
image:{project_images}/login-events-settings.png[]
|
||||
image:{project_images}/login-events-settings.png[Save Events]
|
||||
+
|
||||
. Specify the events to store in the *Saved Types* field.
|
||||
|
||||
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` 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.
|
||||
You can click the *Clear events* button to delete all events.
|
||||
|
||||
To view events, go to the `Login Events` tab.
|
||||
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
|
||||
image:{project_images}/login-events.png[]
|
||||
image:{project_images}/login-events.png[Login Events]
|
||||
|
||||
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.
|
||||
You can filter events using the *Filter* button.
|
||||
|
||||
.Login Event Filter
|
||||
image:{project_images}/login-events-filter.png[]
|
||||
|
||||
In this screenshot, we're filtering only `Login` events. Clicking the `Update` button runs the filter.
|
||||
image:{project_images}/login-events-filter.png[Login Event Filter]
|
||||
|
||||
In this example, we filter only `Login` events. Click *Update* to run the filter.
|
||||
|
||||
==== Event Types
|
||||
|
||||
Login events:
|
||||
*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.
|
||||
[cols="2",options="header"]
|
||||
|===
|
||||
|Event |Description
|
||||
|Login
|
||||
|A user logs in.
|
||||
|
||||
Account events:
|
||||
|Register
|
||||
|A user registers.
|
||||
|
||||
* 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.
|
||||
|Logout
|
||||
|A user logs out.
|
||||
|
||||
For all events there is a corresponding error event.
|
||||
|Code to Token
|
||||
|An application, or client, exchanges a code for a token.
|
||||
|
||||
|Refresh Token
|
||||
|An application, or client, refreshes a token.
|
||||
|
||||
|===
|
||||
|
||||
*Account events:*
|
||||
|
||||
[cols="2",options="header"]
|
||||
|===
|
||||
|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
|
||||
|{project_name} 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
|
||||
|{project_name} removes TOTP from an account.
|
||||
|
||||
|Send Verify Email
|
||||
|{project_name} sends an email verification email.
|
||||
|
||||
|Verify Email
|
||||
|{project_name} verifies the email address for an account.
|
||||
|
||||
|===
|
||||
|
||||
Each event has a corresponding error event.
|
||||
|
||||
==== Event Listener
|
||||
|
||||
Event listeners listen for events and perform an action based on that event. There are two built-in
|
||||
listeners that come with {project_name}: Logging Event Listener and Email Event Listener.
|
||||
Event listeners listen for events and perform actions based on that event. {project_name} includes two built-in listeners, the 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:
|
||||
===== 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:
|
||||
|
||||
----
|
||||
11:36:09,965 WARN [org.keycloak.events] (default task-51) type=LOGIN_ERROR, realmId=master,
|
||||
|
|
@ -75,15 +116,20 @@ Here's an example log message:
|
|||
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. Then feed this information
|
||||
into Fail2Ban so that it can help prevent attacks.
|
||||
You can use the Logging Event Listener to protect against hacker bot attacks:
|
||||
|
||||
The Logging Event Listener logs events to the `org.keycloak.events` logger category. By default debug log events are not
|
||||
included in server logs.
|
||||
. 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.
|
||||
|
||||
To include debug log events in server logs, edit the `standalone.xml` file and change the log level used by the Logging
|
||||
Event listener. Alternately, you can configure the log level for `org.keycloak.events`.
|
||||
The Logging Event Listener logs events to the `org.keycloak.events` log category. {project_name} 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:
|
||||
|
||||
|
|
@ -114,22 +160,27 @@ To change the log level used by the Logging Event listener, add the following:
|
|||
</subsystem>
|
||||
----
|
||||
|
||||
Valid values for the log levels are `debug`, `info`, `warn`, `error`, and `fatal`.
|
||||
The valid values for log levels are `debug`, `info`, `warn`, `error`, and `fatal`.
|
||||
|
||||
The Email Event Listener sends an email to the user's account when an event occurs.
|
||||
===== The Email Event Listener
|
||||
|
||||
Currently, the Email Event Listener supports the following events:
|
||||
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 TOTP
|
||||
* Remove TOTP
|
||||
* Login Error.
|
||||
* Update Password.
|
||||
* Update Time-based One-time Password (TOTP).
|
||||
* Remove Time-based One-time Password (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.
|
||||
.Procedure
|
||||
|
||||
You can exclude one or more events by editing the `standalone.xml`, `standalone-ha.xml`, or `domain.xml`
|
||||
that comes with your distribution and adding for example:
|
||||
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:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
|
|
@ -142,8 +193,7 @@ that comes with your distribution and adding for example:
|
|||
</spi>
|
||||
----
|
||||
|
||||
You can also set up a maximum length of the Event detail stored in the database by editing `standalone.xml`, `standalone-ha.xml`, or
|
||||
`domain.xml`. This setting can be useful in case some field (e.g. redirect_uri) is very long. Here is an example of defining the maximum length.:
|
||||
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:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
|
|
@ -156,5 +206,4 @@ You can also set up a maximum length of the Event detail stored in the database
|
|||
</spi>
|
||||
----
|
||||
|
||||
See the link:{installguide_link}[{installguide_name}] for more details on
|
||||
where the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file lives.
|
||||
See the link:{installguide_link}[{installguide_name}] for more details on the location of the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` files.
|
||||
|
|
|
|||
Loading…
Reference in a new issue