Laravel Sanctum: Leitfaden zur API-Authentifizierung

Laravel Sanctum ist der einfachste Weg, einer modernen API Authentifizierung hinzuzufügen. Ohne die Komplexität von JWT-Bibliotheken oder die aufwendige Einrichtung von OAuth löst es zwei Anforderungen in einem einzigen Paket: API-Tokens für mobile Apps und Drittanbieter-Clients sowie cookiebasierte Sitzungen für SPAs wie React oder Vue, die auf derselben Domain laufen. In diesem Artikel richten wir beide Ansätze mit echtem, funktionierendem Code ein.

Wann und warum Sanctum?

Das Laravel-Ökosystem bietet drei Hauptoptionen für die Authentifizierung: Passport für Projekte, die einen vollständigen OAuth2-Server benötigen, externe Bibliotheken für zustandslose JWTs und Sanctum, die leichtgewichtige Lösung, die die meisten Anwendungen tatsächlich brauchen. Sanctum ist die richtige Wahl, wenn du dich in einer dieser Situationen befindest:

Du hast eine mobile App oder ein CLI-Tool und möchtest jeder Anfrage ein einfaches Bearer-Token anhängen.
Dein Frontend (SPA) läuft auf derselben Hauptdomain wie deine Laravel-API und du benötigst keinen echten OAuth-Flow.
Du möchtest Tokens fähigkeitsbasierte Berechtigungen (Abilities) erteilen — zum Beispiel ein Token, das nur lesen darf.

Wenn du eine für externe Entwickler offene Plattform baust, die OAuth2-Flows (Authorization Code, Client Credentials) erfordert, passt Passport besser. Für die meisten praktischen Szenarien ist Sanctum jedoch schneller einzurichten und wartungsärmer.

Installation

In Laravel 11 und 12 kommt Sanctum in einem einzigen Schritt über den Befehl install:api. Dieser Befehl veröffentlicht das Paket, fügt die Migration hinzu und bereitet die API-Routendatei vor:

php artisan install:api

Nach Ausführung des Befehls sind die Migrationen bereits gelaufen und die Tabelle personal_access_tokens wurde erstellt. Du musst nur das Trait HasApiTokens zu deinem User-Modell hinzufügen:

use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}

Dieses Trait stattet das Modell mit der Methode createToken() und der Beziehung tokens() aus. Jetzt können wir Tokens ausstellen.

API-Tokens ausstellen und verwenden

Das häufigste Szenario: Ein Benutzer meldet sich mit E-Mail und Passwort an, und du gibst ihm ein Token zurück. Der Client speichert es und sendet es bei nachfolgenden Anfragen über den Header Authorization: Bearer <token>. Ein einfacher Login-Controller sieht so aus:

use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;
use Illuminate\Support\Facades\Hash;
use App\Models\User;

public function login(Request $request)
{
    $request->validate([
        'email' => 'required|email',
        'password' => 'required',
    ]);

    $user = User::where('email', $request->email)->first();

    if (! $user || ! Hash::check($request->password, $user->password)) {
        throw ValidationException::withMessages([
            'email' => ['Die angegebenen Anmeldedaten sind falsch.'],
        ]);
    }

    $token = $user->createToken('mobile-app')->plainTextToken;

    return response()->json(['token' => $token]);
}

Hier gibt es ein wichtiges Detail: plainTextToken gibt den Klartextwert des Tokens nur im Moment seiner Erstellung zurück. Die Datenbank speichert lediglich einen Hash des Tokens, sodass du diesen Wert nicht wiederherstellen kannst, wenn du ihn verlierst — der Client muss ihn sofort speichern.

Schütze deine Routen mit der Middleware auth:sanctum. In routes/api.php:

use Illuminate\Support\Facades\Route;

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

Auf der Client-Seite sieht die Anfrage so aus:

curl https://api.beispiel.com/api/user \
  -H "Authorization: Bearer 1|abcDEF..." \
  -H "Accept: application/json"

Token-Fähigkeiten (Abilities)

Sanctum erlaubt es dir, jedem Token bestimmte Fähigkeiten zuzuweisen. Das ist eine saubere Möglichkeit, einzuschränken, was ein Token tun darf:

$token = $user->createToken('report-bot', ['post:read'])->plainTextToken;

In einem Controller oder einer Route kannst du diese Fähigkeit prüfen:

if ($request->user()->tokenCan('post:read')) {
    // hat Leseberechtigung
}

