Een custom authenticatieguard implementeren

De interne structuur van het authenticatiesysteem van Laravel

De `Auth`-facade en de `AuthManager`

De Auth-facade is een proxy voor Illuminate\Auth\AuthManager. De AuthManager beheert meerdere guards volgens het driverpatroon en maakt en cachet de juiste guardinstanties op basis van de configuratie in config/auth.php.

// De interne werking van Auth::guard('web') (vereenvoudigde versie van AuthManager::guard())
public function guard($name = null)
{
    $name = $name ?: $this->getDefaultDriver();

    return $this->guards[$name] ?? ($this->guards[$name] = $this->resolve($name));
}

resolve() leest de driver-sleutel uit de guards-array in config/auth.php en roept de bijbehorende factory-closure aan. Ook de ingebouwde drivers session en token zijn op deze manier geregistreerd.

Het verschil tussen de interfaces `Guard` en `StatefulGuard`

Een authenticatieguard van Laravel moet minimaal Illuminate\Contracts\Auth\Guard implementeren. Moet er een sessie worden bijgehouden, dan implementeer je StatefulGuard.

De Guard-interface (Illuminate\Contracts\Auth\Guard)

interface Guard
{
    // Controleert of er een geauthenticeerde gebruiker is
    public function check();

    // Controleert of het een gast (niet-geauthenticeerd) is
    public function guest();

    // Geeft de huidige geauthenticeerde gebruiker terug (null indien niet geauthenticeerd)
    public function user();

    // Geeft het ID van de huidige geauthenticeerde gebruiker terug
    public function id();

    // Controleert of de opgegeven credentials geldig zijn (logt niet in)
    public function validate(array $credentials = []);

    // Controleert of er een gebruiker is gezet (ook zonder login te injecteren via setUser)
    public function hasUser();

    // Zet handmatig de geauthenticeerde gebruiker
    public function setUser(Authenticatable $user);
}

De StatefulGuard-interface (Illuminate\Contracts\Auth\StatefulGuard)

StatefulGuard erft van Guard en voegt de methodes toe die nodig zijn om de loginstatus via sessies en cookies te bewaren.

interface StatefulGuard extends Guard
{
    // Valideert credentials en logt in (met remember-vlag)
    public function attempt(array $credentials = [], $remember = false);

    // Authenticeert voor één request zonder de sessie op te slaan
    public function once(array $credentials = []);

    // Logt een gebruikersinstantie direct in
    public function login(Authenticatable $user, $remember = false);

    // Logt in op basis van een ID
    public function loginUsingId($id, $remember = false);

    // Authenticeert voor één request op basis van een ID
    public function onceUsingId($id);

    // Controleert of er is ingelogd via de "ingelogd blijven"-cookie
    public function viaRemember();

    // Logt uit
    public function logout();
}

Guards die geen sessie nodig hebben, zoals API-authenticatie of eigen tokenauthenticatie, hoeven alleen Guard te implementeren. Is een sessie nodig, zoals bij een beheerderslogin, dan implementeer je StatefulGuard.

Een custom guard implementeren

De `GuardHelpers`-trait

Omdat check(), guest(), id() en hasUser() van de Guard-interface vrijwel altijd dezelfde implementatie hebben, biedt Laravel de trait Illuminate\Auth\GuardHelpers. Met deze trait beperk je de verplichte implementatie tot twee methodes: user() en validate().

// De standaardimplementatie die GuardHelpers biedt (fragment)
trait GuardHelpers
{
    protected $user;

    public function check(): bool
    {
        return ! is_null($this->user());
    }

    public function guest(): bool
    {
        return ! $this->check();
    }

    public function id(): mixed
    {
        return $this->user()?->getAuthIdentifier();
    }

    public function hasUser(): bool
    {
        return ! is_null($this->user);
    }

    public function setUser(Authenticatable $user): static
    {
        $this->user = $user;
        return $this;
    }
}

Implementatievoorbeeld: een API-tokenguard

Naar het voorbeeld van het ontwerp van de TokenGuard implementeren we een eenvoudige guard met API-tokenauthenticatie. De guard haalt het token uit de requestheader of queryparameter en resolvet de gebruiker via de UserProvider.

