How to keep track of Laravel Authentication Events in your application

Laravel has multiple Authentication Events that are dispatched by the framework.

We’ll shortly discuss all the Authentication Events. You can find more information about each event and their properties in the Laravel API (https://laravel.com/api/9.x/Illuminate/Auth/Events.html).

Laravel Authentication Events

Flow chart of all Laravel authentication Events

Attempting
This event is dispatched after the user tries to login (first event in the chain)

Validated
This event is dispatched after the credentials are verified

Login
This event is dispatched after the Validated event and the user is logged in

Authenticated
This event is dispatched after the user is identified and authenticated

Failed
This event is dispatched after the user tries to login with invalid credentials

Lockout
This event is dispatched after the user reached a certain number of Failed events

Logout
This event is dispatched after the user closes the session and is called after all sessions and cookies are made invalid

CurrentDeviceLogout
This event is dispatched after the user logs out of the current session and the session is made invalid

OtherDeviceLogout
This event is dispatched after all other sessions of the user are made invalid (usually after a new login)

Registered
This event is dispatched after the user registers (usually with a name, email and password)

Verified
This event is dispatched after the user has verified his/her email address (email_verified_at field is set)

PasswordReset
This event is dispatched after the new password of the user is persisted into the the database (usually after a password reset request)

In your EventServiceProvider you can listen for these event being dispatched and call one or multiple Listeners.

Laravel ships with one authentication Event — Listener action by default. The ‘SendEmailVerificationNotification’ is called when the Registered event is dispatched (https://github.com/laravel/framework/blob/9.x/src/Illuminate/Auth/Listeners/SendEmailVerificationNotification.php).

Save the Authentication actions to the database

To track unwanted activity or to keep track of statistics in your Laravel application we’ll use these Authentication Events.

We’ll make use of the Laravel package ‘Laravel Auth Log’ (https://github.com/Label84/laravel-auth-log) that does just this.

We’ll install the package through composer.

composer require label84/laravel-auth-log

We’ll then publish the configuration file.

php artisan vendor:publish --provider="Label84\AuthLog\AuthLogServiceProvider" --tag="config"

We’ll then add the migration to our application.

php artisan vendor:publish --provider="Label84\AuthLog\AuthLogServiceProvider" --tag="migrations"

And we’ll run the migrations.

php artisan migrate

Now we’ve installed the package, we can change some configuration and select which Events we want to save to the database.

In the config file you’ll see a list of all the Authentication Events that can be saved to the database. You can comment out the once you don’t need. In the example below we only enabled 5/10 events.

// config/authlog.php

return [
    // ...
    'events' => [
        // \Illuminate\Auth\Events\Attempting::class,
        // \Illuminate\Auth\Events\Authenticated::class,
        \Illuminate\Auth\Events\Failed::class,
        \Illuminate\Auth\Events\Lockout::class,
        \Illuminate\Auth\Events\Login::class,
        // \Illuminate\Auth\Events\Logout::class,
        // \Illuminate\Auth\Events\OtherDeviceLogout::class,
        // \Illuminate\Auth\Events\PasswordReset::class,
        \Illuminate\Auth\Events\Registered::class,
        \Illuminate\Auth\Events\Verified::class,
    ],
];

When a users registers, verifies their email address or successfully is logged in you’ll now see records of those actions in your database in the table ‘authentication_logs’.

Each row in the table contains the following information:

• Event name
• Email address
• User ID
• IP address
• User-Agent
• Context (empty, see next paragraph)
• Created at

Add custom events and context

By default the package only listens to the default Laravel Authentication Events. We’ll now explain how to add a custom Event to the same table including some context about that Event.

Administrators of our application have the ability to impersonate users. We want to save this information — each time an administrator impersonates a user. Wwe’ll save this information including the ID of the administrator and the ID of the user that the administrator is impersonating.

Our application makes use of the package ‘Laravel Impersonate’ (https://github.com/404labfr/laravel-impersonate). This package dispatches a ‘TakeImpersonation’ event each time an impersonation takes place.

We’ll use this ‘TakeImpersonation’ Event in our new Listener called ‘LogTakeImpersonation’ (we’ve placed this in the Auth/ subdirectory).

php artisan make:listener Auth/LogTakeImpersonation

To let our application know to listen to the ‘TakeImpersonation’ Event we’ll add this to our EventServiceProvider.

// app/Providers/EventServiceProvider.php
protected $listen = [
    // ...
    TakeImpersonation::class => [
        LogTakeImpersonation::class,
    ],
];

We also need to add Event to the list of Events in the config file of the ‘Laravel Auth Log’ package. The handler of the ‘LogAuthAction’ checks if the Event is listed here, otherwise the event is ignored.

// config/authlog.php

return [
    // ...
    'events' => [
        // ...
        \Illuminate\Auth\Events\Registered::class,
        \Illuminate\Auth\Events\Verified::class,
        Lab404\Impersonate\Events\TakeImpersonation::class,
    ],
];

In the Listener we add an array containing the ‘impersonator_id’ and ‘impersonated_id’ as second argument. These values will be saved to the context column in the database table.