Passer au contenu principal
Lorsque votre package récupère des utilisateurs ailleurs que dans le modèle Eloquent ou la base de données standard de Laravel, enregistrez votre propre 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é par Auth::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.
Cette configuration se lit comme suit.
  1. Le guard directory-web référence le provider directory-users.
  2. Le driver de directory-users est directory : le callback ci-dessus est donc sélectionné.
  3. Un SessionGuard est créé et récupère les utilisateurs via le UserProvider gé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.
Les trois méthodes de récupération renvoient un utilisateur ou 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.
Limitez les arguments de 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.
Excluez des critères de recherche du stockage non seulement 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.
Renvoyez 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émente rehashPasswordIfRequired et ne met à jour le hash dans le stockage que lorsque c’est nécessaire.
Comme cette opération écrit dans le stockage externe, n’ignorez pas les échecs de rehash. Si l’attribut mot de passe de l’objet utilisateur reste obsolète après la mise à jour, le rehash peut se répéter à la connexion suivante. Documentez aussi comme exigence du package que le 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é du UserProvider. Vérifiez en particulier ces trois points séparément.
  • retrieveByCredentials ne 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.
Remplacez 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.
  1. Charger le service provider du package.
  2. Définir le driver personnalisé dans auth.providers.
  3. Référencer ce provider depuis auth.guards.
  4. 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.
  5. 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

Un UserProvider 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.php ou les paramètres de connexion, vérifiez le cache de configuration et la procédure de déploiement.
Traitez « depuis quel stockage et quoi renvoyer comme utilisateur » et « avec quel hash gérer les mots de passe » comme le contrat public du package, et ne laissez pas entièrement la gestion des identifiants à l’application.

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

Dernière modification le 17 novembre 2026