De guardklasse aanmaken

Maak de guardklasse aan in de map app/Auth.

<?php

namespace App\Auth;

use Illuminate\Auth\GuardHelpers;
use Illuminate\Contracts\Auth\Guard;
use Illuminate\Contracts\Auth\UserProvider;
use Illuminate\Http\Request;

class ApiTokenGuard implements Guard
{
    use GuardHelpers;

    protected Request $request;

    public function __construct(UserProvider $provider, Request $request)
    {
        $this->provider = $provider;
        $this->request = $request;
    }

    /**
     * Geeft de huidige geauthenticeerde gebruiker terug
     */
    public function user(): ?\Illuminate\Contracts\Auth\Authenticatable
    {
        // Geef de gecachete gebruiker terug als die er is
        if (! is_null($this->user)) {
            return $this->user;
        }

        $token = $this->getTokenForRequest();

        if (empty($token)) {
            return null;
        }

        // Haal de gebruiker op via de UserProvider
        $this->user = $this->provider->retrieveByCredentials([
            'api_token' => $token,
        ]);

        return $this->user;
    }

    /**
     * Valideert alleen de credentials (logt niet in)
     */
    public function validate(array $credentials = []): bool
    {
        if (empty($credentials['api_token'])) {
            return false;
        }

        return (bool) $this->provider->retrieveByCredentials($credentials);
    }

    /**
     * Haalt het token uit het request
     *
     * Prioriteit: Bearer-header → queryparameter → requestbody
     */
    protected function getTokenForRequest(): ?string
    {
        $token = $this->request->bearerToken();

        if (empty($token)) {
            $token = $this->request->query('api_token');
        }

        if (empty($token)) {
            $token = $this->request->input('api_token');
        }

        return $token ?: null;
    }

    /**
     * Vervangt de requestinstantie
     */
    public function setRequest(Request $request): static
    {
        $this->request = $request;
        return $this;
    }
}

De guard registreren in een service provider

Registreer de guard met Auth::extend() in de boot()-methode van de AppServiceProvider.

<?php

namespace App\Providers;

use App\Auth\ApiTokenGuard;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Auth::extend('api-token', function (Application $app, string $name, array $config) {
            // Resolve de provider uit de config met Auth::createUserProvider()
            $provider = Auth::createUserProvider($config['provider'] ?? 'users');

            return new ApiTokenGuard($provider, $app->make('request'));
        });
    }
}

Auth::createUserProvider() leest de providers-configuratie in config/auth.php en geeft de bijbehorende UserProvider-instantie terug. Zolang je geen eigen provider maakt, gebruik je op deze manier de standaard EloquentUserProvider.

De guard configureren in config/auth.php

Voeg de nieuwe guard toe aan config/auth.php.

'guards' => [
    'web' => [
        'driver'   => 'session',
        'provider' => 'users',
    ],

    // De toegevoegde custom guard
    'api' => [
        'driver'   => 'api-token', // Moet overeenkomen met het eerste argument van Auth::extend()
        'provider' => 'users',
    ],
],

De guard toepassen op routes

Geef de guardnaam op bij de auth-middleware.

// routes/api.php
use Illuminate\Support\Facades\Route;

Route::middleware('auth:api')->group(function () {
    Route::get('/user', function () {
        return auth()->user();
    });

    Route::get('/posts', [\App\Http\Controllers\PostController::class, 'index']);
});

Om in een controller of andere code een specifieke guard te gebruiken, roep je Auth::guard('api') of auth('api') aan.

$user = Auth::guard('api')->user();

Een simpele guard met een closure

Met Auth::viaRequest() kun je zonder klasse, alleen met een closure, een eenvoudige guard definiëren. Geschikt voor prototypes of heel simpele authenticatie.

use Illuminate\Http\Request;
use App\Models\User;

// In AppServiceProvider::boot()
Auth::viaRequest('custom-token', function (Request $request): ?User {
    $token = $request->bearerToken();

    if (empty($token)) {
        return null;
    }

    return User::where('api_token', $token)->first();
});

