Laravel Authentication & Authorization
Agent Workflow (MANDATORY)
Before ANY implementation, launch in parallel:
- 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
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
1---2name: laravel-auth3description: Use when implementing user authentication, API tokens, social login, or authorization. Covers Sanctum, Passport, Socialite, Fortify, policies, and gates for Laravel 12.4versions:5 laravel: "12.x"6 sanctum: "4.0"7 php: "8.4"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/aibot88/laravel-auth13---1415# Laravel Authentication & Authorization1617## Agent Workflow (MANDATORY)1819Before ANY implementation, launch in parallel:20211. **fuse-ai-pilot:explore-codebase** - Check existing auth setup, guards, policies222. **fuse-ai-pilot:research-expert** - Verify latest Laravel 12 auth docs via Context7233. **mcp__context7__query-docs** - Query specific patterns (Sanctum, Passport, etc.)2425After implementation, run **fuse-ai-pilot:sniper** for validation.2627---2829## Overview3031Laravel provides a complete authentication and authorization ecosystem. Choose based on your needs:3233| Package | Best For | Complexity |34|---------|----------|------------|35| **Starter Kits** | New projects, quick setup | Low |36| **Sanctum** | API tokens, SPA auth | Low |37| **Fortify** | Custom UI, headless backend | Medium |38| **Passport** | OAuth2 server, third-party access | High |39| **Socialite** | Social login (Google, GitHub) | Low |4041---4243## Critical Rules44451. **Use policies for model authorization** - Not inline `if` checks462. **Always hash passwords** - `Hash::make()` or `'hashed'` cast473. **Regenerate session after login** - Prevents fixation attacks484. **Use HTTPS in production** - Required for secure cookies495. **Define token abilities** - Principle of least privilege5051---5253## Architecture5455```56app/57├── Http/58│ ├── Controllers/59│ │ └── Auth/ ← Auth controllers (if manual)60│ └── Middleware/61│ └── Authenticate.php ← Redirects unauthenticated62├── Models/63│ └── User.php ← HasApiTokens trait (Sanctum)64├── Policies/ ← Authorization policies65│ └── PostPolicy.php66├── Providers/67│ └── AppServiceProvider.php ← Gate definitions68└── Actions/69 └── Fortify/ ← Fortify actions (if used)70 ├── CreateNewUser.php71 └── ResetUserPassword.php7273config/74├── auth.php ← Guards & providers75├── sanctum.php ← API token config76└── fortify.php ← Fortify features77```7879---8081## FuseCore Integration8283When working in a **FuseCore project**, authentication follows the modular structure:8485```86FuseCore/87├── Core/ # Infrastructure (priority 0)88│ └── App/Contracts/89│ └── AuthServiceInterface.php ← Auth contract90│91├── User/ # Auth module (existing)92│ ├── App/93│ │ ├── Models/User.php ← HasApiTokens trait94│ │ ├── Http/95│ │ │ ├── Controllers/96│ │ │ │ ├── AuthController.php97│ │ │ │ └── TokenController.php98│ │ │ ├── Requests/99│ │ │ │ ├── LoginRequest.php100│ │ │ │ └── RegisterRequest.php101│ │ │ └── Resources/UserResource.php102│ │ ├── Policies/UserPolicy.php103│ │ └── Services/AuthService.php104│ ├── Config/105│ │ └── sanctum.php ← Sanctum config (module-level)106│ ├── Database/Migrations/107│ ├── Routes/api.php ← Auth routes108│ └── module.json # dependencies: []109│110└── {YourModule}/ # Depends on User module111 ├── App/Policies/ ← Module-specific policies112 └── module.json # dependencies: ["User"]113```114115### FuseCore Auth Checklist116117- [ ] Auth code in `/FuseCore/User/` module118- [ ] Policies in module's `/App/Policies/`119- [ ] Auth routes in `/FuseCore/User/Routes/api.php`120- [ ] Sanctum config in `/FuseCore/User/Config/sanctum.php`121- [ ] Declare `"User"` dependency in other modules' `module.json`122- [ ] Use `auth:sanctum` middleware in module routes123124### Cross-Module Authorization125126```php127// In FuseCore/{Module}/Routes/api.php128Route::middleware(['api', 'auth:sanctum'])->group(function () {129 Route::apiResource('posts', PostController::class);130});131132// In FuseCore/{Module}/App/Http/Controllers/PostController.php133public function update(UpdatePostRequest $request, Post $post)134{135 $this->authorize('update', $post); // Uses PostPolicy136 // ...137}138```139140→ See [fusecore skill](../fusecore/SKILL.md) for complete module patterns.141142---143144## Decision Guide145146### Authentication Method147148```149Need auth scaffolding? → Starter Kit150├── Yes → Use React/Vue/Livewire starter kit151└── No → Building custom frontend?152 ├── Yes → Use Fortify (headless)153 └── No → API only?154 ├── Yes → Sanctum (tokens)155 └── No → Session-based156```157158### Token Type159160```161Third-party apps need access? → Passport (OAuth2)162├── No → Mobile app?163│ ├── Yes → Sanctum API tokens164│ └── No → SPA on same domain?165│ ├── Yes → Sanctum SPA auth (cookies)166│ └── No → Sanctum API tokens167```168169---170171## Key Concepts172173| Concept | Description | Reference |174|---------|-------------|-----------|175| **Guards** | Define HOW users authenticate (session, token) | [authentication.md](references/authentication.md) |176| **Providers** | Define WHERE users are retrieved from (database) | [authentication.md](references/authentication.md) |177| **Gates** | Closure-based authorization for simple checks | [authorization.md](references/authorization.md) |178| **Policies** | Class-based authorization tied to models | [authorization.md](references/authorization.md) |179| **Abilities** | Token permissions (Sanctum/Passport scopes) | [sanctum.md](references/sanctum.md) |180181---182183## Reference Guide184185### Concepts (WHY & Architecture)186187| Topic | Reference | When to Consult |188|-------|-----------|-----------------|189| **Authentication** | [authentication.md](references/authentication.md) | Guards, providers, login flow |190| **Authorization** | [authorization.md](references/authorization.md) | Gates vs policies, access control |191| **Sanctum** | [sanctum.md](references/sanctum.md) | API tokens, SPA authentication |192| **Passport** | [passport.md](references/passport.md) | OAuth2 server, third-party access |193| **Fortify** | [fortify.md](references/fortify.md) | Headless auth, 2FA |194| **Socialite** | [socialite.md](references/socialite.md) | Social login providers |195| **Starter Kits** | [starter-kits.md](references/starter-kits.md) | Auth scaffolding |196| **Email Verification** | [verification.md](references/verification.md) | MustVerifyEmail, verified middleware |197| **Password Reset** | [passwords.md](references/passwords.md) | Forgot password flow |198| **Session** | [session.md](references/session.md) | Session drivers, flash data |199| **CSRF** | [csrf.md](references/csrf.md) | Form protection, AJAX tokens |200| **Encryption** | [encryption.md](references/encryption.md) | Data encryption (not passwords) |201| **Hashing** | [hashing.md](references/hashing.md) | Password hashing |202203### Templates (Complete Code)204205| Template | When to Use |206|----------|-------------|207| [LoginController.php.md](references/templates/LoginController.php.md) | Manual authentication controllers |208| [GatesAndPolicies.php.md](references/templates/GatesAndPolicies.php.md) | Gates and policy examples |209| [PostPolicy.php.md](references/templates/PostPolicy.php.md) | Complete policy class with before filter |210| [sanctum-setup.md](references/templates/sanctum-setup.md) | Sanctum configuration + testing |211| [PassportSetup.php.md](references/templates/PassportSetup.php.md) | OAuth2 server setup |212| [FortifySetup.php.md](references/templates/FortifySetup.php.md) | Fortify configuration + 2FA |213| [SocialiteController.php.md](references/templates/SocialiteController.php.md) | Social login + testing |214| [PasswordResetController.php.md](references/templates/PasswordResetController.php.md) | Password reset flow |215216---217218## Best Practices219220### DO221- Use starter kits for new projects222- Define policies for all models223- Set token expiration224- Rate limit login attempts225- Use `verified` middleware for sensitive actions226- Prune expired tokens regularly227228### DON'T229- Store plain text passwords230- Skip session regeneration on login231- Use Passport when Sanctum suffices232- Forget to prune expired tokens233- Ignore HTTPS in production234- Put authorization logic in controllers