Agent Skills: Laravel Authentication & Authorization

Laravel Authentication & Authorization

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

1. fuse-ai-pilot:explore-codebase - Check existing auth setup, guards, policies
2. fuse-ai-pilot:research-expert - Verify latest Laravel 12 auth docs via Context7
3. 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

1. Use policies for model authorization - Not inline if checks
2. Always hash passwords - Hash::make() or 'hashed' cast
3. Regenerate session after login - Prevents fixation attacks
4. Use HTTPS in production - Required for secure cookies
5. 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