243 lines
No EOL
7.1 KiB
Text
243 lines
No EOL
7.1 KiB
Text
|
||
=== Login events
|
||
|
||
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[Event Configuration]
|
||
+
|
||
. Toggle *Save Events* to *ON*.
|
||
+
|
||
.Save Events
|
||
image:{project_images}/login-events-settings.png[Save Events]
|
||
+
|
||
. Specify the events to store in the *Saved Types* field.
|
||
|
||
You can click the *Clear events* button to delete all events.
|
||
|
||
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[Login Events]
|
||
|
||
You can filter events using the *Filter* button.
|
||
|
||
.Login Events Filter
|
||
image:{project_images}/login-events-filter.png[Login Events Filter]
|
||
|
||
In this example, we filter only `Login` events. Click *Update* to run the filter.
|
||
|
||
==== Event types
|
||
|
||
*Login events:*
|
||
|
||
[cols="2",options="header"]
|
||
|===
|
||
|Event |Description
|
||
|Login
|
||
|A user logs in.
|
||
|
||
|Register
|
||
|A user registers.
|
||
|
||
|Logout
|
||
|A user logs out.
|
||
|
||
|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 actions based on that event. {project_name} includes two built-in listeners, the Logging Event Listener and Email Event Listener.
|
||
|
||
===== 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,
|
||
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
|
||
----
|
||
|
||
You can use the Logging Event Listener to protect against hacker bot attacks:
|
||
|
||
. 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.
|
||
|
||
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:
|
||
|
||
ifeval::["{kc_dist}" == "quarkus"]
|
||
. Change the log level for the `org.keycloak.events` category
|
||
. Change the log level used by the Logging Event listener.
|
||
|
||
To change the log level used by the Logging Event listener, add the following:
|
||
|
||
[source,bash]
|
||
----
|
||
bin/kc.[sh|bat] start --spi-events-listener-jboss-logging-success-level=info --spi-events-listener-jboss-logging-error-level=error
|
||
----
|
||
|
||
The valid values for log levels are `debug`, `info`, `warn`, `error`, and `fatal`.
|
||
endif::[]
|
||
|
||
ifeval::["{kc_dist}" == "wildfly"]
|
||
. 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:
|
||
|
||
[source,xml]
|
||
----
|
||
<subsystem xmlns="urn:jboss:domain:logging:...">
|
||
...
|
||
<logger category="org.keycloak.events">
|
||
<level name="DEBUG"/>
|
||
</logger>
|
||
</subsystem>
|
||
----
|
||
|
||
To change the log level used by the Logging Event listener, add the following:
|
||
|
||
[source,xml]
|
||
----
|
||
<subsystem xmlns="urn:jboss:domain:keycloak-server:...">
|
||
...
|
||
<spi name="eventsListener">
|
||
<provider name="jboss-logging" enabled="true">
|
||
<properties>
|
||
<property name="success-level" value="info"/>
|
||
<property name="error-level" value="error"/>
|
||
</properties>
|
||
</provider>
|
||
</spi>
|
||
</subsystem>
|
||
----
|
||
|
||
The valid values for log levels are `debug`, `info`, `warn`, `error`, and `fatal`.
|
||
endif::[]
|
||
|
||
===== The Email Event Listener
|
||
|
||
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 Time-based One-time Password (TOTP).
|
||
* Remove Time-based One-time Password (TOTP).
|
||
|
||
.Procedure
|
||
|
||
To enable the Email Listener:
|
||
|
||
. Click *Events* from the menu.
|
||
. Click the *Config* tab.
|
||
. Click the *Event Listeners* field.
|
||
. Select `email`.
|
||
|
||
ifeval::["{kc_dist}" == "quarkus"]
|
||
You can exclude events by using the `--spi-events-listener-email-exclude-events` argument. For example:
|
||
|
||
[source,bash]
|
||
----
|
||
kc.[sh|bat] --spi-events-listener-email-exclude-events=UPDATE_TOTP,REMOVE_TOTP
|
||
----
|
||
|
||
You can set a maximum length of the Event detail in the database by using the `--spi-events-listener-email-exclude-events` argument. This setting is useful if a field (for example, redirect_uri) is long. For example:
|
||
|
||
[source,bash]
|
||
----
|
||
kc.[sh|bat] --spi-events-listener-email-max-detail-length=1000
|
||
----
|
||
endif::[]
|
||
|
||
ifeval::["{kc_dist}" == "wildfly"]
|
||
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]
|
||
----
|
||
<spi name="eventsListener">
|
||
<provider name="email" enabled="true">
|
||
<properties>
|
||
<property name="exclude-events" value="["UPDATE_TOTP","REMOVE_TOTP"]"/>
|
||
</properties>
|
||
</provider>
|
||
</spi>
|
||
----
|
||
|
||
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]
|
||
----
|
||
<spi name="eventsStore">
|
||
<provider name="jpa" enabled="true">
|
||
<properties>
|
||
<property name="max-detail-length" value="1000"/>
|
||
</properties>
|
||
</provider>
|
||
</spi>
|
||
----
|
||
|
||
See the link:{installguide_link}[{installguide_name}] for more details on the location of the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` files.
|
||
endif::[] |