Laravel Sanctum (API-tokenauthenticatie)

Wat is Sanctum

Laravel Sanctum is een lichtgewicht authenticatiepakket voor SPA’s (single-page applications), mobiele apps en eenvoudige API’s. Zonder kennis van complexe OAuth kun je per gebruiker meerdere API-tokens uitgeven en beheren. Sanctum lost twee problemen op.

Authenticatiemodus	Werking	Voornaamste toepassing
API-tokenauthenticatie	`Authorization: Bearer <token>`-header	Mobiele apps en integraties van derden
SPA-authenticatie	Sessiecookie + CSRF-bescherming	Eigen frontend (Vue/React e.d.)

Roep je de API aan vanuit je eigen SPA, gebruik dan SPA-authenticatie. Gebruiken mobiele apps of derden je API, gebruik dan API-tokenauthenticatie. Je mag ook gerust maar één van beide gebruiken.

Sanctum of Passport?

	Sanctum	Passport
Complexiteit	Eenvoudig	Volwaardige OAuth2
Geschikt voor	Eigen SPA’s en mobiele apps	OAuth-provider voor externe apps
Tokentype	Personal access tokens	OAuth2-accesstokens

Moet je als OAuth2-provider fungeren voor externe diensten, kies dan Passport; voor de meeste applicaties volstaat Sanctum.

Installatie en configuratie

Installatie

Sanctum wordt opgezet door simpelweg het Artisan-commando install:api uit te voeren.

php artisan install:api

Dit commando doet automatisch het volgende:

Installeren van het pakket laravel/sanctum
Publiceren van het migratiebestand voor de tabel personal_access_tokens
Uitvoeren van de migraties

De HasApiTokens-trait toevoegen

Voeg de trait HasApiTokens toe aan je User-model.

// app/Models/User.php

use Laravel\Sanctum\HasApiTokens;

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

Hierna kun je methoden zoals $user->createToken() en $user->tokens gebruiken.

API-tokenauthenticatie

Tokenflow

Een token uitgeven

Met de methode createToken() geef je een token uit. Via de property plainTextToken haal je de tokenwaarde in platte tekst op. Het platte-teksttoken wordt niet in de database opgeslagen, dus je moet het direct na uitgifte aan de gebruiker teruggeven.

use Illuminate\Http\Request;

Route::post('/tokens/create', function (Request $request) {
    $token = $request->user()->createToken($request->token_name);

    return ['token' => $token->plainTextToken];
})->middleware('auth');

In de database wordt het token opgeslagen als een SHA-256-hash.

Scopes (abilities) instellen

Door abilities (scopes) aan een token toe te kennen, beperk je welke acties met dat token mogelijk zijn.

// Token met scopes uitgeven
$token = $user->createToken('mobile-app', ['server:update', 'server:read']);

return $token->plainTextToken;

Tijdens het verwerken van een request controleer je de scopes van het token.

if ($request->user()->tokenCan('server:update')) {
    // Update-actie uitvoeren
}

if ($request->user()->tokenCant('server:update')) {
    abort(403);
}

Scopes controleren met middleware

Registreer de middleware-aliassen in bootstrap/app.php.

use Laravel\Sanctum\Http\Middleware\CheckAbilities;
use Laravel\Sanctum\Http\Middleware\CheckForAnyAbility;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->alias([
        'abilities' => CheckAbilities::class,  // Heeft alle abilities
        'ability'   => CheckForAnyAbility::class, // Heeft minstens één van de abilities
    ]);
})

Pas de middleware toe op je routes.

// Alleen tokens toestaan die zowel check-status als place-orders hebben
Route::get('/orders', function () {
    // ...
})->middleware(['auth:sanctum', 'abilities:check-status,place-orders']);

// Tokens toestaan die check-status of place-orders hebben
Route::get('/orders', function () {
    // ...
})->middleware(['auth:sanctum', 'ability:check-status,place-orders']);

Geldigheidsduur van tokens

Standaard verlopen Sanctum-tokens niet. Met de optie expiration in config/sanctum.php stel je een geldigheidsduur in minuten in.

// config/sanctum.php
'expiration' => 525600, // 365 dagen (in minuten)

Je kunt ook per token een vervaldatum opgeven.

$token = $user->createToken(
    'token-name',
    ['*'],
    now()->addWeeks(1) // Verloopt over 1 week
)->plainTextToken;

Heb je een geldigheidsduur ingesteld, plan dan het periodiek verwijderen van verlopen tokens in.

use Illuminate\Support\Facades\Schedule;

Schedule::command('sanctum:prune-expired --hours=24')->daily();

