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

# Custom UserProviders in packages

> Hoe je vanuit een Laravel-package de opslag van geauthenticeerde gebruikers uitbreidt en het UserProvider-contract, de registratie met Auth::provider, sessies en het rehashen van wachtwoorden veilig implementeert.

Als je package gebruikers ophaalt uit iets anders dan het standaard Eloquent-model of de database van Laravel, registreer je een eigen `UserProvider`. Zo kun je bijvoorbeeld een externe directory, een bestaand ledensysteem of een eigen API als opslag voor authenticatie gebruiken.

Dit is iets anders dan een nieuwe guard maken. Je levert alleen de implementatie die gebruikers opzoekt en verifieert voor de bestaande `session`- of `token`-guards. Wil je de authenticatiemethode van de guard zelf wijzigen, zie dan [Een custom authenticatieguard implementeren](https://kawax.biz/nl/advanced/custom-auth-guard.md).

> [!NOTE]
>
> Deze pagina is gericht op Laravel 13 en verwijst naar de `13.x`-branch van de officiële documentatie en de implementatie in Framework `v13.43.0`. Controleer de contractmethoden en het gedrag van het rehashen van wachtwoorden in elke Laravel-versie die je package ondersteunt.

## De verantwoordelijkheden van guard en UserProvider scheiden

De guard die `Auth::guard()` teruggeeft, haalt de authenticatiestatus uit de sessie of het request. Wanneer de guard een gebruiker nodig heeft, delegeert hij dat aan de geconfigureerde provider.

```mermaid theme={null}
sequenceDiagram
    participant G as SessionGuard
    participant P as UserProvider
    participant S as Externe gebruikersopslag
    G->>P: retrieveById / retrieveByCredentials
    P->>S: Gebruiker opzoeken
    S-->>P: Opgeslagen data
    P-->>G: Authenticatable of null
    G->>P: validateCredentials
    P-->>G: true of false
```

| Uitbreidingspunt | Belangrijkste verantwoordelijkheid | Waar het wordt ingesteld |
| - | - | - |
| Guard | Beheert de authenticatiestatus vanuit request, sessie of token | `auth.guards` |
| UserProvider | Haalt gebruikers op, valideert wachtwoorden en werkt remember tokens bij | `auth.providers` |
| Authenticatable | Maakt de attribuutnamen van de auth-ID, het wachtwoord en het remember token beschikbaar | Gebruikersobject |

De waarde die een `UserProvider` teruggeeft, moet een object zijn dat `Illuminate\Contracts\Auth\Authenticatable` implementeert, geen array uit de opslag of een SDK-response.

## `Auth::provider` registreren vanuit een package

### Registreren in de `boot` van de service provider

Laravel roept de callback die je met `Auth::provider($name, $callback)` registreert aan op basis van de waarde van `auth.providers.*.driver`. De callback krijgt de applicatie en de providerconfiguratie mee.

Registreer hem in de service provider van je package voordat de authenticatieservices worden gebruikt.

```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` en `DirectoryUserProvider` zijn klassen die je package in de container registreert. `$config` komt uit de `auth.php` van de applicatie die het package gebruikt, dus daaruit kun je de verbindingsnaam, tenant en andere waarden lezen die nodig zijn om de provider te maken.

`Auth::provider` registreert de naam van een authenticatie-**user provider**. Dat is een ander uitbreidingspunt dan de custom guard-driver die `Auth::extend` registreert. Ook als je beide gebruikt, houd je de verantwoordelijkheden van de guard en die van de gebruikersopslag in aparte klassen.

### Provider en guard koppelen in `auth.php`

Geef de geregistreerde naam op als `driver` in `auth.providers` en verwijs vanuit een guard naar die provider.

```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',
        ],
    ],
];
```

De configuratie hangt als volgt samen.

1. De guard `directory-web` verwijst naar de provider `directory-users`.
2. De `driver` van `directory-users` is `directory`, dus de callback van hierboven wordt gekozen.
3. Er wordt een `SessionGuard` aangemaakt die gebruikers ophaalt via de gegenereerde `UserProvider`.

`AuthManager` cachet een guard de eerste keer dat hij wordt opgelost. Er is geen API die een al opgeloste guard na de providerregistratie vervangt, dus let op de bootvolgorde van service providers en op het gebruik van `Auth::forgetGuards()` in tests. Als de `auth`-configuratie gecachet wordt, lees verbindingsgegevens dan niet rechtstreeks uit omgevingsvariabelen, maar los ze op in de configuratie en geef ze daarna door aan de callback.

## Het `UserProvider`-contract implementeren

In Laravel 13 vereist `Illuminate\Contracts\Auth\UserProvider` de volgende zes methoden.

```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,
    );
}
```

De drie ophaalmethoden geven een gebruiker of `null` terug; een niet-gevonden gebruiker wordt niet met een exception aangegeven. Het contract van je package bepaalt of time-outs en communicatiestoringen van de opslag `null` worden of een herhaalbare exception. Belangrijk is dat je storingen van de opslag niet verbergt achter hetzelfde "ongeldige inloggegevens" als een mislukte authenticatie.

### Een `Authenticatable` teruggeven

Dit minimale voorbeeld zet een record uit de externe opslag om naar een `GenericUser` in plaats van het ongewijzigd terug te geven. Een echt package kan een eigen gebruikersklasse bieden zodat gebruikers getypeerd bij extra attributen kunnen.

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

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

    // Gaat uit van een record met id, password en remember_token.
    return new GenericUser($record);
}
```

`GenericUser` gebruikt standaard de attribuutnamen `id`, `password` en `remember_token`. Gebruik je andere namen, overschrijf dan `getAuthIdentifierName()` en verwante methoden in een eigen klasse die `Authenticatable` implementeert.

### Ophalen via ID en remember token

`retrieveById` herstelt de gebruiker uit de auth-ID die in de sessie is opgeslagen. Als je inloggen via remember token ondersteunt, vergelijk je de identifier en het token in de opslag.

```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,
    );
}
```

Beperk de argumenten van `hash_equals` tot de string uit de opslag en het token, en schrijf tokens nooit naar logs. Ondersteunt de externe opslag geen remember tokens, laat `updateRememberToken` dan niet leeg zodat het lijkt te slagen. Geef in de authenticatieconfiguratie van je package duidelijk aan dat de remember-functie niet beschikbaar is.

## Opzoeken van inloggegevens en wachtwoordvalidatie scheiden

### Valideer het wachtwoord niet in `retrieveByCredentials`

`Auth::attempt()` zoekt eerst de gebruiker op met `retrieveByCredentials` en valideert daarna het wachtwoord met `validateCredentials`. Als de zoekmethode ook wachtwoorden vergelijkt, breekt dat de verwerkingsvolgorde die de guard verwacht en het rehashen van wachtwoorden.

```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));
}
```

Sluit niet alleen `password` uit van de zoekcriteria van de opslag, maar ook sleutels zoals `password_confirmation`. Neem wachtwoorden en access tokens nooit op in queries van de zoek-API, logs of cachesleutels. De als zoekcriteria geaccepteerde sleutels beperken tot een allowlist zoals `email` helpt ook om geen willekeurige velden naar een externe API te sturen.

### De hash vergelijken in `validateCredentials`

Gebruik voor de validatie de `Hasher` van de applicatie, en stuur wachtwoorden in platte tekst nooit naar de opslag of naar 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);
}
```