Configuratie in config/auth.php:

'guards' => [
    'api' => [
        'driver' => 'custom-token',
    ],
],

Guards die je definieert met Auth::viaRequest() gebruiken geen UserProvider, waardoor providermethodes zoals retrieveById() niet werken. Voor productie raden we een klassegebaseerde guard via Auth::extend() aan.

Een custom `UserProvider` implementeren

Wil je gebruikersgegevens uit een andere bron dan de database halen (een externe API, LDAP, enzovoort), dan implementeer je de interface Illuminate\Contracts\Auth\UserProvider.

<?php

namespace App\Auth;

use App\Models\User;
use Illuminate\Contracts\Auth\Authenticatable;
use Illuminate\Contracts\Auth\UserProvider;

class ApiUserProvider implements UserProvider
{
    public function __construct(
        protected string $apiBaseUrl,
        protected string $model = User::class,
    ) {}

    /**
     * Haalt een gebruiker op via ID
     */
    public function retrieveById(mixed $identifier): ?Authenticatable
    {
        return ($this->model)::find($identifier);
    }

    /**
     * Haalt een gebruiker op via het "ingelogd blijven"-token
     * Bij guards zonder sessie volstaat het om null terug te geven
     */
    public function retrieveByToken(mixed $identifier, string $token): ?Authenticatable
    {
        return null;
    }

    /**
     * Werkt het "ingelogd blijven"-token bij
     * Bij guards zonder sessie hoeft dit niets te doen
     */
    public function updateRememberToken(Authenticatable $user, string $token): void {}

    /**
     * Haalt een gebruiker op via credentials
     * Wordt aangeroepen vanuit validate() en user() van de guard
     */
    public function retrieveByCredentials(array $credentials): ?Authenticatable
    {
        if (empty($credentials['api_token'])) {
            return null;
        }

        // Voorbeeld: het token verifiëren via een externe API en de gebruikersgegevens ophalen
        $response = \Illuminate\Support\Facades\Http::withToken($credentials['api_token'])
            ->get("{$this->apiBaseUrl}/auth/me");

        if (! $response->successful()) {
            return null;
        }

        $data = $response->json();

        // Koppelen aan een gebruiker in de lokale DB, of dynamisch een model aanmaken
        return User::firstOrCreate(
            ['external_id' => $data['id']],
            ['name' => $data['name'], 'email' => $data['email']],
        );
    }

    /**
     * Valideert de credentials van de opgehaalde gebruiker
     * Bij tokenauthenticatie volstaat true als retrieveByCredentials slaagt
     */
    public function validateCredentials(Authenticatable $user, array $credentials): bool
    {
        return true;
    }

    /**
     * Controleert of het wachtwoord opnieuw gehasht moet worden
     * Bij tokenauthenticatie is dit altijd overbodig
     */
    public function rehashPasswordIfRequired(Authenticatable $user, array $credentials, bool $force = false): void {}
}

De custom `UserProvider` registreren

// AppServiceProvider::boot()
Auth::provider('api-user', function (Application $app, array $config) {
    return new \App\Auth\ApiUserProvider(
        config('services.auth_api.base_url'),
        $config['model'] ?? \App\Models\User::class,
    );
});

Voeg hem toe aan de providers-sectie van config/auth.php:

'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model'  => App\Models\User::class,
    ],

    // Custom provider
    'api-users' => [
        'driver' => 'api-user',
        'model'  => App\Models\User::class,
    ],
],

Combineer de guard met de provider:

'guards' => [
    'api' => [
        'driver'   => 'api-token',
        'provider' => 'api-users', // De custom provider opgeven
    ],
],

Praktische use cases

Multi-authenticatie (aparte guards voor beheerders en gewone gebruikers)

Het beheerdersmodel aanmaken

Maak een Eloquent-model voor beheerders. Door van Authenticatable te erven, werkt het samen met het Auth-systeem.

php artisan make:model Admin -m

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;

class Admin extends Authenticatable
{
    protected $fillable = ['name', 'email', 'password'];

    protected $hidden = ['password', 'remember_token'];
}

config/auth.php configureren

