keycloak-scim/server_admin/topics/events/login.adoc

=== 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="[&quot;UPDATE_TOTP&quot;,&quot;REMOVE_TOTP&quot;]"/>
    </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::[]