Geef `false` terug als `$credentials['password']` ontbreekt of de gebruiker geen wachtwoord heeft. Delegeer je de validatie aan een externe authenticatie-API, houd je dan aan hetzelfde contract en behandel fouten, time-outs en rate limits volgens het exceptionbeleid van je package.

## Het rehashen van wachtwoorden behouden

Na een geslaagde login kan Laravel controleren of een rehash nodig is voor het ingestelde hash-algoritme. Een custom provider implementeert `rehashPasswordIfRequired` en werkt de hash in de opslag alleen bij wanneer dat nodig is.

```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),
    );
}
```

Omdat dit naar de externe opslag schrijft, mag je fouten bij het rehashen niet negeren. Blijft het wachtwoordattribuut van het gebruikersobject na de update verouderd, dan kan het rehashen bij de volgende login opnieuw gebeuren. Leg ook als vereiste van je package vast dat de gebruikte `Hasher` overeenkomt met het wachtwoordformaat van de opslag.

## De service provider en de authenticatieflow testen

Vervang in de tests van je package de opslagclient door een fake en controleer elke verantwoordelijkheid van de `UserProvider` afzonderlijk. Controleer vooral deze drie punten los van elkaar.

* `retrieveByCredentials` geeft het wachtwoord niet door aan de client.
* Alleen een juiste hash komt door `validateCredentials`.
* De update-API wordt alleen aangeroepen als een rehash nodig is.