Du kannst außerdem die Middlewares abilities und ability zu Routen hinzufügen, um den Zugriff auf Gate-Ebene einzuschränken. Beachte, dass Fähigkeiten nur eine Komfortschicht sind; die eigentliche Autorisierungslogik musst du trotzdem in deiner Anwendung durchsetzen.

SPA-Authentifizierung

Für eine SPA, die auf derselben Hauptdomain läuft, verwendet Sanctum die Sitzungscookies von Laravel anstelle von Tokens. Dieser Ansatz ist sicherer, weil du das Token nicht im für JavaScript zugänglichen localStorage aufbewahren musst; der Browser verwaltet das HttpOnly-Cookie automatisch. Der Ablauf ist wie folgt:

Die SPA fordert zunächst ein CSRF-Cookie vom Endpunkt /sanctum/csrf-cookie an.
Anschließend sendet sie eine normale Web-Anfrage an die Route /login; bei Erfolg wird ein Sitzungscookie gesetzt.
Alle nachfolgenden API-Anfragen kommen bereits über dieses Cookie authentifiziert an.

Drei Einstellungen sind dabei wichtig. Setze zunächst supports_credentials in config/cors.php auf true. Trage zweitens die Domain deiner SPA in der Datei .env ein:

SANCTUM_STATEFUL_DOMAINS=localhost:3000
SESSION_DOMAIN=localhost

Drittens muss der Client Cookies mit seinen Anfragen senden. Wenn du Axios verwendest:

import axios from 'axios';

axios.defaults.withCredentials = true;
axios.defaults.withXSRFToken = true;

await axios.get('/sanctum/csrf-cookie');
await axios.post('/login', { email, password });
const { data } = await axios.get('/api/user');

Der häufigste Fehler hier ist, die SPA und die API auf völlig unterschiedlichen Domains zu betreiben und sich dann zu fragen, warum die Sitzung nicht erhalten bleibt. Die cookiebasierte Methode erfordert, dass beide dieselbe Hauptdomain teilen (zum Beispiel app.beispiel.com und api.beispiel.com).

Tokens widerrufen und Sicherheit

Wenn sich ein Benutzer abmeldet oder ein Gerät verliert, musst du Tokens ungültig machen. Um das aktuelle Token zu löschen:

$request->user()->currentAccessToken()->delete();

Um alle Tokens zu widerrufen (überall abmelden):

$request->user()->tokens()->delete();

Ein paar Sicherheitshinweise: Lege über config/sanctum.php (den Schlüssel expiration) eine Token-Ablaufzeit fest, betreibe deine API immer hinter HTTPS und füge deinem Login-Endpunkt die throttle-Middleware hinzu, um Brute-Force-Versuche zu begrenzen. Auf der SPA-Seite ist ein aktiver CSRF-Schutz der größte Vorteil, den die cookiebasierte Methode bietet.

Häufige Fragen

Sollte ich Sanctum oder Passport verwenden?

Sofern du keinen vollständigen, für externe Entwickler offenen OAuth2-Server baust, wähle Sanctum. Für mobile App-Tokens und Erstanbieter-SPA-Sitzungen ist Sanctum sowohl leichter als auch einfacher zu warten. Passport ist sinnvoll, wenn du OAuth-Flows wie den Authorization Code Grant benötigst.

Wo sollte ich Tokens speichern?

Bewahre das Token in mobilen Apps im sicheren Speicher der Plattform auf (iOS Keychain, Android Keystore). Verwende in SPAs die cookiebasierte SPA-Authentifizierung statt der Token-Methode, damit du das Token nicht im für JavaScript zugänglichen localStorage aufbewahren musst.

Warum gibt mein SPA-Login einen 419-Fehler zurück?

Ein 419-Fehler ist meist eine CSRF-Token-Abweichung. Stelle sicher, dass du /sanctum/csrf-cookie vor deinen Anfragen aufrufst, dass der Client Cookies sendet (withCredentials) und dass SANCTUM_STATEFUL_DOMAINS und SESSION_DOMAIN korrekt konfiguriert sind.

Möchtest du eine sichere Authentifizierungsschicht für deine API einrichten? Wenn du Hilfe bei der Laravel-Sanctum-Integration, SPA-Sitzungen oder deinen mobilen APIs brauchst, nimm Kontakt mit mir auf — lass uns gemeinsam die Lösung bauen, die am besten zu deinem Projekt passt.