README

Quick developer authentication for Laravel applications in local/staging environments. Skip the login form during development by clicking a button to authenticate as any predefined user.

⚠️ Security Warning: This package is designed for development and staging environments only. Never enable it in production!

Features

• 🚀 One-click authentication as any configured user
• 🔒 Safe defaults (disabled in production by default)
• 🎯 Works with Laravel Fortify + Inertia.js
• 🔐 Optional 2FA bypass for developer logins
• 🌐 Multiple authentication guard support
• 🛡️ IP whitelist support (optional)
• 📝 Activity logging for security auditing
• ⚙️ Highly configurable via environment variables

Requirements

• PHP 8.1+
• Laravel 10.x, 11.x, 12.x, or 13.x
• Laravel Fortify (for authentication)

Installation

1. Install via Composer

composer require josrom/laravel-developer-logins --dev

2. Publish Configuration

php artisan vendor:publish --tag="developer-logins-config"

3. Configure Users

By default, the package fetches the first 10 users from your database automatically. You can customize this in config/developer-logins.php:

Option 1: Dynamic users from database (Recommended)

'users' => fn () => App\Models\User::limit(10)->pluck('email', 'name')->toArray()

Option 2: Static predefined users

'users' => [
    'Admin' => 'admin@example.com',
    'User' => 'user@example.com',
]

4. Configure Environment Variables

Add to your .env file:

# Enable/disable developer logins
DEVELOPER_LOGINS_ENABLED=true

# Optional: Bypass 2FA for developer logins (default: false)
DEVELOPER_LOGINS_BYPASS_2FA=false

# Optional: IP whitelist (comma-separated)
DEVELOPER_LOGINS_ALLOWED_IPS=127.0.0.1,::1

5. Integration

For Blade Views

Add to your login view (e.g., resources/views/auth/login.blade.php):

@if(config('developer-logins.enabled'))
    <x-developer-logins::login-buttons />
@endif

For Inertia.js + Vue

The package automatically shares developer logins data with Inertia. Add to your Login component:

<template>
    <div v-if="$page.props.developerLogins" class="mt-4 space-y-2">
        <div class="text-sm text-amber-600 font-semibold">
            ⚠️ Developer Logins Enabled
        </div>

        <form
            v-for="(credentials, label) in $page.props.developerLogins"
            :key="credentials"
            method="POST"
            :action="route('developer-logins.login-as')"
        >
            <input type="hidden" name="_token" :value="$page.props.csrf_token">
            <input type="hidden" name="credentials" :value="credentials">
            <button
                type="submit"
                class="w-full px-4 py-2 bg-amber-100 hover:bg-amber-200 rounded border border-amber-300"
            >
                Login as {{ label }} ({{ credentials }})
            </button>
        </form>
    </div>
</template>

Configuration

The configuration file (config/developer-logins.php) provides extensive customization options:

return [
    // Enable/disable globally (default: only in local environment)
    'enabled' => env('DEVELOPER_LOGINS_ENABLED', env('APP_ENV') === 'local'),

    // User model class
    'model' => App\Models\User::class,

    // Column to match against (email, username, etc.)
    'column' => 'email',

    // Authentication guard (or null for default)
    'guard' => null,

    // Users for quick login (static array or closure)
    // Option 1: Dynamic from database (Recommended)
    'users' => fn () => App\Models\User::limit(10)->pluck('email', 'name')->toArray(),

    // Option 2: Static predefined users
    // 'users' => [
    //     'Admin' => 'admin@example.com',
    //     'User' => 'user@example.com',
    // ],

    // Redirect after successful login
    'redirect_to' => '/admin/dashboard',

    // Bypass 2FA for developer logins (default: false)
    'bypass_2fa' => env('DEVELOPER_LOGINS_BYPASS_2FA', false),

    // IP whitelist (empty = allow all)
    'allowed_ips' => array_filter(explode(',', env('DEVELOPER_LOGINS_ALLOWED_IPS', ''))),

    // Log developer login attempts
    'log_attempts' => env('DEVELOPER_LOGINS_LOG', true),

    // Show warning message on login page
    'show_warning' => true,

    // Throw exception if enabled in production
    'prevent_production' => true,
];

Usage

Basic Usage

Once configured, developer login buttons will appear on your login page. Click any button to authenticate as that user instantly.

Multiple Authentication Guards

To use a specific guard:

// In config/developer-logins.php
'guard' => 'admin',

Or specify per-user in a custom configuration.

IP Whitelist

Restrict developer logins to specific IP addresses:

# .env
DEVELOPER_LOGINS_ALLOWED_IPS=127.0.0.1,::1,192.168.1.100

Logging

All developer login attempts are logged by default:

// Log channel: 'stack' (default Laravel)
// Log level: 'info'
// Log format: "Developer login attempt: {email} from IP: {ip}"

Disable logging in .env:

DEVELOPER_LOGINS_LOG=false

Two-Factor Authentication (2FA)

By default, developer logins still require 2FA if enabled on the user account. To bypass 2FA:

# .env
DEVELOPER_LOGINS_BYPASS_2FA=true

⚠️ Security Note: Only enable 2FA bypass in trusted local environments.

Security

Built-in Safety Features

✅ Disabled by default in production - Set APP_ENV=production and the package won't work ✅ Exception on production - Throws ConfigurationException if enabled in production (configurable) ✅ IP whitelist support - Restrict to specific IPs ✅ Activity logging - All attempts logged for auditing ✅ CSRF protection - Uses Laravel's CSRF tokens ✅ Warning messages - Visual indicators on login page ✅ 2FA respect - Honors 2FA by default (bypass is opt-in)

Best Practices

❌ Never enable in production ✅ Use environment-specific .env files ✅ Add to .env.example with safe defaults ✅ Enable IP whitelist in shared staging environments ✅ Keep logging enabled for security auditing ✅ Only bypass 2FA in local environments

Troubleshooting

Buttons not appearing

1. Check APP_ENV - Must be local or staging (or set DEVELOPER_LOGINS_ENABLED=true)
2. Verify users exist in database with configured emails
3. Clear config cache: php artisan config:clear
4. Check logs: storage/logs/laravel.log

"User not found" error

Ensure the configured email/username exists in your database:

php artisan tinker
>>> User::where('email', 'admin@example.com')->first();

IP whitelist blocking access

Check your IP address:

curl ifconfig.me

Add it to .env:

DEVELOPER_LOGINS_ALLOWED_IPS=127.0.0.1,::1,YOUR_IP_HERE

Production exception

If you see ConfigurationException: Developer logins should not be enabled in production!:

1. Set APP_ENV=production in .env
2. Or set DEVELOPER_LOGINS_ENABLED=false
3. Or set prevent_production => false in config (not recommended)

Testing

composer test

Changelog

Please see CHANGELOG for recent changes.

Contributing

Contributions are welcome! Please see CONTRIBUTING for details.

Security Vulnerabilities

If you discover a security vulnerability, please email security@example.com.

Credits

• Jose Vicente
• Inspired by dutchcodingcompany/filament-developer-logins

License

The MIT License (MIT). Please see License File for more information.