Laravel Auth Checker Laravel Package

Technical Evaluation

Architecture Fit

• Core Use Case Alignment: The package directly addresses authentication monitoring, intrusion detection, and device tracking—key concerns for security-sensitive applications (e.g., SaaS, financial systems, or admin panels). It integrates seamlessly with Laravel’s built-in auth system (Illuminate\Auth), leveraging middleware and events (Illuminate\Auth\Events\Attempting, Authenticated, Failed).
• Modularity: Lightweight (~100 LOC core), non-intrusive, and designed as a "drop-in" solution. No forced architecture changes required; works alongside existing auth providers (e.g., Sanctum, Passport, Jetstream).
• Extensibility: Hooks into Laravel’s event system, allowing customization (e.g., adding IP geolocation, user-agent parsing, or third-party risk scoring). Supports plugin-like behavior via AuthCheckerEvents.

Integration Feasibility

• Low Friction: Requires minimal setup (publish config, run migrations, register middleware). Compatible with Laravel 9+ (PHP 8.0+).
• Database Schema: Adds 3 tables (auth_checker_devices, auth_checker_attempts, auth_checker_lockouts) with sensible defaults (e.g., failed_attempts counter, last_attempt_at). Schema is backward-compatible with minor Laravel versions.
• Middleware: Provides AuthCheckerMiddleware to intercept requests, which can be applied globally or per-route/group (e.g., /admin).
• Event-Driven: Emits events (AuthChecker\Events\Lockout, AuthChecker\Events\DeviceRegistered) for reactive logic (e.g., sending alerts via Laravel Notifications).

Technical Risk

• False Positives/Negatives: Lockout logic relies on configurable thresholds (max_attempts, lockout_duration). Misconfiguration could lead to legitimate users being blocked or intruders slipping through. Mitigation: Start with conservative defaults (e.g., max_attempts=5, lockout_duration=15m) and monitor via auth_checker_attempts table.
• Performance: Logging every auth attempt could impact high-traffic endpoints. Mitigation: Use Laravel’s queue facade to defer logging (e.g., AuthChecker::logAttempt($credentials, $result) in a job).
• Session/Device Tracking: Assumes Laravel’s default session driver. Custom session handlers (e.g., Redis) may require adjustments to device_id generation. Mitigation: Override AuthChecker::getDeviceId() if needed.
• Legacy Systems: If using older Laravel versions (<9.0) or PHP <8.0, the package may not work without forks or shims. Mitigation: Check composer.json constraints or use a compatibility layer.

Key Questions

1. Compliance Requirements:
   • Does the application need to log auth events for auditing (e.g., GDPR, SOC 2)? If so, ensure the package’s schema aligns with retention policies.
2. Multi-Tenant Support:
   • For SaaS, will lockouts apply tenant-wide or per-tenant? The package doesn’t natively support tenants; customization may be needed.
3. Third-Party Integrations:
   • Will auth events trigger external actions (e.g., SIEM alerts, 2FA enforcement)? The event system supports this, but integration effort depends on the tool.
4. Rate-Limiting vs. Lockouts:
   • Should failed attempts trigger rate-limiting (e.g., throttle) before lockouts? The package doesn’t replace Laravel’s built-in throttling; design may need both.
5. Testing Coverage:
   • Are there edge cases to test (e.g., concurrent requests, malformed IPs, custom auth guards)? Unit tests should mock AuthManager and Request.

Integration Approach

Stack Fit

• Laravel Ecosystem: Optimized for Laravel’s auth stack. Works out-of-the-box with:
  • Auth Providers: Sanctum (API), Passport (OAuth), Jetstream/Breeze (web).
  • Session Drivers: File, database, Redis (with minor adjustments for device_id).
  • Queues: Supports async logging via AuthChecker::logAttempt($credentials, $result, true).
• PHP Extensions: No hard dependencies beyond Laravel’s core (e.g., bcmath not required).
• Database: Supports MySQL, PostgreSQL, SQLite (via Laravel’s query builder). No raw SQL.

