Configuration

Publishing Assets

New Installations

You can publish and run the migrations with:

1php artisan vendor:publish --provider="Rappasoft\LaravelAuthenticationLog\LaravelAuthenticationLogServiceProvider" --tag="authentication-log-migrations"
2php artisan migrate

Upgrading from v3.x or Earlier

If you're upgrading from an older version, the package includes an upgrade migration that will safely add new columns to your existing authentication_log table:

1# Update the package
2composer update rappasoft/laravel-authentication-log
3 
4# Publish migrations (includes upgrade migration)
5php artisan vendor:publish --provider="Rappasoft\LaravelAuthenticationLog\LaravelAuthenticationLogServiceProvider" --tag="authentication-log-migrations"
6 
7# Run migrations (upgrade migration checks for existing columns)
8php artisan migrate

The upgrade migration (*_add_new_features_to_authentication_log_table.php) will:

Check if each new column already exists
Only add columns that don't exist
Preserve all existing data
Set safe default values for new columns

Note: Existing authentication logs will have null values for new columns (device_id, device_name, etc.). Only new logs created after the upgrade will populate these fields.

For detailed upgrade instructions, see the Upgrade Guide.

You can publish the view/email files with:

1php artisan vendor:publish --provider="Rappasoft\LaravelAuthenticationLog\LaravelAuthenticationLogServiceProvider" --tag="authentication-log-views"

You can publish the config file with:

1php artisan vendor:publish --provider="Rappasoft\LaravelAuthenticationLog\LaravelAuthenticationLogServiceProvider" --tag="authentication-log-config"

This is the contents of the published config file:

  1return [
  2    // The database table name
  3    // You can change this if the database keys get too long for your driver
  4    'table_name' => 'authentication_log',
  5 
  6    // The database connection where the authentication_log table resides. Leave empty to use the default
  7    'db_connection' => null,
  8 
  9    // The events the package listens for to log
 10    'events' => [
 11        'login' => \Illuminate\Auth\Events\Login::class,
 12        'failed' => \Illuminate\Auth\Events\Failed::class,
 13        'logout' => \Illuminate\Auth\Events\Logout::class,
 14        'other-device-logout' => \Illuminate\Auth\Events\OtherDeviceLogout::class,
 15    ],
 16 
 17    'listeners' => [
 18        'login' => \Rappasoft\LaravelAuthenticationLog\Listeners\LoginListener::class,
 19        'failed' => \Rappasoft\LaravelAuthenticationLog\Listeners\FailedLoginListener::class,
 20        'logout' => \Rappasoft\LaravelAuthenticationLog\Listeners\LogoutListener::class,
 21        'other-device-logout' => \Rappasoft\LaravelAuthenticationLog\Listeners\OtherDeviceLogoutListener::class,
 22    ],
 23 
 24    'notifications' => [
 25        'new-device' => [
 26            // Send the NewDevice notification
 27            'enabled' => env('NEW_DEVICE_NOTIFICATION', true),
 28 
 29            // Use torann/geoip to attempt to get a location
 30            'location' => true,
 31 
 32            // The Notification class to send
 33            'template' => \Rappasoft\LaravelAuthenticationLog\Notifications\NewDevice::class,
 34 
 35            // Rate limiting for notifications (max attempts per time period)
 36            'rate_limit' => env('NEW_DEVICE_NOTIFICATION_RATE_LIMIT', 3),
 37            'rate_limit_decay' => env('NEW_DEVICE_NOTIFICATION_RATE_LIMIT_DECAY', 60), // minutes
 38        ],
 39        'failed-login' => [
 40            // Send the FailedLogin notification
 41            'enabled' => env('FAILED_LOGIN_NOTIFICATION', false),
 42 
 43            // Use torann/geoip to attempt to get a location
 44            'location' => true,
 45 
 46            // The Notification class to send
 47            'template' => \Rappasoft\LaravelAuthenticationLog\Notifications\FailedLogin::class,
 48 
 49            // Rate limiting for notifications (max attempts per time period)
 50            'rate_limit' => env('FAILED_LOGIN_NOTIFICATION_RATE_LIMIT', 5),
 51            'rate_limit_decay' => env('FAILED_LOGIN_NOTIFICATION_RATE_LIMIT_DECAY', 60), // minutes
 52        ],
 53        'suspicious-activity' => [
 54            // Send the SuspiciousActivity notification (disabled by default)
 55            'enabled' => env('SUSPICIOUS_ACTIVITY_NOTIFICATION', false),
 56 
 57            // Use torann/geoip to attempt to get a location
 58            'location' => true,
 59 
 60            // The Notification class to send
 61            'template' => \Rappasoft\LaravelAuthenticationLog\Notifications\SuspiciousActivity::class,
 62 
 63            // Rate limiting for notifications (max attempts per time period)
 64            'rate_limit' => env('SUSPICIOUS_ACTIVITY_NOTIFICATION_RATE_LIMIT', 3),
 65            'rate_limit_decay' => env('SUSPICIOUS_ACTIVITY_NOTIFICATION_RATE_LIMIT_DECAY', 60), // minutes
 66        ],
 67    ],
 68 
 69    // Suspicious activity detection
 70    'suspicious' => [
 71        // Threshold for failed login attempts to be considered suspicious
 72        'failed_login_threshold' => env('AUTH_LOG_SUSPICIOUS_FAILED_THRESHOLD', 5),
 73 
 74        // Check for unusual login times
 75        'check_unusual_times' => env('AUTH_LOG_CHECK_UNUSUAL_TIMES', false),
 76 
 77        // Usual login hours (0-23)
 78        'usual_hours' => [9, 10, 11, 12, 13, 14, 15, 16, 17],
 79    ],
 80 
 81    // Webhook configuration
 82    'webhooks' => [
 83        // [
 84        //     'url' => 'https://example.com/webhook',
 85        //     'events' => ['login', 'failed', 'new_device', 'suspicious'],
 86        //     'headers' => [
 87        //         'Authorization' => 'Bearer your-token',
 88        //     ],
 89        // ],
 90    ],
 91 
 92    // Webhook settings
 93    'webhook_settings' => [
 94        'log_failures' => env('AUTH_LOG_WEBHOOK_LOG_FAILURES', true),
 95        'timeout' => env('AUTH_LOG_WEBHOOK_TIMEOUT', 10),
 96    ],
 97 
 98    // When the clean-up command is run, delete old logs greater than `purge` days
 99    // Don't schedule the clean-up command if you want to keep logs forever.
100    'purge' => 365,
101 
102    // Prevent session restorations from being logged as new logins
103    // When Laravel restores a session (e.g., page refresh, remember me cookie),
104    // it fires the Login event. This setting prevents those from creating duplicate log entries.
105    'prevent_session_restoration_logging' => env('AUTH_LOG_PREVENT_SESSION_RESTORATION', true),
106 
107    // Time window (in minutes) to consider a login as a session restoration
108    // If an active session exists for the same device within this window, update it instead of creating a new entry
109    'session_restoration_window_minutes' => env('AUTH_LOG_SESSION_RESTORATION_WINDOW', 5),
110 
111    // If you are behind an CDN proxy, set 'behind_cdn.http_header_field' to the corresponding http header field of your cdn
112    // For cloudflare you can have look at: https://developers.cloudflare.com/fundamentals/get-started/reference/http-request-headers/
113    // 'behind_cdn' => [
114    //     'http_header_field' => 'HTTP_CF_CONNECTING_IP' // used by Cloudflare
115    // ],
116 
117    // If you are not a cdn user, use false
118    'behind_cdn' => false,
119];

