Laravel Authentication & Authorization

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

fuse-ai-pilot:explore-codebase - Check existing auth setup, guards, policies
fuse-ai-pilot:research-expert - Verify latest Laravel 12 auth docs via Context7
mcp__context7__query-docs - Query specific patterns (Sanctum, Passport, etc.)

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

Laravel provides a complete authentication and authorization ecosystem. Choose based on your needs:

Package	Best For	Complexity
Starter Kits	New projects, quick setup	Low
Sanctum	API tokens, SPA auth	Low
Fortify	Custom UI, headless backend	Medium
Passport	OAuth2 server, third-party access	High
Socialite	Social login (Google, GitHub)	Low

Critical Rules

Use policies for model authorization - Not inline if checks
Always hash passwords - Hash::make() or 'hashed' cast
Regenerate session after login - Prevents fixation attacks
Use HTTPS in production - Required for secure cookies
Define token abilities - Principle of least privilege

Architecture

app/
├── Http/
│   ├── Controllers/
│   │   └── Auth/              ← Auth controllers (if manual)
│   └── Middleware/
│       └── Authenticate.php   ← Redirects unauthenticated
├── Models/
│   └── User.php               ← HasApiTokens trait (Sanctum)
├── Policies/                  ← Authorization policies
│   └── PostPolicy.php
├── Providers/
│   └── AppServiceProvider.php ← Gate definitions
└── Actions/
    └── Fortify/               ← Fortify actions (if used)
        ├── CreateNewUser.php
        └── ResetUserPassword.php

config/
├── auth.php                   ← Guards & providers
├── sanctum.php                ← API token config
└── fortify.php                ← Fortify features

FuseCore Integration

When working in a FuseCore project, authentication follows the modular structure:

FuseCore/
├── Core/                      # Infrastructure (priority 0)
│   └── App/Contracts/
│       └── AuthServiceInterface.php  ← Auth contract
│
├── User/                      # Auth module (existing)
│   ├── App/
│   │   ├── Models/User.php    ← HasApiTokens trait
│   │   ├── Http/
│   │   │   ├── Controllers/
│   │   │   │   ├── AuthController.php
│   │   │   │   └── TokenController.php
│   │   │   ├── Requests/
│   │   │   │   ├── LoginRequest.php
│   │   │   │   └── RegisterRequest.php
│   │   │   └── Resources/UserResource.php
│   │   ├── Policies/UserPolicy.php
│   │   └── Services/AuthService.php
│   ├── Config/
│   │   └── sanctum.php        ← Sanctum config (module-level)
│   ├── Database/Migrations/
│   ├── Routes/api.php         ← Auth routes
│   └── module.json            # dependencies: []
│
└── {YourModule}/              # Depends on User module
    ├── App/Policies/          ← Module-specific policies
    └── module.json            # dependencies: ["User"]

FuseCore Auth Checklist

Auth code in /FuseCore/User/ module
Policies in module's /App/Policies/
Auth routes in /FuseCore/User/Routes/api.php
Sanctum config in /FuseCore/User/Config/sanctum.php
Declare "User" dependency in other modules' module.json
Use auth:sanctum middleware in module routes

Cross-Module Authorization

// In FuseCore/{Module}/Routes/api.php
Route::middleware(['api', 'auth:sanctum'])->group(function () {
    Route::apiResource('posts', PostController::class);
});

// In FuseCore/{Module}/App/Http/Controllers/PostController.php
public function update(UpdatePostRequest $request, Post $post)
{
    $this->authorize('update', $post);  // Uses PostPolicy
    // ...
}

→ See fusecore skill for complete module patterns.

Decision Guide

Authentication Method

Need auth scaffolding? → Starter Kit
├── Yes → Use React/Vue/Livewire starter kit
└── No → Building custom frontend?
    ├── Yes → Use Fortify (headless)
    └── No → API only?
        ├── Yes → Sanctum (tokens)
        └── No → Session-based

Token Type

Third-party apps need access? → Passport (OAuth2)
├── No → Mobile app?
│   ├── Yes → Sanctum API tokens
│   └── No → SPA on same domain?
│       ├── Yes → Sanctum SPA auth (cookies)
│       └── No → Sanctum API tokens

Key Concepts

Concept	Description	Reference
Guards	Define HOW users authenticate (session, token)	authentication.md
Providers	Define WHERE users are retrieved from (database)	authentication.md
Gates	Closure-based authorization for simple checks	authorization.md
Policies	Class-based authorization tied to models	authorization.md
Abilities	Token permissions (Sanctum/Passport scopes)	sanctum.md

Reference Guide

Concepts (WHY & Architecture)

Topic	Reference	When to Consult
Authentication	authentication.md	Guards, providers, login flow
Authorization	authorization.md	Gates vs policies, access control
Sanctum	sanctum.md	API tokens, SPA authentication
Passport	passport.md	OAuth2 server, third-party access
Fortify	fortify.md	Headless auth, 2FA
Socialite	socialite.md	Social login providers
Starter Kits	starter-kits.md	Auth scaffolding
Email Verification	verification.md	MustVerifyEmail, verified middleware
Password Reset	passwords.md	Forgot password flow
Session	session.md	Session drivers, flash data
CSRF	csrf.md	Form protection, AJAX tokens
Encryption	encryption.md	Data encryption (not passwords)
Hashing	hashing.md	Password hashing

Templates (Complete Code)

Template	When to Use
LoginController.php.md	Manual authentication controllers
GatesAndPolicies.php.md	Gates and policy examples
PostPolicy.php.md	Complete policy class with before filter
sanctum-setup.md	Sanctum configuration + testing
PassportSetup.php.md	OAuth2 server setup
FortifySetup.php.md	Fortify configuration + 2FA
SocialiteController.php.md	Social login + testing
PasswordResetController.php.md	Password reset flow

Best Practices

DO

Use starter kits for new projects
Define policies for all models
Set token expiration
Rate limit login attempts
Use verified middleware for sensitive actions
Prune expired tokens regularly

DON'T

Store plain text passwords
Skip session regeneration on login
Use Passport when Sanctum suffices
Forget to prune expired tokens
Ignore HTTPS in production
Put authorization logic in controllers

laravel-auth