Laravel Authentication Explained — Starter Kits, Guards, and Custom Auth

<?php

return [

    /*
    |--------------------------------------------------------------------------
    | Default Authentication Guard
    |--------------------------------------------------------------------------
    | This is the guard Laravel uses when you call Auth::check() or
    | auth()->user() without specifying which guard to use.
    | For a classic web app, 'web' is correct.
    | For a pure API, change this to 'api'.
    */
    'defaults' => [
        'guard'     => 'web',   // <-- the active guard for browser sessions
        'passwords' => 'users', // <-- which password-reset broker to use
    ],

    /*
    |--------------------------------------------------------------------------
    | Guards
    |--------------------------------------------------------------------------
    | Each guard pairs a *driver* (how auth state is stored) with a
    | *provider* (where user records live).
    */
    'guards' => [
        'web' => [
            'driver'   => 'session',  // stores auth state in the PHP session
            'provider' => 'users',    // uses the 'users' provider below
        ],

        'api' => [
            'driver'   => 'token',    // reads a Bearer token from the request
            'provider' => 'users',
            'hash'     => false,      // set to true if you hash API tokens in DB
        ],

        // Custom admin guard — completely isolated from the 'web' guard
        'admin' => [
            'driver'   => 'session',
            'provider' => 'admins',   // separate provider for admin users
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | User Providers
    |--------------------------------------------------------------------------
    | Providers tell Laravel *how* to retrieve users from storage.
    | 'eloquent' uses your model class; 'database' uses raw table queries.
    */
    'providers' => [
        'users' => [
            'driver' => 'eloquent',
            'model'  => App\Models\User::class, // must implement Authenticatable
        ],

        'admins' => [
            'driver' => 'eloquent',
            'model'  => App\Models\Admin::class, // separate admin model
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Password Reset Configuration
    |--------------------------------------------------------------------------
    | Controls the token expiry (in minutes) and the table that stores tokens.
    */
    'passwords' => [
        'users' => [
            'provider' => 'users',
            'table'    => 'password_reset_tokens', // Laravel 10+ renamed this table
            'expire'   => 60,   // token expires after 60 minutes
            'throttle' => 60,   // can only request a new token every 60 seconds
        ],
    ],

    'password_timeout' => 10800, // re-confirm password after 3 hours (in seconds)

];

# --- Install Laravel Breeze ---
# Step 1: Require the package (development dependency only)
composer require laravel/breeze --dev

# Step 2: Scaffold the auth views and controllers.
# Options: blade | react | vue | api | livewire | livewire-functional
php artisan breeze:install blade

# Step 3: Run migrations — creates users, sessions, password_reset_tokens tables
php artisan migrate

# Step 4: Compile front-end assets (Breeze uses Tailwind CSS)
npm install && npm run dev

# --- What Breeze actually generates ---
# Routes:       routes/auth.php (included automatically in routes/web.php)
# Controllers:  app/Http/Controllers/Auth/  (8 focused controllers)
# Views:        resources/views/auth/  (login, register, forgot-password, etc.)
# Middleware:   already wired — 'auth' middleware redirects guests to /login
#               'guest' middleware redirects authenticated users to /dashboard

# Verify everything is wired by listing all registered routes:
php artisan route:list --path=auth

<?php

namespace App\Http\Controllers\Auth;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Http\RedirectResponse;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\RateLimiter;
use Illuminate\Support\Str;
use Illuminate\Validation\ValidationException;

class CustomLoginController extends Controller
{
    /**
     * Show the login form.
     * The 'guest' middleware (defined in Kernel.php) ensures
     * already-authenticated users are bounced to /dashboard
     * before they even reach this method.
     */
    public function showLoginForm()
    {
        return view('auth.login');
    }

    /**
     * Handle a login attempt.
     * We validate, rate-limit, attempt auth, then redirect.
     */
    public function login(Request $request): RedirectResponse
    {
        // 1. Validate the incoming fields before we touch the database
        $credentials = $request->validate([
            'email'    => ['required', 'email'],
            'password' => ['required', 'string'],
        ]);

        // 2. Build a per-user, per-IP rate limit key.
        //    Using BOTH email and IP makes it much harder to brute-force
        //    from rotating IPs or enumerate valid emails.
        $rateLimitKey = Str::lower($request->input('email')) . '|' . $request->ip();

        // 3. Reject the attempt if they've failed 5 times in the last 60 seconds
        if (RateLimiter::tooManyAttempts($rateLimitKey, maxAttempts: 5)) {
            $secondsRemaining = RateLimiter::availableIn($rateLimitKey);

            // Throw a ValidationException — Laravel formats this nicely
            // in both Blade views and JSON responses automatically
            throw ValidationException::withMessages([
                'email' => __('auth.throttle', ['seconds' => $secondsRemaining]),
            ]);
        }

        // 4. Auth::attempt() does three things in one call:
        //    a) Looks up the user by email via the Eloquent provider
        //    b) Runs Hash::check($password, $user->password)
        //    c) If both match: writes the user ID to the session and returns true
        //
        // The second argument (boolean) controls "remember me" —
        // true creates a persistent cookie valid for years (configurable).
        $rememberMe = $request->boolean('remember');

        if (Auth::attempt($credentials, $rememberMe)) {
            // 5. Regenerate the session ID to prevent session fixation attacks.
            //    This is critical — always do this after a successful login.
            $request->session()->regenerate();

            // 6. Clear the rate limit hit counter on successful login
            RateLimiter::clear($rateLimitKey);

            // 7. intended() redirects to the URL the user was trying to reach
            //    before the 'auth' middleware kicked them to /login.
            //    If there's no intended URL, it falls back to /dashboard.
            return redirect()->intended(route('dashboard'));
        }

        // 8. Failed attempt — increment the rate limiter counter
        RateLimiter::hit($rateLimitKey, decay: 60); // 60 second decay window

        // 9. Return a generic error message.
        //    NEVER say 'wrong password' or 'user not found' separately —
        //    that tells attackers which emails are registered (user enumeration).
        throw ValidationException::withMessages([
            'email' => __('auth.failed'), // "These credentials do not match our records."
        ]);
    }

    /**
     * Log the user out.
     * Three steps: logout from Auth, invalidate the session, regenerate the CSRF token.
     * Skipping any one of these leaves a security gap.
     */
    public function logout(Request $request): RedirectResponse
    {
        Auth::logout(); // clears the auth data from the session

        $request->session()->invalidate();       // destroy the session entirely
        $request->session()->regenerateToken();  // issue a new CSRF token

        return redirect()->route('login');
    }
}

<?php
// ============================================================
// FILE 1: routes/web.php — protecting routes with middleware
// ============================================================

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\DashboardController;
use App\Http\Controllers\ProfileController;
use App\Http\Controllers\Admin\AdminDashboardController;

// Public route — no middleware, anyone can access
Route::get('/', fn() => view('welcome'))->name('home');

// Single protected route
Route::get('/dashboard', [DashboardController::class, 'index'])
    ->middleware('auth')          // redirects guests to /login
    ->name('dashboard');

// Group of protected routes — cleaner than repeating middleware
Route::middleware(['auth', 'verified'])->group(function () {
    // 'verified' means the user must also have confirmed their email
    Route::get('/profile', [ProfileController::class, 'show'])->name('profile.show');
    Route::put('/profile', [ProfileController::class, 'update'])->name('profile.update');
    Route::delete('/profile', [ProfileController::class, 'destroy'])->name('profile.destroy');
});

// Multi-guard example: admin area uses a separate 'admin' guard
// This guard would be defined in config/auth.php with its own provider
Route::middleware('auth:admin')->prefix('admin')->group(function () {
    Route::get('/dashboard', [AdminDashboardController::class, 'index'])
        ->name('admin.dashboard');
});


// ============================================================
// FILE 2: app/Http/Controllers/DashboardController.php
// Checking auth state inside a controller
// ============================================================

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

class DashboardController extends Controller
{
    public function index(Request $request)
    {
        // Auth::user() returns the currently authenticated User model.
        // Since this route is behind 'auth' middleware, we know it's never null here.
        // But in code that might run for guests too, always null-check first.
        $currentUser = Auth::user();

        // auth()->id() is shorthand for Auth::id() — returns the primary key only.
        // Use this when you just need the ID for a query (avoids loading the full model).
        $userId = auth()->id();

        // You can also pull the user off the Request object.
        // Useful in Form Requests and Middleware where $request is already injected.
        $userFromRequest = $request->user();

        return view('dashboard', [
            'user'        => $currentUser,
            'recentPosts' => $currentUser->posts()->latest()->take(5)->get(),
        ]);
    }
}


// ============================================================
// FILE 3: resources/views/layouts/navigation.blade.php
// Conditional rendering based on auth state in Blade
// ============================================================

/*
<nav>
    {{-- @auth renders its contents ONLY for authenticated users --}}
    @auth
        <span>Welcome, {{ Auth::user()->name }}</span>
        <form method="POST" action="{{ route('logout') }}">
            @csrf
            <button type="submit">Log Out</button>
        </form>
    @endauth

    {{-- @guest renders its contents ONLY for unauthenticated visitors --}}
    @guest
        <a href="{{ route('login') }}">Log In</a>
        <a href="{{ route('register') }}">Register</a>
    @endguest

    {{-- Multi-guard check in Blade: check a specific guard --}}
    @auth('admin')
        <a href="{{ route('admin.dashboard') }}">Admin Panel</a>
    @endauth
</nav>
*/

<?php

// ============================================================
// Step 1: Install and configure Sanctum
// ============================================================
// composer require laravel/sanctum
// php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
// php artisan migrate

// ============================================================
// Step 2: routes/api.php — protect API routes with Sanctum
// ============================================================

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Api\ProfileController;
use App\Http\Controllers\Api\PostController;

// Public API routes — no authentication required
Route::get('/posts', [PostController::class, 'index']);
Route::get('/posts/{post}', [PostController::class, 'show']);

// Protected API routes — requires valid Sanctum token or session cookie
Route::middleware('auth:sanctum')->group(function () {
    Route::get('/user', fn($request) => $request->user());
    Route::put('/profile', [ProfileController::class, 'update']);
    Route::post('/posts', [PostController::class, 'store']);
    Route::delete('/posts/{post}', [PostController::class, 'destroy']);
});

// ============================================================
// Step 3: Token issuance — user generates a token via UI
// ============================================================

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;

class TokenController extends Controller
{
    /**
     * Issue a new API token with specific abilities.
     * The token is returned ONCE — store it securely on the client.
     */
    public function store(Request $request): JsonResponse
    {
        $request->validate([
            'name' => 'required|string|max:255',
            'abilities' => 'array|nullable',
        ]);

        $token = $request->user()->createToken(
            $request->input('name', 'api-token'),
            $request->input('abilities', ['read', 'write'])
        );

        return response()->json([
            'token' => $token->plainTextToken, // shown ONCE — never stored in plain text
            'abilities' => $token->accessToken->abilities,
        ], 201);
    }

    /**
     * Revoke a specific token.
     */
    public function destroy(Request $request, int $tokenId): JsonResponse
    {
        $request->user()->tokens()->where('id', $tokenId)->delete();

        return response()->json(['message' => 'Token revoked.']);
    }

    /**
     * Revoke all tokens (nuclear option — used on password change).
     */
    public function destroyAll(Request $request): JsonResponse
    {
        $request->user()->tokens()->delete();

        return response()->json(['message' => 'All tokens revoked.']);
    }
}

<?php

// ============================================================
// config/hashing.php — password hashing configuration
// ============================================================

return [
    'driver' => 'bcrypt',
    'bcrypt' => [
        'rounds' => env('BCRYPT_ROUNDS', 10), // increase to 12 for high-security
    ],
    'argon' => [
        'memory' => 65536, // 64MB — Argon2 memory cost
        'threads' => 1,    // parallelism
        'time' => 4,       // time cost
    ],
];

// ============================================================
// config/session.php — session security settings
// ============================================================

return [
    'driver'          => env('SESSION_DRIVER', 'redis'), // redis for production
    'lifetime'        => env('SESSION_LIFETIME', 120),   // minutes
    'expire_on_close' => false,                          // true for public computers
    'encrypt'         => false,                          // true if session data is sensitive
    'secure'          => env('SESSION_SECURE_COOKIE', true),  // HTTPS only — MUST be true
    'http_only'       => true,  // JS cannot access cookie — MUST be true
    'same_site'       => env('SESSION_SAME_SITE', 'lax'), // lax recommended
    'cookie'          => env('SESSION_COOKIE', '__Host-laravel_session'),
    'domain'          => env('SESSION_DOMAIN', null),     // null required for __Host- prefix
    'path'            => '/',                             // '/' required for __Host- prefix
];

// ============================================================
// Middleware: force password re-confirmation for sensitive actions
// ============================================================

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Carbon;
use Symfony\Component\HttpFoundation\Response;

class PasswordConfirmedRecently
{
    /**
     * Ensure the user confirmed their password within the last 3 hours.
     * Used for sensitive actions: changing email, deleting account, viewing API keys.
     */
    public function handle(Request $request, Closure $next): Response
    {
        if (!session()->has('password_confirmed_at')) {
            return redirect()->route('password.confirm');
        }

        $confirmedAt = Carbon::createFromTimestamp(session('password_confirmed_at'));

        if ($confirmedAt->addSeconds(config('auth.password_timeout', 10800))->isPast()) {
            return redirect()->route('password.confirm');
        }

        return $next($request);
    }
}