If you installed torann/geoip you should also publish that config file to set your defaults:

1php artisan vendor:publish --provider="Torann\GeoIP\GeoIPServiceProvider" --tag=config

Setting up your model

You must add the AuthenticationLoggable and Notifiable traits to the models you want to track.

1use Illuminate\Notifications\Notifiable;
2use Rappasoft\LaravelAuthenticationLog\Traits\AuthenticationLoggable;
3use Illuminate\Foundation\Auth\User as Authenticatable;
4 
5class User extends Authenticatable
6{
7    use Notifiable, AuthenticationLoggable;
8}

The package will listen for Laravel's Login, Logout, Failed, and OtherDeviceLogout events.

Suspicious Activity Detection

Configure suspicious activity detection thresholds:

1'suspicious' => [
2    'failed_login_threshold' => 5, // Number of failed logins in 1 hour to trigger suspicious flag
3    'check_unusual_times' => true, // Enable unusual time detection
4    'usual_hours' => [9, 10, 11, 12, 13, 14, 15, 16, 17], // Hours considered "usual"
5],

Suspicious Activity Notifications

You can enable notifications when suspicious activity is detected. This is disabled by default.

1'notifications' => [
2    'suspicious-activity' => [
3        'enabled' => env('SUSPICIOUS_ACTIVITY_NOTIFICATION', false),
4        'location' => function_exists('geoip'),
5        'template' => \Rappasoft\LaravelAuthenticationLog\Notifications\SuspiciousActivity::class,
6        'rate_limit' => env('SUSPICIOUS_ACTIVITY_NOTIFICATION_RATE_LIMIT', 3),
7        'rate_limit_decay' => env('SUSPICIOUS_ACTIVITY_NOTIFICATION_RATE_LIMIT_DECAY', 60),
8    ],
9],

When enabled, users will receive notifications for:

Multiple failed login attempts
Rapid location changes
Unusual login times (if enabled)