'guards' => [
    'web' => [
        'driver'   => 'session',
        'provider' => 'users',
    ],
    'admin' => [
        'driver'   => 'session',
        'provider' => 'admins', // Provider voor beheerders
    ],
],

'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model'  => App\Models\User::class,
    ],
    'admins' => [
        'driver' => 'eloquent',
        'model'  => App\Models\Admin::class, // Beheerdersmodel
    ],
],

Routes en middleware instellen

// routes/web.php

// Routes voor gewone gebruikers (standaard web-guard)
Route::middleware('auth')->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
});

// Routes voor beheerders (admin-guard)
Route::prefix('admin')->middleware('auth:admin')->group(function () {
    Route::get('/dashboard', [AdminDashboardController::class, 'index']);
});

De loginverwerking schrijven met een expliciete guard

<?php

namespace App\Http\Controllers\Admin;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

class LoginController extends Controller
{
    public function store(Request $request)
    {
        $credentials = $request->validate([
            'email'    => 'required|email',
            'password' => 'required',
        ]);

        // attempt() met expliciet de admin-guard
        if (Auth::guard('admin')->attempt($credentials)) {
            $request->session()->regenerate();
            return redirect()->intended('/admin/dashboard');
        }

        return back()->withErrors(['email' => 'De inloggegevens zijn onjuist.']);
    }

    public function destroy(Request $request)
    {
        Auth::guard('admin')->logout();
        $request->session()->invalidate();
        $request->session()->regenerateToken();

        return redirect('/admin/login');
    }
}

Externe API-authenticatie met JWT-tokens

Een voorbeeldimplementatie van een custom guard wanneer je een externe JWT-authenticatiedienst gebruikt.

<?php

namespace App\Auth;

use App\Models\User;
use Illuminate\Auth\GuardHelpers;
use Illuminate\Contracts\Auth\Guard;
use Illuminate\Contracts\Auth\UserProvider;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;

class JwtGuard implements Guard
{
    use GuardHelpers;

    protected Request $request;
    protected ?array $payload = null;

    public function __construct(UserProvider $provider, Request $request)
    {
        $this->provider = $provider;
        $this->request  = $request;
    }

    public function user(): ?\Illuminate\Contracts\Auth\Authenticatable
    {
        if (! is_null($this->user)) {
            return $this->user;
        }

        $token = $this->request->bearerToken();

        if (empty($token)) {
            return null;
        }

        // De JWT verifiëren bij de externe dienst
        $payload = $this->verifyToken($token);

        if (is_null($payload)) {
            return null;
        }

        $this->payload = $payload;

        $this->user = $this->provider->retrieveById($payload['sub']);

        return $this->user;
    }

    public function validate(array $credentials = []): bool
    {
        if (empty($credentials['token'])) {
            return false;
        }

        return ! is_null($this->verifyToken($credentials['token']));
    }

    /**
     * De JWT verifiëren en de payload ophalen
     */
    protected function verifyToken(string $token): ?array
    {
        $response = Http::withToken($token)
            ->get(config('services.auth.verify_url'));

        if (! $response->successful()) {
            return null;
        }

        return $response->json();
    }

    /**
     * Geeft de geverifieerde JWT-payload terug
     */
    public function payload(): ?array
    {
        return $this->payload;
    }
}

Registratie in de AppServiceProvider:

Auth::extend('jwt', function (Application $app, string $name, array $config) {
    return new \App\Auth\JwtGuard(
        Auth::createUserProvider($config['provider'] ?? 'users'),
        $app->make('request'),
    );
});

Je kunt ook methodes aanroepen die specifiek zijn voor je custom guard, zoals Auth::guard('jwt')->payload(). Auth::guard() geeft de guardinstantie zelf terug, dus ook methodes die niet in de interface staan zijn aanroepbaar.

Testen

In unittests van een custom guard mock je de UserProvider om het gedrag van de guard te controleren.

<?php

namespace Tests\Unit\Auth;

use App\Auth\ApiTokenGuard;
use Illuminate\Contracts\Auth\Authenticatable;
use Illuminate\Contracts\Auth\UserProvider;
use Illuminate\Http\Request;
use PHPUnit\Framework\MockObject\MockObject;
use Tests\TestCase;