Tokens intrekken

// Alle tokens verwijderen
$user->tokens()->delete();

// Het token van het huidige request verwijderen
$request->user()->currentAccessToken()->delete();

// Een specifiek token verwijderen
$user->tokens()->where('id', $tokenId)->delete();

SPA-authenticatie

SPA-authenticatie gebruikt een sessiecookie, dus je hoeft geen tokens uit te geven of te beheren. Het is geschikt wanneer je de API aanroept vanuit je eigen frontend (Vue, React, Next.js e.d.).

Om SPA-authenticatie te gebruiken moeten de SPA en de API hetzelfde top-level domein delen (subdomeinen mogen verschillen). Verder moeten requests de header Accept: application/json en een Referer- of Origin-header bevatten.

De Sanctum-middleware inschakelen

Schakel de middleware statefulApi() in via bootstrap/app.php.

->withMiddleware(function (Middleware $middleware): void {
    $middleware->statefulApi();
})

First-party domeinen instellen

Stel het domein van je SPA in via de optie stateful in config/sanctum.php.

// config/sanctum.php
'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', sprintf(
    '%s%s',
    'localhost,localhost:3000,127.0.0.1,127.0.0.1:8000,::1',
    Sanctum::currentApplicationUrlWithPort()
))),

CORS configureren

Roep je de API aan vanaf een ander subdomein, dan is CORS-configuratie nodig.

php artisan config:publish cors

Stel in config/cors.php de optie supports_credentials in op true.

// config/cors.php
'supports_credentials' => true,

Ook axios in de frontend moet worden geconfigureerd.

// resources/js/bootstrap.js
axios.defaults.withCredentials = true;
axios.defaults.withXSRFToken = true;

Vergeet ook de domeininstelling van de sessiecookie niet.

// config/session.php
'domain' => '.example.com', // Begin met een punt

Authenticatieflow vanuit de SPA

Het CSRF-cookie ophalen

Roep vóór het inloggen het endpoint /sanctum/csrf-cookie aan om de CSRF-bescherming te initialiseren.

await axios.get('/sanctum/csrf-cookie');

Het loginrequest versturen

Stuur een POST-request naar het /login-endpoint.

await axios.post('/login', {
    email: '[email protected]',
    password: 'password',
});

Geauthenticeerde requests versturen

Requests na het inloggen worden automatisch geauthenticeerd via het sessiecookie.

const response = await axios.get('/api/user');
console.log(response.data); // Gegevens van de ingelogde gebruiker

Geauthenticeerde routes beschermen

Pas de middleware auth:sanctum toe op een route en niet-geauthenticeerde requests krijgen een 401 Unauthorized terug. Deze ene middleware handelt zowel API-token- als SPA-authenticatie af.

use Illuminate\Http\Request;

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

// Een routegroep beschermen
Route::middleware('auth:sanctum')->group(function () {
    Route::get('/profile', [ProfileController::class, 'show']);
    Route::put('/profile', [ProfileController::class, 'update']);
    Route::get('/posts', [PostController::class, 'index']);
});

Een voorbeeld van API-tokenauthenticatie voor een mobiele app.

Het login-endpoint maken

// routes/api.php

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

Route::post('/sanctum/token', function (Request $request) {
    $request->validate([
        'email'       => ['required', 'email'],
        'password'    => ['required'],
        'device_name' => ['required', 'string'],
    ]);

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

    if (! $user || ! Hash::check($request->password, $user->password)) {
        throw ValidationException::withMessages([
            'email' => ['De opgegeven inloggegevens zijn onjuist.'],
        ]);
    }

    return response()->json([
        'token' => $user->createToken($request->device_name)->plainTextToken,
    ]);
});

Geauthenticeerde routes maken

// routes/api.php

Route::middleware('auth:sanctum')->group(function () {
    // Gegevens van de huidige gebruiker teruggeven
    Route::get('/user', function (Request $request) {
        return $request->user();
    });

    // Het huidige token intrekken en uitloggen
    Route::post('/logout', function (Request $request) {
        $request->user()->currentAccessToken()->delete();

        return response()->json(['message' => 'Je bent uitgelogd.']);
    });

    // Uitloggen op alle apparaten
    Route::post('/logout/all', function (Request $request) {
        $request->user()->tokens()->delete();

        return response()->json(['message' => 'Je bent op alle apparaten uitgelogd.']);
    });
});

Requests versturen vanuit de client

// Inloggen
const { data } = await axios.post('/api/sanctum/token', {
    email: '[email protected]',
    password: 'password',
    device_name: 'My iPhone',
});

