Naar hoofdinhoud gaan
Als je package gebruikers ophaalt uit iets anders dan het standaard Eloquent-model of de database van Laravel, registreer je een eigen UserProvider. Zo kun je bijvoorbeeld een externe directory, een bestaand ledensysteem of een eigen API als opslag voor authenticatie gebruiken. Dit is iets anders dan een nieuwe guard maken. Je levert alleen de implementatie die gebruikers opzoekt en verifieert voor de bestaande session- of token-guards. Wil je de authenticatiemethode van de guard zelf wijzigen, zie dan Een custom authenticatieguard implementeren.
Deze pagina is gericht op Laravel 13 en verwijst naar de 13.x-branch van de officiële documentatie en de implementatie in Framework v13.43.0. Controleer de contractmethoden en het gedrag van het rehashen van wachtwoorden in elke Laravel-versie die je package ondersteunt.

De verantwoordelijkheden van guard en UserProvider scheiden

De guard die Auth::guard() teruggeeft, haalt de authenticatiestatus uit de sessie of het request. Wanneer de guard een gebruiker nodig heeft, delegeert hij dat aan de geconfigureerde provider. De waarde die een UserProvider teruggeeft, moet een object zijn dat Illuminate\Contracts\Auth\Authenticatable implementeert, geen array uit de opslag of een SDK-response.

Auth::provider registreren vanuit een package

Registreren in de boot van de service provider

Laravel roept de callback die je met Auth::provider($name, $callback) registreert aan op basis van de waarde van auth.providers.*.driver. De callback krijgt de applicatie en de providerconfiguratie mee. Registreer hem in de service provider van je package voordat de authenticatieservices worden gebruikt.
DirectoryClientManager en DirectoryUserProvider zijn klassen die je package in de container registreert. $config komt uit de auth.php van de applicatie die het package gebruikt, dus daaruit kun je de verbindingsnaam, tenant en andere waarden lezen die nodig zijn om de provider te maken. Auth::provider registreert de naam van een authenticatie-user provider. Dat is een ander uitbreidingspunt dan de custom guard-driver die Auth::extend registreert. Ook als je beide gebruikt, houd je de verantwoordelijkheden van de guard en die van de gebruikersopslag in aparte klassen.

Provider en guard koppelen in auth.php

Geef de geregistreerde naam op als driver in auth.providers en verwijs vanuit een guard naar die provider.
De configuratie hangt als volgt samen.
  1. De guard directory-web verwijst naar de provider directory-users.
  2. De driver van directory-users is directory, dus de callback van hierboven wordt gekozen.
  3. Er wordt een SessionGuard aangemaakt die gebruikers ophaalt via de gegenereerde UserProvider.
AuthManager cachet een guard de eerste keer dat hij wordt opgelost. Er is geen API die een al opgeloste guard na de providerregistratie vervangt, dus let op de bootvolgorde van service providers en op het gebruik van Auth::forgetGuards() in tests. Als de auth-configuratie gecachet wordt, lees verbindingsgegevens dan niet rechtstreeks uit omgevingsvariabelen, maar los ze op in de configuratie en geef ze daarna door aan de callback.

Het UserProvider-contract implementeren

In Laravel 13 vereist Illuminate\Contracts\Auth\UserProvider de volgende zes methoden.
De drie ophaalmethoden geven een gebruiker of null terug; een niet-gevonden gebruiker wordt niet met een exception aangegeven. Het contract van je package bepaalt of time-outs en communicatiestoringen van de opslag null worden of een herhaalbare exception. Belangrijk is dat je storingen van de opslag niet verbergt achter hetzelfde “ongeldige inloggegevens” als een mislukte authenticatie.

Een Authenticatable teruggeven

Dit minimale voorbeeld zet een record uit de externe opslag om naar een GenericUser in plaats van het ongewijzigd terug te geven. Een echt package kan een eigen gebruikersklasse bieden zodat gebruikers getypeerd bij extra attributen kunnen.
GenericUser gebruikt standaard de attribuutnamen id, password en remember_token. Gebruik je andere namen, overschrijf dan getAuthIdentifierName() en verwante methoden in een eigen klasse die Authenticatable implementeert.

Ophalen via ID en remember token

retrieveById herstelt de gebruiker uit de auth-ID die in de sessie is opgeslagen. Als je inloggen via remember token ondersteunt, vergelijk je de identifier en het token in de opslag.
Beperk de argumenten van hash_equals tot de string uit de opslag en het token, en schrijf tokens nooit naar logs. Ondersteunt de externe opslag geen remember tokens, laat updateRememberToken dan niet leeg zodat het lijkt te slagen. Geef in de authenticatieconfiguratie van je package duidelijk aan dat de remember-functie niet beschikbaar is.

