Laravel Sanctum für PHP: Komplettguide zu API-Tokens und SPA-Authentifizierung

1. Was ist Laravel Sanctum und wozu braucht man es?

Laravel Sanctum ist eine schlanke Authentifizierungsbibliothek für das PHP-Framework Laravel, die speziell für die Verwaltung von API-Tokens und Single-Page-Anwendungen (SPA) entwickelt wurde. Entwickelt von Taylor Otwell und dem Laravel-Team, bietet Sanctum eine einfache, aber leistungsstarke Möglichkeit, API-Routen zu schützen. Entwickler können damit schnell eine Authentifizierung implementieren, ohne die komplexe Konfiguration schwererer Lösungen wie Passport (OAuth2) in Kauf nehmen zu müssen.

Die Hauptaufgabe von Sanctum besteht darin, zwei zentrale Herausforderungen der modernen Webentwicklung zu lösen: die Authentifizierung für SPAs (Single Page Applications), die auf derselben Domain wie das Backend laufen, und die Ausgabe von API-Tokens für mobile Apps oder Drittanbieterdienste. Im Gegensatz zu Passport verwendet Sanctum kein vollwertiges OAuth2-Protokoll, was es zur idealen Wahl für Projekte macht, die kein komplexes Zugriffsdelegierungssystem benötigen. Für die SPA-Authentifizierung nutzt es Laravel-Sessions und für die API einfache HMAC-basierte Tokens.

Die Bibliothek ist ab Laravel 8 standardmäßig enthalten und somit "out of the box" verfügbar. Sanctum ist besonders nützlich für Startups, kleine Teams und Projekte, bei denen Entwicklungsgeschwindigkeit und minimale Abhängigkeiten im Vordergrund stehen. Es verwaltet automatisch die Token-Gültigkeit, unterstützt "Abilities" (Fähigkeiten) zur feingranularen Rechteverwaltung und lässt sich problemlos mit Laravel Fortify, Breeze oder Jetstream integrieren.

2. Installation

Laravel Sanctum wird über Composer installiert, den Standard-Paketmanager für PHP. Stellen Sie sicher, dass PHP 8.0 oder höher sowie Laravel 8.x/9.x/10.x/11.x installiert sind.

Der genaue Befehl zur Installation lautet:

composer require laravel/sanctum

Nach der Installation müssen Sie die Konfigurationsdatei und die Datenbankmigrationen veröffentlichen:

php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"

Führen Sie anschließend die Migrationen aus, um die Tabelle personal_access_tokens zu erstellen:

php artisan migrate

Für die SPA-Authentifizierung müssen Sie zusätzlich die Middleware EnsureFrontendRequestsAreStateful zum HTTP-Kernel hinzufügen (Datei app/Http/Kernel.php):

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

Geben Sie außerdem in der .env-Datei die Domain Ihrer SPA an:

SANCTUM_STATEFUL_DOMAINS=localhost:8080

3. Schnellstart – Minimales Arbeitsbeispiel

Betrachten wir ein minimales Beispiel zur Ausgabe eines API-Tokens und zum Schutz einer Route.

Schritt 1: User-Modell

Verwenden Sie im Modell App\Models\User das Trait HasApiTokens:

validate([
        'email' => 'required|email',
        'password' => 'required',
    ]);

    if (auth()->attempt($credentials)) {
        $user = auth()->user();
        $token = $user->createToken('api-token')->plainTextToken;
        
        return response()->json([
            'token' => $token,
            'user' => $user
        ]);
    }