Airlock Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/sanctum
   php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider" --tag="sanctum-config"
   php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider" --tag="sanctum-migrations"
   php artisan migrate
   

   • Run migrations to create personal_access_tokens table.

2. Middleware Setup: Add Sanctum middleware to app/Http/Kernel.php:

   'api' => [
       \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
       'throttle:api',
       \Illuminate\Routing\Middleware\SubstituteBindings::class,
   ],
   

   • Ensure api middleware group is applied to routes requiring auth.

3. First Use Case:

   • SPA Authentication:

     php artisan make:auth
     

     • Sanctum handles token generation automatically via LoginController (or custom auth logic).
   • API Token Generation:

     use Laravel\Sanctum\PersonalAccessToken;
     
     $token = PersonalAccessToken::createToken('token-name', $user);
     return $token->plainTextToken; // Return to frontend
     

Implementation Patterns

Core Workflows

1. Token-Based Authentication:

   • Frontend: Send Authorization: Bearer <token> in requests.
   • Backend: Sanctum auto-verifies tokens via HasApiTokens trait (applied to User model by default).
   • Example:

     Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
         return $request->user(); // Auto-resolved authenticated user
     });
     

2. Stateful Sessions (SPAs):

   • Sanctum tracks frontend sessions via X-XSRF-TOKEN header (CSRF protection).
   • Workflow:
     • Frontend fetches CSRF token from /sanctum/csrf-cookie.
     • Include token in subsequent requests (e.g., fetch('/sanctum/csrf-cookie').then(...)).

3. Token Management:

   • List Tokens:

     $user->tokens; // Collection of PersonalAccessToken models
     

   • Revoke Token:

     $token->delete();
     

4. Customizing Token Creation:

   • Extend PersonalAccessToken or use events:

     use Laravel\Sanctum\Events\PersonalAccessTokenCreated;
     
     PersonalAccessTokenCreated::dispatch($token, $abilities);
     

Integration Tips

• Laravel Passport: Sanctum is lighter; use Passport for OAuth2 needs.
• Testing: Use actingAs() with tokens:

  $user = User::factory()->create();
  $token = $user->createToken('test-token')->plainTextToken;
  
  $response = $this->withHeader('Authorization', 'Bearer '.$token)
                   ->get('/user');
  

• Rate Limiting: Combine with throttle middleware:

  Route::middleware(['throttle:60,1', 'auth:sanctum'])->get('/rate-limited');
  

Gotchas and Tips

Pitfalls

1. CSRF Token Mismatch:

   • Issue: Frontend forgets to fetch /sanctum/csrf-cookie before authenticated requests.
   • Fix: Ensure frontend includes CSRF token in all stateful requests (e.g., POST/PUT/DELETE).

2. Token Leaks:

   • Issue: Plain-text tokens exposed in logs or frontend code.
   • Fix:
     • Use .env for sensitive values (e.g., SANCTUM_STATEFUL_DOMAIN).
     • Frontend: Store tokens in HttpOnly cookies or secure memory (e.g., Vuex/Pinia).

3. Middleware Order:

   • Issue: auth:sanctum must run after EnsureFrontendRequestsAreStateful.
   • Fix: Verify app/Http/Kernel.php middleware order.

4. Token Expiration:

   • Issue: Tokens never expire by default.
   • Fix: Add TTL via PersonalAccessToken model:

     use Laravel\Sanctum\PersonalAccessToken;
     
     $token = PersonalAccessToken::createToken('test', $user, now()->addHours(1));
     

Debugging

• Token Validation Errors:

  • Check sanctum.token middleware logs for malformed tokens.
  • Validate SANCTUM_STATEFUL_DOMAIN matches frontend origin (e.g., localhost in dev).

• Database Issues:

  • Ensure personal_access_tokens table exists and has correct columns (tokenable_id, abilities, etc.).

Extension Points

1. Custom Token Models:

   • Extend PersonalAccessToken to add metadata:

     class CustomToken extends PersonalAccessToken {
         protected $casts = ['metadata' => 'array'];
     }
     

2. Token Events:

   • Listen for token creation/revocation:

     PersonalAccessTokenCreated::listen(function ($token, $abilities) {
         // Log or notify
     });
     

3. API Resource Filtering:

   • Scope tokens to specific routes:

     $token = $user->createToken('admin-token', ['admin']);
     // Then use `can()` in policies:
     public function handle(Request $request, Closure $next) {
         $request->user()->mustBeAdmin(); // Custom method
         return $next($request);
     }
     

4. Testing Tokens:

   • Mock tokens in tests:

     $this->actingAs($user, 'sanctum');
     // Or with a specific token:
     $this->withToken($token->plainTextToken);