Opzoeken van inloggegevens en wachtwoordvalidatie scheiden

Valideer het wachtwoord niet in retrieveByCredentials

Auth::attempt() zoekt eerst de gebruiker op met retrieveByCredentials en valideert daarna het wachtwoord met validateCredentials. Als de zoekmethode ook wachtwoorden vergelijkt, breekt dat de verwerkingsvolgorde die de guard verwacht en het rehashen van wachtwoorden.
Sluit niet alleen password uit van de zoekcriteria van de opslag, maar ook sleutels zoals password_confirmation. Neem wachtwoorden en access tokens nooit op in queries van de zoek-API, logs of cachesleutels. De als zoekcriteria geaccepteerde sleutels beperken tot een allowlist zoals email helpt ook om geen willekeurige velden naar een externe API te sturen.

De hash vergelijken in validateCredentials

Gebruik voor de validatie de Hasher van de applicatie, en stuur wachtwoorden in platte tekst nooit naar de opslag of naar logs.
Geef false terug als $credentials['password'] ontbreekt of de gebruiker geen wachtwoord heeft. Delegeer je de validatie aan een externe authenticatie-API, houd je dan aan hetzelfde contract en behandel fouten, time-outs en rate limits volgens het exceptionbeleid van je package.

Het rehashen van wachtwoorden behouden

Na een geslaagde login kan Laravel controleren of een rehash nodig is voor het ingestelde hash-algoritme. Een custom provider implementeert rehashPasswordIfRequired en werkt de hash in de opslag alleen bij wanneer dat nodig is.
Omdat dit naar de externe opslag schrijft, mag je fouten bij het rehashen niet negeren. Blijft het wachtwoordattribuut van het gebruikersobject na de update verouderd, dan kan het rehashen bij de volgende login opnieuw gebeuren. Leg ook als vereiste van je package vast dat de gebruikte Hasher overeenkomt met het wachtwoordformaat van de opslag.

De service provider en de authenticatieflow testen

Vervang in de tests van je package de opslagclient door een fake en controleer elke verantwoordelijkheid van de UserProvider afzonderlijk. Controleer vooral deze drie punten los van elkaar.
  • retrieveByCredentials geeft het wachtwoord niet door aan de client.
  • Alleen een juiste hash komt door validateCredentials.
  • De update-API wordt alleen aangeroepen als een rehash nodig is.
Vervang expects hierboven door de API van de mockbibliotheek die je gebruikt. Gebruik je een echte HTTP-client, controleer dan de verzonden inhoud met een HTTP-fake en test dat het wachtwoord in platte tekst nooit in requests of logs verschijnt. Controleer in integratietests die de registratie met Auth::provider bevatten met Testbench of iets vergelijkbaars de volgende volgorde.
  1. Laad de service provider van het package.
  2. Stel de custom driver in auth.providers in.
  3. Verwijs vanuit auth.guards naar die provider.
  4. Los de guard voor het eerst op en controleer dat het ophalen van gebruikers aan de fake client wordt gedelegeerd.
  5. Roep in tests die configuratie of registratie wijzigen Auth::forgetGuards() aan voordat je naar de volgende case gaat.

Compatibiliteit bij updates ontwerpen

Een UserProvider ligt op de grens van authenticatie, dus controleer bij een package-update het volgende.
  • Als je de attribuutnamen van ID, wachtwoord of remember token van de Authenticatable wijzigt, bepaal dan hoe bestaande sessies en remember cookies worden behandeld.
  • Als je het ID-formaat of het wachtwoord-hash-algoritme van de externe opslag wijzigt, controleer dan of bestaande gebruikers nog hersteld kunnen worden en kunnen inloggen.
  • Als je de toegestane sleutels van retrieveByCredentials beperkt, controleer dan de compatibiliteit met de voorwaarden die gebruikers aan Auth::attempt doorgaven.
  • Onderscheid storingen van de opslag van mislukte authenticatie, en kies een beleid waarbij gebruikers op het loginscherm niet ten onrechte hun wachtwoord opnieuw moeten invoeren.
  • Controleer de configuratiecache en je deploystappen voordat je de providernaam, de configuratiesleutels in auth.php of de verbindingsinstellingen verwijdert.
Behandel “uit welke opslag en wat je als gebruiker teruggeeft” en “met welke hash wachtwoorden worden beheerd” als publiek contract van je package, en laat de omgang met inloggegevens niet volledig aan de applicatie over.

Gerelateerde pagina’s

Een custom authenticatieguard implementeren

Lees hoe je de guard zelf uitbreidt en gebruikers oplost vanuit sessies of API-tokens.

Service providers

Lees de basis voor het registreren van de service provider van je package en het toepassen van uitbreidingen bij het booten.

Geraadpleegde primaire bronnen

Laatst gewijzigd op 17 november 2026