Laravel Authentication & Authorization
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Check existing auth setup, guards, policies
- fuse-ai-pilot:research-expert - Verify latest Laravel 13 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
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 13 Notes
PreventRequestForgery (ex-VerifyCsrfToken)
Laravel 13 renomme VerifyCsrfToken en PreventRequestForgery. Le middleware utilise une vérification origin-aware (vérifie Origin/Referer en plus du token CSRF) pour bloquer les attaques CSRF cross-origin sur les routes stateful.
// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
$middleware->validateOrigin(except: ['stripe/*', 'webhook/*']);
})
- Migrer toute référence
VerifyCsrfToken::class → PreventRequestForgery::class
- Property
$except reste compatible mais préférer validateOrigin(except: [...])
- Les APIs stateless (Sanctum tokens) ne sont pas affectées
1---2name: laravel-auth3description: Use when implementing user authentication, API tokens, social login, or authorization in Laravel 13.4versions:5 laravel: "13.0"6 sanctum: "4.0"7 php: "8.3"8user-invocable: true9references: references/authentication.md, references/authorization.md, references/sanctum.md, references/passport.md, references/fortify.md, references/socialite.md, references/starter-kits.md, references/verification.md, references/passwords.md, references/session.md, references/csrf.md, references/encryption.md, references/hashing.md, references/templates/LoginController.php.md, references/templates/GatesAndPolicies.php.md, references/templates/PostPolicy.php.md, references/templates/sanctum-setup.md, references/templates/PassportSetup.php.md, references/templates/FortifySetup.php.md, references/templates/SocialiteController.php.md, references/templates/PasswordResetController.php.md10related-skills: laravel-api, laravel-permission, fusecore11metadata:12 source: https://skillmd.com/skills/fusengine/laravel-auth13---1415<objective>16Covers the Laravel 13 authentication and authorization ecosystem: Sanctum17(API tokens, SPA auth), Passport (OAuth2 server), Fortify (headless18custom-UI auth), Socialite (social login), starter kits, policies and gates,19email verification, password reset, session management, CSRF /20PreventRequestForgery, encryption, and hashing. Includes FuseCore modular-21project integration patterns for auth (User module, cross-module22authorization via policies).23</objective>2425# Laravel Authentication & Authorization2627## Agent Workflow (MANDATORY)2829Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:30311. **fuse-ai-pilot:explore-codebase** - Check existing auth setup, guards, policies322. **fuse-ai-pilot:research-expert** - Verify latest Laravel 13 auth docs via Context7333. **mcp__context7__query-docs** - Query specific patterns (Sanctum, Passport, etc.)3435After implementation, run **fuse-ai-pilot:sniper** for validation.3637---3839## Overview4041Laravel provides a complete authentication and authorization ecosystem. Choose based on your needs:4243| Package | Best For | Complexity |44|---------|----------|------------|45| **Starter Kits** | New projects, quick setup | Low |46| **Sanctum** | API tokens, SPA auth | Low |47| **Fortify** | Custom UI, headless backend | Medium |48| **Passport** | OAuth2 server, third-party access | High |49| **Socialite** | Social login (Google, GitHub) | Low |5051---5253## Critical Rules54551. **Use policies for model authorization** - Not inline `if` checks562. **Always hash passwords** - `Hash::make()` or `'hashed'` cast573. **Regenerate session after login** - Prevents fixation attacks584. **Use HTTPS in production** - Required for secure cookies595. **Define token abilities** - Principle of least privilege6061---6263## Architecture6465```66app/67├── Http/68│ ├── Controllers/69│ │ └── Auth/ ← Auth controllers (if manual)70│ └── Middleware/71│ └── Authenticate.php ← Redirects unauthenticated72├── Models/73│ └── User.php ← HasApiTokens trait (Sanctum)74├── Policies/ ← Authorization policies75│ └── PostPolicy.php76├── Providers/77│ └── AppServiceProvider.php ← Gate definitions78└── Actions/79 └── Fortify/ ← Fortify actions (if used)80 ├── CreateNewUser.php81 └── ResetUserPassword.php8283config/84├── auth.php ← Guards & providers85├── sanctum.php ← API token config86└── fortify.php ← Fortify features87```8889---9091## FuseCore Integration9293When working in a **FuseCore project**, authentication follows the modular structure:9495```96FuseCore/97├── Core/ # Infrastructure (priority 0)98│ └── App/Contracts/99│ └── AuthServiceInterface.php ← Auth contract100│101├── User/ # Auth module (existing)102│ ├── App/103│ │ ├── Models/User.php ← HasApiTokens trait104│ │ ├── Http/105│ │ │ ├── Controllers/106│ │ │ │ ├── AuthController.php107│ │ │ │ └── TokenController.php108│ │ │ ├── Requests/109│ │ │ │ ├── LoginRequest.php110│ │ │ │ └── RegisterRequest.php111│ │ │ └── Resources/UserResource.php112│ │ ├── Policies/UserPolicy.php113│ │ └── Services/AuthService.php114│ ├── Config/115│ │ └── sanctum.php ← Sanctum config (module-level)116│ ├── Database/Migrations/117│ ├── Routes/api.php ← Auth routes118│ └── module.json # dependencies: []119│120└── {YourModule}/ # Depends on User module121 ├── App/Policies/ ← Module-specific policies122 └── module.json # dependencies: ["User"]123```124125### FuseCore Auth Checklist126127- [ ] Auth code in `/FuseCore/User/` module128- [ ] Policies in module's `/App/Policies/`129- [ ] Auth routes in `/FuseCore/User/Routes/api.php`130- [ ] Sanctum config in `/FuseCore/User/Config/sanctum.php`131- [ ] Declare `"User"` dependency in other modules' `module.json`132- [ ] Use `auth:sanctum` middleware in module routes133134### Cross-Module Authorization135136```php137// In FuseCore/{Module}/Routes/api.php138Route::middleware(['api', 'auth:sanctum'])->group(function () {139 Route::apiResource('posts', PostController::class);140});141142// In FuseCore/{Module}/App/Http/Controllers/PostController.php143public function update(UpdatePostRequest $request, Post $post)144{145 $this->authorize('update', $post); // Uses PostPolicy146 // ...147}148```149150→ See [fusecore skill](../fusecore/SKILL.md) for complete module patterns.151152---153154## Decision Guide155156### Authentication Method157158```159Need auth scaffolding? → Starter Kit160├── Yes → Use React/Vue/Livewire starter kit161└── No → Building custom frontend?162 ├── Yes → Use Fortify (headless)163 └── No → API only?164 ├── Yes → Sanctum (tokens)165 └── No → Session-based166```167168### Token Type169170```171Third-party apps need access? → Passport (OAuth2)172├── No → Mobile app?173│ ├── Yes → Sanctum API tokens174│ └── No → SPA on same domain?175│ ├── Yes → Sanctum SPA auth (cookies)176│ └── No → Sanctum API tokens177```178179---180181## Key Concepts182183| Concept | Description | Reference |184|---------|-------------|-----------|185| **Guards** | Define HOW users authenticate (session, token) | [authentication.md](references/authentication.md) |186| **Providers** | Define WHERE users are retrieved from (database) | [authentication.md](references/authentication.md) |187| **Gates** | Closure-based authorization for simple checks | [authorization.md](references/authorization.md) |188| **Policies** | Class-based authorization tied to models | [authorization.md](references/authorization.md) |189| **Abilities** | Token permissions (Sanctum/Passport scopes) | [sanctum.md](references/sanctum.md) |190191---192193## Reference Guide194195### Concepts (WHY & Architecture)196197| Topic | Reference | When to Consult |198|-------|-----------|-----------------|199| **Authentication** | [authentication.md](references/authentication.md) | Guards, providers, login flow |200| **Authorization** | [authorization.md](references/authorization.md) | Gates vs policies, access control |201| **Sanctum** | [sanctum.md](references/sanctum.md) | API tokens, SPA authentication |202| **Passport** | [passport.md](references/passport.md) | OAuth2 server, third-party access |203| **Fortify** | [fortify.md](references/fortify.md) | Headless auth, 2FA |204| **Socialite** | [socialite.md](references/socialite.md) | Social login providers |205| **Starter Kits** | [starter-kits.md](references/starter-kits.md) | Auth scaffolding |206| **Email Verification** | [verification.md](references/verification.md) | MustVerifyEmail, verified middleware |207| **Password Reset** | [passwords.md](references/passwords.md) | Forgot password flow |208| **Session** | [session.md](references/session.md) | Session drivers, flash data |209| **CSRF** | [csrf.md](references/csrf.md) | Form protection, AJAX tokens |210| **Encryption** | [encryption.md](references/encryption.md) | Data encryption (not passwords) |211| **Hashing** | [hashing.md](references/hashing.md) | Password hashing |212213### Templates (Complete Code)214215| Template | When to Use |216|----------|-------------|217| [LoginController.php.md](references/templates/LoginController.php.md) | Manual authentication controllers |218| [GatesAndPolicies.php.md](references/templates/GatesAndPolicies.php.md) | Gates and policy examples |219| [PostPolicy.php.md](references/templates/PostPolicy.php.md) | Complete policy class with before filter |220| [sanctum-setup.md](references/templates/sanctum-setup.md) | Sanctum configuration + testing |221| [PassportSetup.php.md](references/templates/PassportSetup.php.md) | OAuth2 server setup |222| [FortifySetup.php.md](references/templates/FortifySetup.php.md) | Fortify configuration + 2FA |223| [SocialiteController.php.md](references/templates/SocialiteController.php.md) | Social login + testing |224| [PasswordResetController.php.md](references/templates/PasswordResetController.php.md) | Password reset flow |225226---227228## Best Practices229230### DO231- Use starter kits for new projects232- Define policies for all models233- Set token expiration234- Rate limit login attempts235- Use `verified` middleware for sensitive actions236- Prune expired tokens regularly237238### DON'T239- Store plain text passwords240- Skip session regeneration on login241- Use Passport when Sanctum suffices242- Forget to prune expired tokens243- Ignore HTTPS in production244- Put authorization logic in controllers245246---247248## Laravel 13 Notes249250### PreventRequestForgery (ex-VerifyCsrfToken)251Laravel 13 renomme `VerifyCsrfToken` en `PreventRequestForgery`. Le middleware utilise une vérification **origin-aware** (vérifie `Origin`/`Referer` en plus du token CSRF) pour bloquer les attaques CSRF cross-origin sur les routes stateful.252253```php254// bootstrap/app.php255->withMiddleware(function (Middleware $middleware) {256 $middleware->validateOrigin(except: ['stripe/*', 'webhook/*']);257})258```259260- Migrer toute référence `VerifyCsrfToken::class` → `PreventRequestForgery::class`261- Property `$except` reste compatible mais préférer `validateOrigin(except: [...])`262- Les APIs stateless (Sanctum tokens) ne sont pas affectées