> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# UserProvider personnalisé dans un package

> Comment étendre depuis un package Laravel l'emplacement de stockage des utilisateurs authentifiés et implémenter en toute sécurité le contrat UserProvider, l'enregistrement via Auth::provider, les sessions et le rehash des mots de passe.

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é](https://kawax.biz/fr/advanced/custom-auth-guard.md).

> [!NOTE]
>
> 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é.

```mermaid theme={null}
sequenceDiagram
    participant G as SessionGuard
    participant P as UserProvider
    participant S as Stockage d'utilisateurs externe
    G->>P: retrieveById / retrieveByCredentials
    P->>S: Rechercher l'utilisateur
    S-->>P: Données stockées
    P-->>G: Authenticatable ou null
    G->>P: validateCredentials
    P-->>G: true ou false
```

| Point d'extension | Responsabilité principale | Où le configurer |
| - | - | - |
| Guard | Gère l'état d'authentification à partir de la requête, de la session ou du token | `auth.guards` |
| UserProvider | Récupère les utilisateurs, vérifie les mots de passe et met à jour le remember token | `auth.providers` |
| Authenticatable | Expose les noms d'attribut de l'identifiant d'authentification, du mot de passe et du remember token | Objet utilisateur |

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.

```php theme={null}
<?php

namespace Acme\Directory;

use Illuminate\Contracts\Auth\UserProvider;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\ServiceProvider;

final class DirectoryServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Auth::provider('directory', function (
            Application $app,
            array $config,
        ): UserProvider {
            return new DirectoryUserProvider(
                $app->make(DirectoryClientManager::class)
                    ->connection($config['connection'] ?? 'default'),
                $app->make('hash'),
            );
        });
    }
}
```

`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.

```php theme={null}
// config/auth.php
return [
    'defaults' => [
        'guard' => 'directory-web',
        'passwords' => 'users',
    ],

    'guards' => [
        'directory-web' => [
            'driver' => 'session',
            'provider' => 'directory-users',
        ],
    ],

    'providers' => [
        'directory-users' => [
            'driver' => 'directory',
            'connection' => 'primary-directory',
        ],
    ],
];
```

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.

```php theme={null}
interface UserProvider
{
    public function retrieveById($identifier);
    public function retrieveByToken($identifier, $token);
    public function updateRememberToken(Authenticatable $user, $token);
    public function retrieveByCredentials(array $credentials);
    public function validateCredentials(Authenticatable $user, array $credentials);
    public function rehashPasswordIfRequired(
        Authenticatable $user,
        array $credentials,
        bool $force = false,
    );
}
```

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.

```php theme={null}
use Illuminate\Auth\GenericUser;
use Illuminate\Contracts\Auth\Authenticatable;

private function makeUser(?array $record): ?Authenticatable
{
    if ($record === null) {
        return null;
    }

    // Suppose un enregistrement contenant id, password et remember_token.
    return new GenericUser($record);
}
```

`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.

```php theme={null}
public function retrieveById($identifier): ?Authenticatable
{
    return $this->makeUser($this->client->find($identifier));
}

public function retrieveByToken(
    $identifier,
    #[\SensitiveParameter] $token,
): ?Authenticatable {
    $record = $this->client->find($identifier);
    $rememberToken = $record['remember_token'] ?? null;

    if (! is_string($rememberToken) || ! hash_equals($rememberToken, $token)) {
        return null;
    }

    return $this->makeUser($record);
}

public function updateRememberToken(
    Authenticatable $user,
    #[\SensitiveParameter] $token,
): void {
    $this->client->updateRememberToken(
        $user->getAuthIdentifier(),
        $token,
    );
}
```

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.

```php theme={null}
use Illuminate\Contracts\Auth\Authenticatable;

public function retrieveByCredentials(
    #[\SensitiveParameter] array $credentials,
): ?Authenticatable {
    $criteria = array_filter(
        $credentials,
        fn (string $key): bool => ! str_contains($key, 'password'),
        ARRAY_FILTER_USE_KEY,
    );

    if ($criteria === []) {
        return null;
    }

    return $this->makeUser($this->client->findBy($criteria));
}
```

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.

```php theme={null}
use Illuminate\Contracts\Auth\Authenticatable;
use Illuminate\Contracts\Hashing\Hasher;

public function validateCredentials(
    Authenticatable $user,
    #[\SensitiveParameter] array $credentials,
): bool {
    $plain = $credentials['password'] ?? null;
    $hashed = $user->getAuthPassword();

    if (! is_string($plain) || ! is_string($hashed)) {
        return false;
    }

    return $this->hasher->check($plain, $hashed);
}
```

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.

```php theme={null}
public function rehashPasswordIfRequired(
    Authenticatable $user,
    #[\SensitiveParameter] array $credentials,
    bool $force = false,
): void {
    $plain = $credentials['password'] ?? null;
    $currentHash = $user->getAuthPassword();

    if (! is_string($plain) || ! is_string($currentHash)) {
        return;
    }

    if (! $force && ! $this->hasher->needsRehash($currentHash)) {
        return;
    }

    $this->client->updatePassword(
        $user->getAuthIdentifier(),
        $this->hasher->make($plain),
    );
}
```

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.

```php theme={null}
public function test_credentials_lookup_does_not_send_password(): void
{
    $this->client->expects('findBy')
        ->with(['email' => 'user@example.com'])
        ->andReturn([
            'id' => 'user-1',
            'password' => $this->hasher->make('secret'),
            'remember_token' => null,
        ]);

    $user = $this->provider->retrieveByCredentials([
        'email' => 'user@example.com',
        'password' => 'secret',
    ]);

    $this->assertSame('user-1', $user?->getAuthIdentifier());
}
```

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

> [card] [Implémenter un guard d'authentification personnalisé](https://kawax.biz/fr/advanced/custom-auth-guard.md)
>
> Découvrez comment étendre le guard lui-même et résoudre les utilisateurs depuis la session ou un token d'API.

> [card] [Service providers](https://kawax.biz/fr/service-providers.md)
>
> 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](https://github.com/laravel/docs/blob/13.x/authentication.md#adding-custom-user-providers)
* [Documentation officielle Laravel: User Provider Contract](https://github.com/laravel/docs/blob/13.x/authentication.md#the-user-provider-contract)
* [AuthManager: provider() et résolution des guards](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/AuthManager.php)
* [CreatesUserProviders: création de providers personnalisés](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/CreatesUserProviders.php)
* [UserProvider contract](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Contracts/Auth/UserProvider.php)
* [Authenticatable contract](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Contracts/Auth/Authenticatable.php)
* [EloquentUserProvider: implémentation par défaut](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/EloquentUserProvider.php)
* [GenericUser: Authenticatable construit à partir d'attributs](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/GenericUser.php)


## Related topics

- [Sujets avancés](https://kawax.biz/fr/advanced/index.md)
- [Implémenter un guard d'authentification personnalisé](https://kawax.biz/fr/advanced/custom-auth-guard.md)
- [Canaux de notification personnalisés dans un package et vérification de l'envoi](https://kawax.biz/fr/advanced/package-notification-channels.md)
- [Enregistrer et tester des transports de mail dans un package](https://kawax.biz/fr/advanced/package-mail-transports.md)
- [Drivers de session personnalisés pour les packages](https://kawax.biz/fr/advanced/package-session-drivers.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.