UserProvider. Ad esempio, puoi usare una directory esterna, un sistema di iscritti esistente o un’API dedicata come archivio per l’autenticazione.
È diverso dal creare un nuovo guard. Fornisci solo l’implementazione che cerca e verifica gli utenti per i guard esistenti session o token. Se vuoi cambiare il metodo di autenticazione del guard stesso, consulta Implementare un guard di autenticazione personalizzato.
Questa pagina riguarda Laravel 13 e fa riferimento al branch
13.x della documentazione ufficiale e all’implementazione di Framework v13.43.0. Verifica i metodi del contratto e il comportamento del rehash delle password in ogni versione di Laravel supportata dal tuo pacchetto.Separare le responsabilità di guard e UserProvider
Il guard restituito daAuth::guard() ricava lo stato di autenticazione dalla sessione o dalla richiesta. Quando il guard deve recuperare un utente, delega al provider configurato.
Il valore restituito da un
UserProvider deve essere un oggetto che implementa Illuminate\Contracts\Auth\Authenticatable, non un array dell’archivio né una risposta di un SDK.
Registrare Auth::provider da un pacchetto
Registrare nel boot del service provider
Laravel invoca la callback registrata con Auth::provider($name, $callback) in base al valore di auth.providers.*.driver. La callback riceve l’applicazione e la configurazione del provider.
Nel service provider del pacchetto, registrala prima che vengano usati i servizi di autenticazione.
DirectoryClientManager e DirectoryUserProvider sono classi che il pacchetto registra nel container. $config arriva dal file auth.php dell’applicazione che usa il pacchetto, quindi puoi leggere da lì il nome della connessione, il tenant e gli altri valori necessari per creare il provider.
Auth::provider registra il nome di un user provider di autenticazione. È un punto di estensione distinto dal driver di guard personalizzato registrato da Auth::extend. Anche se usi entrambi, mantieni le responsabilità del guard e quelle dell’archivio utenti in classi separate.
Collegare provider e guard in auth.php
Indica il nome registrato come driver in auth.providers e fai riferimento a quel provider da un guard.
- Il guard
directory-webfa riferimento al providerdirectory-users. - Il
driverdidirectory-usersèdirectory, quindi viene scelta la callback vista sopra. - Viene creato un
SessionGuardche recupera gli utenti tramite ilUserProvidergenerato.
AuthManager mette in cache il guard alla prima risoluzione. Non esiste un’API che sostituisca un guard già risolto dopo la registrazione del provider, quindi fai attenzione all’ordine di avvio dei service provider e all’uso di Auth::forgetGuards() nei test. Se la configurazione auth è in cache, non leggere i dati di connessione direttamente dalle variabili d’ambiente: risolvili nella configurazione e poi passali alla callback.
Implementare il contratto UserProvider
In Laravel 13, Illuminate\Contracts\Auth\UserProvider richiede i sei metodi seguenti.
null; un utente non trovato non viene rappresentato con un’eccezione. È il contratto del pacchetto a decidere se timeout e guasti di comunicazione dell’archivio diventano null o un’eccezione ripetibile. L’importante è non nascondere i guasti dell’archivio dietro lo stesso “credenziali non valide” di un fallimento di autenticazione.
Restituire un Authenticatable
Questo esempio minimo converte un record dell’archivio esterno in un GenericUser invece di restituirlo così com’è. Un pacchetto reale può fornire una propria classe utente per offrire un accesso tipizzato agli attributi aggiuntivi.
GenericUser usa per impostazione predefinita i nomi di attributo id, password e remember_token. Se usi nomi diversi, sovrascrivi getAuthIdentifierName() e i metodi correlati in una classe dedicata che implementa Authenticatable.
Recuperare per ID e remember token
retrieveById ripristina l’utente dall’ID di autenticazione salvato in sessione. Se supporti il login con remember token, confronta identificativo e token nell’archivio.
hash_equals alla stringa ottenuta dall’archivio e al token, e non scrivere mai i token nei log. Se l’archivio esterno non supporta i remember token, non lasciare updateRememberToken vuoto facendolo sembrare riuscito. Indica chiaramente nella configurazione di autenticazione del pacchetto che la funzione “ricordami” non è disponibile.
Separare la ricerca delle credenziali dalla verifica della password
Non verificare la password in retrieveByCredentials
Auth::attempt() cerca prima l’utente con retrieveByCredentials e poi verifica la password con validateCredentials. Se il metodo di ricerca confronta anche le password, rompe l’ordine di elaborazione previsto dal guard e il rehash delle password.
password, ma anche chiavi come password_confirmation. Non includere mai password o access token nelle query dell’API di ricerca, nei log o nelle chiavi di cache. Limitare le chiavi accettate come criteri a una allowlist come email è utile anche per non passare campi arbitrari a un’API esterna.
Confrontare l’hash in validateCredentials
Per la verifica usa l’Hasher dell’applicazione, e non inviare mai password in chiaro all’archivio né scriverle nei log.
false se $credentials['password'] manca o se l’utente non ha una password. Se deleghi la verifica a un’API di autenticazione esterna, rispetta lo stesso contratto e gestisci errori, timeout e rate limit secondo la politica delle eccezioni del pacchetto.
Mantenere il rehash delle password
Dopo un login riuscito, Laravel può verificare se serve un rehash per l’algoritmo di hash configurato. Un provider personalizzato implementarehashPasswordIfRequired e aggiorna l’hash nell’archivio solo quando serve.
Hasher usato corrisponda al formato delle password dell’archivio.
Testare il service provider e il flusso di autenticazione
Nei test del pacchetto, sostituisci il client dell’archivio con un fake e verifica separatamente ogni responsabilità delUserProvider. In particolare, controlla separatamente questi tre punti.
retrieveByCredentialsnon passa la password al client.- Solo un hash corretto supera
validateCredentials. - L’API di aggiornamento viene chiamata solo quando serve un rehash.
expects dell’esempio con l’API della libreria di mock che usi. Se usi un vero client HTTP, verifica il contenuto inviato con un HTTP fake e testa che la password in chiaro non compaia mai nelle richieste o nei log.
Nei test di integrazione che includono la registrazione con Auth::provider, verifica con Testbench o strumenti simili il seguente ordine.
- Caricare il service provider del pacchetto.
- Impostare il
driverpersonalizzato inauth.providers. - Fare riferimento a quel provider da
auth.guards. - Risolvere il guard per la prima volta e verificare che il recupero degli utenti sia delegato al client fake.
- Nei test che modificano configurazione o registrazione, chiamare
Auth::forgetGuards()prima di passare al caso successivo.
Progettare la compatibilità tra aggiornamenti
UnUserProvider si trova al confine dell’autenticazione, quindi quando aggiorni il pacchetto verifica quanto segue.
- Se cambi i nomi degli attributi di ID, password o remember token dell’
Authenticatable, decidi come gestire le sessioni e i remember cookie esistenti. - Se cambi il formato degli ID o l’algoritmo di hash delle password dell’archivio esterno, verifica che gli utenti esistenti possano ancora essere ripristinati ed effettuare il login.
- Se restringi le chiavi consentite in
retrieveByCredentials, verifica la compatibilità con le condizioni che gli utilizzatori passavano adAuth::attempt. - Distingui i guasti dell’archivio dai fallimenti di autenticazione e definisci una politica che non costringa a reinserire una password presunta errata nella schermata di login.
- Prima di rimuovere il nome del provider, le chiavi di configurazione di
auth.phpo le impostazioni di connessione, controlla la cache della configurazione e la procedura di deploy.
Pagine correlate
Implementare un guard di autenticazione personalizzato
Scopri come estendere il guard stesso e risolvere gli utenti da sessioni o token API.
Service provider
Ripassa le basi per registrare il service provider del pacchetto e applicare le estensioni all’avvio.
Fonti primarie consultate
- Documentazione ufficiale di Laravel: Adding Custom User Providers
- Documentazione ufficiale di Laravel: User Provider Contract
- AuthManager: provider() e risoluzione dei guard
- CreatesUserProviders: creazione di provider personalizzati
- UserProvider contract
- Authenticatable contract
- EloquentUserProvider: implementazione predefinita
- GenericUser: Authenticatable creato dagli attributi