Laravel SentinelLog

Laravel SentinelLog is a powerful, all-in-one authentication logging and security package for Laravel. It provides advanced features like device tracking, 2FA, session management, brute force protection, geo-fencing, and SSO support, ensuring security while keeping users informed.

Features

• Authentication Logging: Logs login, logout, and failed attempts.
• Device & Geolocation Tracking: Tracks devices and locations for authentication events.
• Notifications: Alerts for new device logins and failed attempts.
• Two-Factor Authentication (2FA): TOTP-based 2FA with QR code support.
• Session Management: Tracks multiple sessions and detects hijacking.
• Brute Force Protection: Rate-limits login attempts and blocks suspicious IPs.
• Geo-Fencing: Restricts logins to specific countries.
• Single Sign-On (SSO): Token-based SSO for seamless authentication.
• New Location Verification: Detects logins from unrecognised locations and emails the user a verify/deny link, invalidating the session on denial.

Demo Project

Want to see Laravel SentinelLog in action? Check out our demo project:

Laravel SentinelLog Demo

This demo project showcases:

• Complete authentication system with SentinelLog integration
• Real-world implementation of all features
• Best practices for configuration and usage
• Example of custom notifications and event handling
• Interactive UI for testing various security features

To run the demo locally:

git clone https://github.com/Harish120/sentinel-test.git
cd sentinel-test
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan db:seed
php artisan serve

Visit http://localhost:8000 to explore the demo.

Installation

Prerequisites

• PHP 8.2 or higher
• Laravel 10.x, 11.x, 12.x, or 13.x
• Composer

Steps

1. Install the Package

  composer require harryes/laravel-sentinellog

2. Publish Configuration

  php artisan vendor:publish --tag=sentinel-log-config

3. Run Migrations

  php artisan migrate

4. Add Trait to User Model

    use Harryes\SentinelLog\Traits\NotifiesAuthenticationEvents;
    
    class User extends Authenticatable
    {
        use NotifiesAuthenticationEvents;
    
        protected $fillable = ['two_factor_secret', 'two_factor_enabled_at'];
        protected $casts = ['two_factor_enabled_at' => 'datetime'];
    }

Configuration

Edit config/sentinel-log.php to customize the package. Key options:

General Settings

    'enabled' => true,
    'events' => ['login' => true, 'logout' => true, 'failed' => true],
    'table_name' => 'authentication_logs',

Notifications

    'new_device' => ['enabled' => true, 'channels' => ['mail']],
    'failed_attempt' => ['threshold' => 5, 'window' => 15],

Two-Factor Authentication (2FA)

    'two_factor' => ['enabled' => false, 'middleware' => 'sentinel-log.2fa'],

Sessions

    'sessions' => ['enabled' => true, 'max_active' => 5],

Brute Force Protection

    'brute_force' => ['enabled' => true, 'threshold' => 5, 'window' => 15, 'block_duration' => 24],

Geo-Fencing

    'geo_fencing' => ['enabled' => false, 'allowed_countries' => ['United States', 'Canada']],

SSO

    'sso' => ['enabled' => false, 'client_id' => 'default_client', 'token_lifetime' => 24],

New Location Verification

    'location_verification' => [
        'enabled' => true,
        'channels' => ['mail'],
        'token_ttl' => 30, // Minutes until verify/deny links expire
        'redirect_after_verify' => '/',
        'redirect_after_deny' => '/',
    ],

Environment Variables

Add these to .env:

    SENTINEL_LOG_ENABLED=true
    SENTINEL_LOG_2FA_ENABLED=true
    SENTINEL_LOG_GEO_FENCING_ENABLED=true
    SENTINEL_LOG_GEO_FENCING_ALLOWED_COUNTRIES="United States,Canada"
    SENTINEL_LOG_LOCATION_VERIFICATION_ENABLED=true

Usage Examples

2FA Setup

Generate a 2FA secret and QR code:

    use Harryes\SentinelLog\Services\TwoFactorAuthenticationService;
    
    $service = new TwoFactorAuthenticationService();
    $user->update([
        'two_factor_secret' => $service->generateSecret(),
        'two_factor_enabled_at' => now(),
    ]);
    $qrCodeUrl = $service->getQrCodeUrl($user->two_factor_secret, $user->email);

Protect routes with 2FA middleware:

    Route::middleware('sentinel-log.2fa')->group(function () {
        Route::get('/dashboard', fn() => 'Protected!');
    });

Verify 2FA code:

    Route::post('/2fa/verify', function (TwoFactorAuthenticationService $service) {
        if ($service->verifyCode(auth()->user()->two_factor_secret, request('code'))) {
            session(['2fa_verified' => true]);
            return redirect('/dashboard');
        }
        return back()->withErrors(['code' => 'Invalid 2FA code']);
    });

SSO Integration

Generate an SSO token:

    use Harryes\SentinelLog\Services\SsoAuthenticationService;
    
    $ssoService = new SsoAuthenticationService();
    $token = $ssoService->generateToken(auth()->user(), 'client_app_1');

Handle SSO login in the client app:

    Route::get('/sso/login', fn() => 'Logged in via SSO')->middleware('auth');

Session Management

View active sessions:

    $sessions = auth()->user()->authenticationLogs()->with('session')->get();

Brute Force & Geo-Fencing

Attempts are automatically rate-limited, and IPs are blocked after exceeding the threshold. Geo-fencing blocks logins from unallowed countries based on config/sentinel-log.php.

New Location Verification

When a user logs in from a city/country they have never used before, SentinelLog automatically sends them a NewLocationLogin notification with two action links:

• Yes, this was me — marks the location as verified and logs a location_verified event.
• No, deny this login — marks the login as denied, logs a location_denied event, and immediately invalidates the session.

The links expire after token_ttl minutes (default 30). No application code changes are required — the check runs inside the LogSuccessfulLogin listener on every login.

To disable the feature:

SENTINEL_LOG_LOCATION_VERIFICATION_ENABLED=false

To prune expired, unactioned verification records:

    use Harryes\SentinelLog\Services\LocationVerificationService;

    app(LocationVerificationService::class)->pruneExpired();

Contributing

Submit issues or pull requests on GitHub. Feedback is welcome!

License

This package is open-sourced under the MIT License.