Vai al contenuto principale
Quando il tuo pacchetto recupera gli utenti da una fonte diversa dal modello Eloquent o dal database standard di Laravel, registra un tuo 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 da Auth::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.
La corrispondenza di questa configurazione è la seguente.
  1. Il guard directory-web fa riferimento al provider directory-users.
  2. Il driver di directory-users è directory, quindi viene scelta la callback vista sopra.
  3. Viene creato un SessionGuard che recupera gli utenti tramite il UserProvider generato.
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.
I tre metodi di recupero restituiscono un utente o 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.
Limita gli argomenti di 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.
Escludi dai criteri di ricerca dell’archivio non solo 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.
Restituisci 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 implementa rehashPasswordIfRequired e aggiorna l’hash nell’archivio solo quando serve.
Poiché questa operazione scrive nell’archivio esterno, non ignorare gli errori di rehash. Se l’attributo password dell’oggetto utente resta obsoleto dopo l’aggiornamento, il rehash può ripetersi al login successivo. Documenta inoltre come requisito del pacchetto che l’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à del UserProvider. In particolare, controlla separatamente questi tre punti.
  • retrieveByCredentials non passa la password al client.
  • Solo un hash corretto supera validateCredentials.
  • L’API di aggiornamento viene chiamata solo quando serve un rehash.
Sostituisci 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.
  1. Caricare il service provider del pacchetto.
  2. Impostare il driver personalizzato in auth.providers.
  3. Fare riferimento a quel provider da auth.guards.
  4. Risolvere il guard per la prima volta e verificare che il recupero degli utenti sia delegato al client fake.
  5. Nei test che modificano configurazione o registrazione, chiamare Auth::forgetGuards() prima di passare al caso successivo.

Progettare la compatibilità tra aggiornamenti

Un UserProvider 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 ad Auth::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.php o le impostazioni di connessione, controlla la cache della configurazione e la procedura di deploy.
Tratta “da quale archivio e cosa restituire come utente” e “con quale hash gestire le password” come contratto pubblico del pacchetto, senza lasciare la gestione delle credenziali interamente all’applicazione.

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

Ultima modifica il 17 novembre 2026