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

=== 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.

.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`.

.Save Events
image:{project_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` 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:{project_images}/login-events.png[]

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
image:{project_images}/login-events-filter.png[]

In this screenshot, we're filtering only `Login` events.  Clicking the `Update` button runs the filter.


==== Event Types

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.

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 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
listeners that come with {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:

----
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
----

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.

The Logging Event Listener logs events to the `org.keycloak.events` logger category. By default debug log events are not
included in server logs.

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`.

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>
----

Valid values for the 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.

Currently, the Email Event Listener supports the following events:

* Login Error
* Update Password
* Update TOTP
* Remove 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.

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:

[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 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.:

[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
where the `standalone.xml`, `standalone-ha.xml`, or `domain.xml` file lives.