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 dieAuth::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 guard
directory-webverwijst naar de providerdirectory-users. - De
drivervandirectory-usersisdirectory, dus de callback van hierboven wordt gekozen. - Er wordt een
SessionGuardaangemaakt die gebruikers ophaalt via de gegenereerdeUserProvider.
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.
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.
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.
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.
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 implementeertrehashPasswordIfRequired en werkt de hash in de opslag alleen bij wanneer dat nodig is.
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 deUserProvider afzonderlijk. Controleer vooral deze drie punten los van elkaar.
retrieveByCredentialsgeeft 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.
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.
- Laad de service provider van het package.
- Stel de custom
driverinauth.providersin. - Verwijs vanuit
auth.guardsnaar die provider. - Los de guard voor het eerst op en controleer dat het ophalen van gebruikers aan de fake client wordt gedelegeerd.
- Roep in tests die configuratie of registratie wijzigen
Auth::forgetGuards()aan voordat je naar de volgende case gaat.
Compatibiliteit bij updates ontwerpen
EenUserProvider 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
Authenticatablewijzigt, 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
retrieveByCredentialsbeperkt, controleer dan de compatibiliteit met de voorwaarden die gebruikers aanAuth::attemptdoorgaven. - 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.phpof de verbindingsinstellingen verwijdert.
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
- Officiële Laravel-documentatie: Adding Custom User Providers
- Officiële Laravel-documentatie: User Provider Contract
- AuthManager: provider() en het oplossen van guards
- CreatesUserProviders: aanmaken van custom providers
- UserProvider contract
- Authenticatable contract
- EloquentUserProvider: standaardimplementatie
- GenericUser: Authenticatable op basis van attributen