const token = data.token;

// Geauthenticeerd request
const response = await axios.get('/api/user', {
    headers: {
        Authorization: `Bearer ${token}`,
    },
});

Testen

Bij het testen van Sanctum gebruik je Sanctum::actingAs() om een gebruiker te authenticeren en de toe te kennen abilities op te geven.

Pest
PHPUnit

use App\Models\User;
use Laravel\Sanctum\Sanctum;

test('takenlijst kan worden opgehaald', function () {
    Sanctum::actingAs(
        User::factory()->create(),
        ['view-tasks']
    );

    $response = $this->get('/api/tasks');

    $response->assertOk();
});

test('toegang met een token met alle abilities', function () {
    Sanctum::actingAs(
        User::factory()->create(),
        ['*']
    );

    $response = $this->get('/api/tasks');

    $response->assertOk();
});

use App\Models\User;
use Laravel\Sanctum\Sanctum;

public function test_task_list_can_be_retrieved(): void
{
    Sanctum::actingAs(
        User::factory()->create(),
        ['view-tasks']
    );

    $response = $this->get('/api/tasks');

    $response->assertOk();
}

Samenvatting

Installatiestappen op een rij

# Sanctum installeren en migraties uitvoeren
php artisan install:api

Voeg de trait HasApiTokens toe aan het User-model:

use Laravel\Sanctum\HasApiTokens;

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

Veelgebruikte API's op een rij

// Token uitgeven
$token = $user->createToken('token-name')->plainTextToken;

// Token met scopes uitgeven
$token = $user->createToken('token-name', ['read', 'write'])->plainTextToken;

// Scopes controleren
$user->tokenCan('read');   // true/false
$user->tokenCant('write'); // true/false

// Tokens intrekken
$user->tokens()->delete();                        // Alle tokens
$request->user()->currentAccessToken()->delete(); // Huidige token
$user->tokens()->where('id', $id)->delete();      // Specifiek token

Kiezen tussen API-tokenauthenticatie en SPA-authenticatie

API-tokenauthenticatie: voor clients zonder sessie, zoals mobiele apps, derden en CLI-tools.
SPA-authenticatie: voor een SPA op hetzelfde domein (of subdomein), zoals je eigen Vue/React/Next.js-frontend. Veiliger en zonder tokenbeheer.

Architectuur

Database

Eloquent

Beveiliging

Events

E-mail en notificaties

Betalingen

Asynchrone verwerking

Realtime communicatie

Taakplanning

Caching en optimalisatie

Internationalisatie

Bestanden en opslag

Debugging en monitoring

Console en CLI

Performance

Frontend

AI-ontwikkeling

Ontwikkelomgeving

Laravel Sanctum (API-tokenauthenticatie)

Wat is Sanctum

Sanctum of Passport?

Installatie en configuratie

Installatie

De HasApiTokens-trait toevoegen

API-tokenauthenticatie

Tokenflow

Een token uitgeven

Scopes (abilities) instellen

Scopes controleren met middleware

Geldigheidsduur van tokens

Tokens intrekken

SPA-authenticatie

De Sanctum-middleware inschakelen

First-party domeinen instellen

CORS configureren

Authenticatieflow vanuit de SPA

Geauthenticeerde routes beschermen

Testen

Samenvatting

​Wat is Sanctum

​Sanctum of Passport?

​Installatie en configuratie

​Installatie

​De HasApiTokens-trait toevoegen

​API-tokenauthenticatie

​Tokenflow

​Een token uitgeven

​Scopes (abilities) instellen

​Scopes controleren met middleware

​Geldigheidsduur van tokens

​Tokens intrekken

​SPA-authenticatie

​De Sanctum-middleware inschakelen

​First-party domeinen instellen

​CORS configureren

​Authenticatieflow vanuit de SPA

​Geauthenticeerde routes beschermen

​Praktijkvoorbeeld: login-API met tokenuitgifte

​Testen

​Samenvatting

Wat is Sanctum

Sanctum of Passport?

Installatie en configuratie

Installatie

De HasApiTokens-trait toevoegen

API-tokenauthenticatie

Tokenflow

Een token uitgeven

Scopes (abilities) instellen

Scopes controleren met middleware

Geldigheidsduur van tokens

Tokens intrekken

SPA-authenticatie

De Sanctum-middleware inschakelen

First-party domeinen instellen

CORS configureren

Authenticatieflow vanuit de SPA

Geauthenticeerde routes beschermen

Praktijkvoorbeeld: login-API met tokenuitgifte

Testen

Samenvatting