Laravel Sanctum pour PHP : guide complet sur les tokens API et l'authentification SPA

1. Qu'est-ce que Laravel Sanctum et pourquoi l'utiliser ?

Laravel Sanctum est une bibliothèque d'authentification légère pour le framework PHP Laravel, conçue pour gérer les tokens API et les applications monopages (SPA). Développée par Taylor Otwell et l'équipe Laravel, Sanctum offre un moyen simple mais puissant de sécuriser les routes API, permettant aux développeurs d'implémenter rapidement l'authentification sans la configuration complexe des solutions plus lourdes comme Passport (OAuth2).

L'objectif principal de Sanctum est de résoudre deux problèmes clés du développement web moderne : l'authentification pour les SPA (Single Page Applications) fonctionnant sur le même domaine que le backend, et la délivrance de tokens API pour les applications mobiles ou les services tiers. Contrairement à Passport, Sanctum n'utilise pas le protocole OAuth2 complet, ce qui en fait un choix idéal pour les projets ne nécessitant pas un système complexe de délégation d'accès. Il utilise les sessions Laravel pour l'authentification SPA et des tokens simples basés sur HMAC pour l'API.

La bibliothèque est incluse par défaut dans Laravel 8 et versions ultérieures, ce qui la rend disponible "prête à l'emploi". Sanctum est particulièrement utile pour les startups, les petites équipes et les projets où la rapidité de développement et un minimum de dépendances sont essentiels. Il gère automatiquement la durée de validité des tokens, prend en charge les "capacités" (abilities) pour un réglage fin des droits d'accès et s'intègre facilement avec Laravel Fortify, Breeze ou Jetstream.

2. Installation

Laravel Sanctum s'installe via Composer, le gestionnaire de paquets standard pour PHP. Assurez-vous d'avoir PHP 8.0 ou supérieur et Laravel 8.x/9.x/10.x/11.x.

Commande d'installation exacte :

composer require laravel/sanctum

Après l'installation, publiez le fichier de configuration et les migrations de base de données :

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

Exécutez ensuite les migrations pour créer la table personal_access_tokens :

php artisan migrate

Pour l'authentification SPA, ajoutez le middleware EnsureFrontendRequestsAreStateful dans le noyau HTTP (fichier app/Http/Kernel.php) :

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

Dans le fichier .env, spécifiez également le domaine de votre SPA :

SANCTUM_STATEFUL_DOMAINS=localhost:8080

3. Démarrage rapide — exemple minimal fonctionnel

Voici un exemple minimal de délivrance d'un token API et de protection d'une route.

Étape 1 : Modèle User

Dans le modèle App\Models\User, utilisez le 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
        ]);
    }