```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());
}
```

Vervang `expects` hierboven door de API van de mockbibliotheek die je gebruikt. Gebruik je een echte HTTP-client, controleer dan de verzonden inhoud met een HTTP-fake en test dat het wachtwoord in platte tekst nooit in requests of logs verschijnt.

Controleer in integratietests die de registratie met `Auth::provider` bevatten met Testbench of iets vergelijkbaars de volgende volgorde.

1. Laad de service provider van het package.
2. Stel de custom `driver` in `auth.providers` in.
3. Verwijs vanuit `auth.guards` naar die provider.
4. Los de guard voor het eerst op en controleer dat het ophalen van gebruikers aan de fake client wordt gedelegeerd.
5. Roep in tests die configuratie of registratie wijzigen `Auth::forgetGuards()` aan voordat je naar de volgende case gaat.

## Compatibiliteit bij updates ontwerpen

Een `UserProvider` ligt op de grens van authenticatie, dus controleer bij een package-update het volgende.

* Als je de attribuutnamen van ID, wachtwoord of remember token van de `Authenticatable` wijzigt, bepaal dan hoe bestaande sessies en remember cookies worden behandeld.
* Als je het ID-formaat of het wachtwoord-hash-algoritme van de externe opslag wijzigt, controleer dan of bestaande gebruikers nog hersteld kunnen worden en kunnen inloggen.
* Als je de toegestane sleutels van `retrieveByCredentials` beperkt, controleer dan de compatibiliteit met de voorwaarden die gebruikers aan `Auth::attempt` doorgaven.
* Onderscheid storingen van de opslag van mislukte authenticatie, en kies een beleid waarbij gebruikers op het loginscherm niet ten onrechte hun wachtwoord opnieuw moeten invoeren.
* Controleer de configuratiecache en je deploystappen voordat je de providernaam, de configuratiesleutels in `auth.php` of de verbindingsinstellingen verwijdert.

Behandel "uit welke opslag en wat je als gebruiker teruggeeft" en "met welke hash wachtwoorden worden beheerd" als publiek contract van je package, en laat de omgang met inloggegevens niet volledig aan de applicatie over.

## Gerelateerde pagina's

> [card] [Een custom authenticatieguard implementeren](https://kawax.biz/nl/advanced/custom-auth-guard.md)
>
> Lees hoe je de guard zelf uitbreidt en gebruikers oplost vanuit sessies of API-tokens.

> [card] [Service providers](https://kawax.biz/nl/service-providers.md)
>
> Lees de basis voor het registreren van de service provider van je package en het toepassen van uitbreidingen bij het booten.

## Geraadpleegde primaire bronnen

* [Officiële Laravel-documentatie: Adding Custom User Providers](https://github.com/laravel/docs/blob/13.x/authentication.md#adding-custom-user-providers)
* [Officiële Laravel-documentatie: User Provider Contract](https://github.com/laravel/docs/blob/13.x/authentication.md#the-user-provider-contract)
* [AuthManager: provider() en het oplossen van guards](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/AuthManager.php)
* [CreatesUserProviders: aanmaken van custom providers](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: standaardimplementatie](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/EloquentUserProvider.php)
* [GenericUser: Authenticatable op basis van attributen](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/GenericUser.php)


## Related topics

- [Geavanceerde onderwerpen](https://kawax.biz/nl/advanced/index.md)
- [Een custom authenticatieguard implementeren](https://kawax.biz/nl/advanced/custom-auth-guard.md)
- [Upgraden van Laravel 10 naar 11](https://kawax.biz/nl/blog/upgrade-10-to-11.md)
- [Custom providers](https://kawax.biz/nl/packages/laravel-copilot-sdk/custom-providers.md)
- [Custom validatieregels](https://kawax.biz/nl/advanced/custom-validation-rules.md)


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