fusengine 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
ifchecks - 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:sanctummiddleware 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
verifiedmiddleware 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