UserProvider. Vous pouvez par exemple utiliser un annuaire externe, un système de membres existant ou une API dédiée comme stockage pour l’authentification.
Ce n’est pas la même chose que créer un nouveau guard. Vous fournissez seulement l’implémentation qui recherche et vérifie les utilisateurs pour les guards existants session ou token. Pour modifier la méthode d’authentification du guard lui-même, consultez Implémenter un guard d’authentification personnalisé.
Cette page cible Laravel 13 et s’appuie sur la branche
13.x de la documentation officielle et sur l’implémentation de Framework v13.43.0. Vérifiez les méthodes du contrat et le comportement du rehash des mots de passe dans chaque version de Laravel prise en charge par votre package.Séparer les responsabilités du guard et du UserProvider
Le guard renvoyé parAuth::guard() lit l’état d’authentification depuis la session ou la requête. Lorsque le guard récupère un utilisateur, il délègue au provider configuré.
La valeur renvoyée par un
UserProvider doit être un objet qui implémente Illuminate\Contracts\Auth\Authenticatable, et non un tableau du stockage ou une réponse de SDK.
Enregistrer Auth::provider depuis un package
Enregistrer dans le boot du service provider
Laravel appelle le callback enregistré avec Auth::provider($name, $callback) selon la valeur de auth.providers.*.driver. Le callback reçoit l’application et la configuration du provider.
Dans le service provider du package, enregistrez-le avant que les services d’authentification ne soient utilisés.
DirectoryClientManager et DirectoryUserProvider sont des classes que le package enregistre dans le conteneur. $config provient du auth.php de l’application qui utilise le package : vous pouvez y lire le nom de connexion, le tenant et les autres valeurs nécessaires à la création du provider.
Auth::provider enregistre le nom d’un user provider d’authentification. C’est un point d’extension distinct du driver de guard personnalisé enregistré par Auth::extend. Même si vous utilisez les deux, gardez les responsabilités du guard et celles du stockage d’utilisateurs dans des classes séparées.
Relier le provider et le guard dans auth.php
Indiquez le nom enregistré comme driver dans auth.providers, puis référencez ce provider depuis un guard.
- Le guard
directory-webréférence le providerdirectory-users. - Le
driverdedirectory-usersestdirectory: le callback ci-dessus est donc sélectionné. - Un
SessionGuardest créé et récupère les utilisateurs via leUserProvidergénéré.
AuthManager met en cache un guard lors de sa première résolution. Aucune API ne remplace un guard déjà résolu après l’enregistrement du provider : faites donc attention à l’ordre de démarrage des service providers et à l’usage de Auth::forgetGuards() dans les tests. Si la configuration auth est mise en cache, ne lisez pas les informations de connexion directement depuis les variables d’environnement : résolvez-les dans la configuration avant de les passer au callback.
Implémenter le contrat UserProvider
Dans Laravel 13, Illuminate\Contracts\Auth\UserProvider exige les six méthodes suivantes.
null ; un utilisateur introuvable n’est pas représenté par une exception. C’est le contrat de votre package qui décide si les timeouts et pannes de communication du stockage deviennent null ou une exception rejouable. L’essentiel est de ne pas masquer les pannes du stockage derrière le même “identifiants invalides” qu’un échec d’authentification.
Renvoyer un Authenticatable
Cet exemple minimal convertit un enregistrement du stockage externe en GenericUser au lieu de le renvoyer tel quel. Un vrai package peut fournir sa propre classe d’utilisateur pour offrir un accès typé aux attributs supplémentaires.
GenericUser utilise par défaut les noms d’attribut id, password et remember_token. Pour d’autres noms, surchargez getAuthIdentifierName() et les méthodes associées dans une classe dédiée qui implémente Authenticatable.
Récupérer par ID et par remember token
retrieveById restaure l’utilisateur à partir de l’identifiant d’authentification stocké en session. Si vous prenez en charge la connexion par remember token, comparez l’identifiant et le token dans le stockage.
hash_equals à la chaîne obtenue du stockage et au token, et n’écrivez jamais les tokens dans les logs. Si le stockage externe ne prend pas en charge les remember tokens, ne laissez pas updateRememberToken vide pour faire croire à un succès. Indiquez clairement dans la configuration d’authentification du package que la fonction « se souvenir de moi » n’est pas disponible.
Séparer la recherche des identifiants et la vérification du mot de passe
Ne pas vérifier le mot de passe dans retrieveByCredentials
Auth::attempt() recherche d’abord l’utilisateur avec retrieveByCredentials, puis vérifie le mot de passe avec validateCredentials. Si la méthode de recherche compare aussi les mots de passe, elle casse l’ordre de traitement attendu par le guard ainsi que le rehash des mots de passe.
password, mais aussi des clés comme password_confirmation. N’incluez jamais de mots de passe ou de tokens d’accès dans les requêtes de l’API de recherche, les logs ou les clés de cache. Restreindre les clés acceptées comme critères à une liste autorisée comme email évite aussi de transmettre des champs arbitraires à une API externe.
Comparer le hash dans validateCredentials
Utilisez le Hasher de l’application pour la vérification, et n’envoyez jamais de mot de passe en clair au stockage ni dans les logs.
false si $credentials['password'] est absent ou si l’utilisateur n’a pas de mot de passe. Si vous déléguez la vérification à une API d’authentification externe, respectez le même contrat et traitez les échecs, timeouts et limitations de débit selon la politique d’exceptions du package.
Préserver le rehash des mots de passe
Après une connexion réussie, Laravel peut vérifier si un rehash est nécessaire pour l’algorithme de hachage configuré. Un provider personnalisé implémenterehashPasswordIfRequired et ne met à jour le hash dans le stockage que lorsque c’est nécessaire.
Hasher utilisé correspond au format de mot de passe du stockage.
Tester le service provider et le flux d’authentification
Dans les tests du package, remplacez le client du stockage par un fake et vérifiez séparément chaque responsabilité duUserProvider. Vérifiez en particulier ces trois points séparément.
retrieveByCredentialsne transmet pas le mot de passe au client.- Seul un hash correct passe
validateCredentials. - L’API de mise à jour n’est appelée que lorsqu’un rehash est nécessaire.
expects ci-dessus par l’API de la bibliothèque de mocks que vous utilisez. Avec un vrai client HTTP, vérifiez le contenu envoyé avec un fake HTTP et testez que le mot de passe en clair n’apparaît jamais dans les requêtes ni dans les logs.
Dans les tests d’intégration qui incluent l’enregistrement via Auth::provider, vérifiez l’ordre suivant avec Testbench ou un outil similaire.
- Charger le service provider du package.
- Définir le
driverpersonnalisé dansauth.providers. - Référencer ce provider depuis
auth.guards. - Résoudre le guard pour la première fois et confirmer que la récupération des utilisateurs est déléguée au client fake.
- Dans les tests qui modifient la configuration ou l’enregistrement, appeler
Auth::forgetGuards()avant de passer au cas suivant.
Concevoir la compatibilité lors des mises à jour
UnUserProvider se situe à la frontière de l’authentification : lors d’une mise à jour du package, vérifiez les points suivants.
- Si vous changez les noms d’attribut de l’ID, du mot de passe ou du remember token de l’
Authenticatable, décidez comment traiter les sessions et remember cookies existants. - Si vous changez le format d’ID ou l’algorithme de hachage des mots de passe du stockage externe, vérifiez que les utilisateurs existants peuvent toujours être restaurés et se connecter.
- Si vous restreignez les clés autorisées de
retrieveByCredentials, vérifiez la compatibilité avec les conditions que les utilisateurs du package passaient àAuth::attempt. - Distinguez les pannes du stockage des échecs d’authentification, et définissez une politique qui n’oblige pas à ressaisir à tort un mot de passe sur l’écran de connexion.
- Avant de supprimer le nom du provider, les clés de configuration de
auth.phpou les paramètres de connexion, vérifiez le cache de configuration et la procédure de déploiement.
Pages associées
Implémenter un guard d'authentification personnalisé
Découvrez comment étendre le guard lui-même et résoudre les utilisateurs depuis la session ou un token d’API.
Service providers
Revoyez les bases pour enregistrer le service provider du package et appliquer des extensions au démarrage.
Sources primaires consultées
- Documentation officielle Laravel: Adding Custom User Providers
- Documentation officielle Laravel: User Provider Contract
- AuthManager: provider() et résolution des guards
- CreatesUserProviders: création de providers personnalisés
- UserProvider contract
- Authenticatable contract
- EloquentUserProvider: implémentation par défaut
- GenericUser: Authenticatable construit à partir d’attributs