class ApiTokenGuardTest extends TestCase
{
    private UserProvider&MockObject $provider;
    private ApiTokenGuard $guard;

    protected function setUp(): void
    {
        parent::setUp();

        $this->provider = $this->createMock(UserProvider::class);
    }

    public function test_user_returns_null_when_no_token(): void
    {
        $request = Request::create('/');
        $guard   = new ApiTokenGuard($this->provider, $request);

        $this->assertNull($guard->user());
    }

    public function test_user_returns_user_with_valid_bearer_token(): void
    {
        $mockUser = $this->createMock(Authenticatable::class);

        $this->provider
            ->expects($this->once())
            ->method('retrieveByCredentials')
            ->with(['api_token' => 'valid-token'])
            ->willReturn($mockUser);

        $request = Request::create('/');
        $request->headers->set('Authorization', 'Bearer valid-token');

        $guard = new ApiTokenGuard($this->provider, $request);

        $this->assertSame($mockUser, $guard->user());
    }

    public function test_check_returns_false_when_no_token(): void
    {
        $request = Request::create('/');
        $guard   = new ApiTokenGuard($this->provider, $request);

        $this->assertFalse($guard->check());
    }

    public function test_validate_returns_false_without_api_token_credential(): void
    {
        $request = Request::create('/');
        $guard   = new ApiTokenGuard($this->provider, $request);

        $this->assertFalse($guard->validate([]));
    }
}

In feature tests met actingAs kun je een gebruiker instellen voor een specifieke guard.

// Testen met een gebruiker geauthenticeerd via een specifieke guard
$this->actingAs($user, 'api')
    ->getJson('/api/user')
    ->assertOk();

Gerelateerde pagina’s

Authenticatie (introductie)

Bekijk de starter kits en de standaard authenticatieflows.

Service container

Begrijp de werking van de service container die je gebruikt bij het registreren van guards.

AI-ontwikkeling

Design patterns

Package-ontwikkeling

Applicatiestructuur

Nieuwe functies in Laravel 13

Eloquent in detail

Validatie-uitbreidingen

Authenticatie uitbreiden

Beveiliging

Queues

Testen

Een custom authenticatieguard implementeren

De interne structuur van het authenticatiesysteem van Laravel

De `Auth`-facade en de `AuthManager`

Het verschil tussen de interfaces `Guard` en `StatefulGuard`

Een custom guard implementeren

De `GuardHelpers`-trait

Implementatievoorbeeld: een API-tokenguard

Een simpele guard met een closure

Een custom `UserProvider` implementeren

De custom `UserProvider` registreren

Praktische use cases

Multi-authenticatie (aparte guards voor beheerders en gewone gebruikers)

Externe API-authenticatie met JWT-tokens

Testen

Gerelateerde pagina’s

Authenticatie (introductie)

Service container

​De interne structuur van het authenticatiesysteem van Laravel

​De Auth-facade en de AuthManager

​Het verschil tussen de interfaces Guard en StatefulGuard

​Een custom guard implementeren

​De GuardHelpers-trait

​Implementatievoorbeeld: een API-tokenguard

​Een simpele guard met een closure

​Een custom UserProvider implementeren

​De custom UserProvider registreren

​Praktische use cases

​Multi-authenticatie (aparte guards voor beheerders en gewone gebruikers)

​Externe API-authenticatie met JWT-tokens

​Testen

​Gerelateerde pagina’s

Authenticatie (introductie)

Service container

De interne structuur van het authenticatiesysteem van Laravel

De `Auth`-facade en de `AuthManager`

Het verschil tussen de interfaces `Guard` en `StatefulGuard`

Een custom guard implementeren

De `GuardHelpers`-trait

Implementatievoorbeeld: een API-tokenguard

Een simpele guard met een closure

Een custom `UserProvider` implementeren

De custom `UserProvider` registreren

Praktische use cases

Multi-authenticatie (aparte guards voor beheerders en gewone gebruikers)

Externe API-authenticatie met JWT-tokens

Testen

Gerelateerde pagina’s