Migration Path

1. Pre-Integration:
   • Audit existing auth flow: Identify where Auth::attempt(), Auth::login(), or middleware runs.
   • Backup auth-related tables (e.g., users, sessions) before adding new schema.
2. Installation:

   composer require lab404/laravel-auth-checker
   php artisan vendor:publish --provider="Lab404\AuthChecker\AuthCheckerServiceProvider"
   php artisan migrate
   

3. Configuration:
   • Update .env for lockout thresholds (e.g., AUTH_CHECKER_MAX_ATTEMPTS=5).
   • Configure middleware in app/Http/Kernel.php:

     protected $middlewareGroups = [
         'web' => [
             \Lab404\AuthChecker\Http\Middleware\AuthCheckerMiddleware::class,
             // ... other middleware
         ],
     ];
     

4. Customization (Optional):
   • Extend AuthCheckerEvents for custom logic (e.g., log to a SIEM):

     AuthChecker::addListener('lockout', function ($user, $device) {
         event(new CustomLockoutEvent($user, $device));
     });
     

   • Override device detection (e.g., for headless APIs):

     AuthChecker::setDeviceResolver(function ($request) {
         return 'api_client_' . $request->ip();
     });
     

Compatibility

• Laravel Versions: Tested on 9.x–11.x. For 8.x, use v1.0.0 (last compatible release).
• PHP Versions: Requires PHP 8.0+. For 7.4, fork and downgrade dependencies.
• Auth Guards: Primarily tested with session-based auth. For API tokens (e.g., Sanctum), ensure device_id generation works with token-based requests.
• Caching: No caching layer, but can be added via AuthChecker::clearCache() for testing.

Sequencing

1. Phase 1: Logging Only
   • Enable auth attempt logging without lockouts (set AUTH_CHECKER_ENABLE_LOCKOUT=false).
   • Validate data in auth_checker_attempts matches expectations.
2. Phase 2: Lockout Testing
   • Enable lockouts in staging with conservative thresholds.
   • Test with manual brute-force attempts and verify auth_checker_lockouts table.
3. Phase 3: Production Rollout
   • Monitor auth_checker_attempts for anomalies (e.g., sudden spikes).
   • Set up alerts for lockout events (e.g., via Laravel Horizon or external tools).
4. Phase 4: Optimization
   • Tune thresholds based on real-world data (e.g., adjust lockout_duration).
   • Consider async logging for high-traffic endpoints.

Operational Impact

Maintenance

• Package Updates: Actively maintained (last release May 2024). Follow Laravel’s release cycle for compatibility.
• Schema Changes: Minimal risk; migrations are backward-compatible. Monitor auth_checker_attempts table growth (archive old data if needed).
• Configuration Drift: Centralized in .env and config/auth-checker.php. Use Laravel’s config caching for performance.
• Deprecations: No breaking changes in recent versions. Check changelog for v2.0.0 (if released).

Support

• Troubleshooting:
  • Debug lockouts: Query auth_checker_lockouts for affected users/devices.
  • Debug logging: Check auth_checker_attempts for failed attempts.
  • Common issues: IP spoofing (use request()->ip() carefully), session conflicts (ensure device_id is stable).
• Documentation: Basic but sufficient. Community-driven issues on GitHub are responsive.
• Monitoring:
  • Track metrics:
    • failed_attempts rate per user/device.
    • lockout events (alert on spikes).
    • device_registration (new devices may indicate compromise).
  • Tools: Laravel Debugbar, Prometheus (via tightenco/laravel-prometheus), or custom queries.

Scaling

• Database Load:
  • Logging every attempt could generate high write volume. Mitigation:
    • Use async logging (queue jobs for AuthChecker::logAttempt).
    • Archive old attempts (e.g., keep 30 days of data).
  • Indexes: Ensure failed_at and user_id are indexed in auth_checker_attempts.
• Lockout Performance:
  • Lockout checks are O(1) (via auth_checker_lockouts table).