See the Suspicious Activity documentation for more details.

Webhook Configuration

Set up webhooks to receive authentication events:

1'webhooks' => [
2    [
3        'url' => 'https://example.com/webhook',
4        'events' => ['login', 'failed', 'new_device', 'suspicious'], // or ['*'] for all events
5        'headers' => [
6            'Authorization' => 'Bearer your-token',
7        ],
8    ],
9],

Available events: login, failed, new_device, suspicious

Session Restoration Prevention

As of v4.0.0, the package automatically prevents session restorations (page refreshes, remember me cookie restorations) from creating duplicate log entries. When Laravel fires the Login event during session restoration, the package detects this and updates the last_activity_at timestamp instead of creating a new log entry.

You can configure this behavior in your config/authentication-log.php:

1// Prevent session restorations from being logged as new logins
2// When Laravel restores a session (e.g., page refresh, remember me cookie),
3// it fires the Login event. This setting prevents those from creating duplicate log entries.
4'prevent_session_restoration_logging' => env('AUTH_LOG_PREVENT_SESSION_RESTORATION', true),
5 
6// Time window (in minutes) to consider a login as a session restoration
7// If an active session exists for the same device within this window, update it instead of creating a new entry
8'session_restoration_window_minutes' => env('AUTH_LOG_SESSION_RESTORATION_WINDOW', 5),

Default behavior:

prevent_session_restoration_logging: true (enabled by default)
session_restoration_window_minutes: 5 minutes

If an active session exists for the same device/user within the configured window, the package will:

Update last_activity_at on the existing log entry
Skip creating a new log entry
Skip sending notifications

This prevents duplicate log entries from page refreshes while still logging actual new logins from different devices or after logout.

Disabling Session Restoration Prevention

If you want to log every Login event (including session restorations), you can disable this feature:

1'prevent_session_restoration_logging' => false,

Overriding default Laravel events

If you would like to listen to your own events you may override them in the package config (as of v1.2).

Note: As of v4.0.0, the session restoration prevention feature handles this automatically. The event override workaround below is no longer necessary but still available if you prefer custom event handling.

Example event override (Legacy Workaround)

You may notice that Laravel fires a Login event when the session renews if the user clicked 'remember me' when logging in. This is now handled automatically by the session restoration prevention feature, but if you prefer custom event handling, you can fire your own Login event instead of listening for Laravel's.

You can create a Login event that takes the user:

 1<?php
 2 
 3namespace App\Domains\Auth\Events;
 4 
 5use Illuminate\Queue\SerializesModels;
 6 
 7class Login
 8{
 9    use SerializesModels;
10 
11    public $user;
12 
13    public function __construct($user)
14    {
15        $this->user = $user;
16    }
17}

Then override it in the package config:

1// The events the package listens for to log
2'events' => [
3    'login' => \App\Domains\Auth\Events\Login::class,
4    ...
5],

Then call it where you login your user:

1event(new Login($user));

Now the package will only register actual login events, and not session re-authentications.

Overriding in Fortify

If you are working with Fortify and would like to register your own Login event, you can append a class to the authentication stack:

In FortifyServiceProvider:

1Fortify::authenticateThrough(function () {
2    return array_filter([
3        ...
4        FireLoginEvent::class,
5    ]);
6});

FireLoginEvent is just a class that fires the event:

 1<?php
 2 
 3namespace App\Domains\Auth\Actions;
 4 
 5use App\Domains\Auth\Events\Login;
 6 
 7class FireLoginEvent
 8{
 9    public function handle($request, $next)
10    {
11        if ($request->user()) {
12            event(new Login($request->user()));
13        }
14 
15        return $next($request);
16    }
17}

Configuration

Publishing Assets

New Installations

Upgrading from v3.x or Earlier

Setting up your model

Suspicious Activity Detection

Suspicious Activity Notifications

Webhook Configuration

Session Restoration Prevention

Configuration

Disabling Session Restoration Prevention

Overriding default Laravel events

Example event override (Legacy Workaround)

Overriding in Fortify

Search

Start searching

Configuration

#Publishing Assets

#New Installations

#Upgrading from v3.x or Earlier

#Setting up your model

#Suspicious Activity Detection

#Suspicious Activity Notifications

#Webhook Configuration

#Session Restoration Prevention

#Configuration

#Disabling Session Restoration Prevention

#Overriding default Laravel events

#Example event override (Legacy Workaround)

#Overriding in Fortify

Search

Start searching

Publishing Assets

New Installations

Upgrading from v3.x or Earlier

Setting up your model

Suspicious Activity Detection

Suspicious Activity Notifications

Webhook Configuration

Session Restoration Prevention

Configuration

Disabling Session Restoration Prevention

Overriding default Laravel events

Example event override (Legacy Workaround)

Overriding in Fortify