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

# Eigene UserProvider in Paketen

> Wie Sie aus einem Laravel-Paket den Speicherort authentifizierter Benutzer erweitern und den UserProvider-Vertrag, die Registrierung mit Auth::provider, Sessions und das Rehashing von Passwörtern sicher implementieren.

Wenn Ihr Paket Benutzer nicht aus Laravels Standard-Eloquent-Modell oder der Datenbank abruft, registrieren Sie einen eigenen `UserProvider`. So können Sie zum Beispiel ein externes Verzeichnis, ein bestehendes Mitgliedersystem oder eine eigene API als Speicher für die Authentifizierung verwenden.

Das unterscheidet sich von der Erweiterung um einen neuen Guard. Sie stellen für die bestehenden Guards `session` oder `token` nur die Implementierung bereit, die Benutzer sucht und prüft. Wenn Sie die Authentifizierungsmethode des Guards selbst ändern möchten, lesen Sie [Eigene Auth-Guards implementieren](https://kawax.biz/de/advanced/custom-auth-guard.md).

> [!NOTE]
>
> Diese Seite bezieht sich auf Laravel 13 und verweist auf den Branch `13.x` der offiziellen Dokumentation sowie auf die Implementierung in Framework `v13.43.0`. Prüfen Sie die Vertragsmethoden und das Verhalten beim Passwort-Rehashing in jeder Laravel-Version, die Ihr Paket unterstützt.

## Zuständigkeiten von Guard und UserProvider trennen

Der von `Auth::guard()` zurückgegebene Guard liest den Authentifizierungsstatus aus der Session oder dem Request. Wenn der Guard einen Benutzer abruft, delegiert er an den konfigurierten Provider.

```mermaid theme={null}
sequenceDiagram
    participant G as SessionGuard
    participant P as UserProvider
    participant S as Externer Benutzerspeicher
    G->>P: retrieveById / retrieveByCredentials
    P->>S: Benutzer suchen
    S-->>P: Gespeicherte Daten
    P-->>G: Authenticatable oder null
    G->>P: validateCredentials
    P-->>G: true oder false
```

| Erweiterungspunkt | Hauptaufgabe | Konfigurationsort |
| - | - | - |
| Guard | Verwaltet den Authentifizierungsstatus aus Request, Session oder Token | `auth.guards` |
| UserProvider | Ruft Benutzer ab, prüft Passwörter und aktualisiert Remember-Tokens | `auth.providers` |
| Authenticatable | Stellt die Attributnamen für Auth-ID, Passwort und Remember-Token bereit | Benutzerobjekt |

Der Rückgabewert eines `UserProvider` muss ein Objekt sein, das `Illuminate\Contracts\Auth\Authenticatable` implementiert, und kein Array aus dem Speicher oder eine SDK-Antwort.

## `Auth::provider` aus einem Paket registrieren

### In der `boot`-Methode des Service-Providers registrieren

Laravel ruft den mit `Auth::provider($name, $callback)` registrierten Callback abhängig vom Wert von `auth.providers.*.driver` auf. Der Callback erhält die Anwendung und die Provider-Konfiguration.

Registrieren Sie ihn im Service-Provider Ihres Pakets, bevor die Authentifizierungsdienste verwendet werden.

```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` und `DirectoryUserProvider` sind Klassen, die Ihr Paket im Container registriert. `$config` stammt aus der `auth.php` der nutzenden Anwendung, daher können Sie daraus den Verbindungsnamen, den Mandanten und andere Werte lesen, die zum Erzeugen des Providers nötig sind.

`Auth::provider` registriert den Namen eines Authentifizierungs-**User-Providers**. Das ist ein anderer Erweiterungspunkt als der Treiber für eigene Guards, den `Auth::extend` registriert. Auch wenn Sie beide verwenden, halten Sie die Aufgaben des Guards und die des Benutzerspeichers in getrennten Klassen.

### Provider und Guard in `auth.php` verbinden

Geben Sie den registrierten Namen als `driver` in `auth.providers` an und referenzieren Sie diesen Provider von einem Guard aus.

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

Die Konfiguration hängt wie folgt zusammen.

1. Der Guard `directory-web` referenziert den Provider `directory-users`.
2. Der `driver` von `directory-users` ist `directory`, daher wird der obige Callback gewählt.
3. Ein `SessionGuard` wird erzeugt und ruft Benutzer über den erzeugten `UserProvider` ab.

`AuthManager` speichert einen Guard bei der ersten Auflösung zwischen. Es gibt keine API, die einen bereits aufgelösten Guard nach der Provider-Registrierung ersetzt. Achten Sie daher auf die Boot-Reihenfolge der Service-Provider und auf `Auth::forgetGuards()` in Tests. Wenn die `auth`-Konfiguration gecacht wird, lesen Sie Verbindungsdaten nicht direkt aus Umgebungsvariablen, sondern lösen Sie sie in die Konfiguration auf und übergeben Sie sie dann an den Callback.

## Den `UserProvider`-Vertrag implementieren

In Laravel 13 verlangt `Illuminate\Contracts\Auth\UserProvider` die folgenden sechs 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,
    );
}
```

Die drei Abrufmethoden geben einen Benutzer oder `null` zurück; ein nicht gefundener Benutzer wird nicht durch eine Exception dargestellt. Ob Timeouts und Kommunikationsfehler des Speichers zu `null` werden oder als wiederholbare Exception gelten, legt der Vertrag Ihres Pakets fest. Wichtig ist, Speicherfehler nicht hinter demselben "ungültige Anmeldedaten" wie einen Authentifizierungsfehler zu verstecken.

### Ein `Authenticatable` zurückgeben

Dieses Minimalbeispiel wandelt einen Datensatz aus dem externen Speicher in einen `GenericUser` um, statt ihn direkt zurückzugeben. Ein echtes Paket kann eine eigene Benutzerklasse bereitstellen, damit Nutzer typisiert auf zusätzliche Attribute zugreifen können.

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

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

    // Geht von einem Datensatz mit id, password und remember_token aus.
    return new GenericUser($record);
}
```

`GenericUser` verwendet standardmäßig die Attributnamen `id`, `password` und `remember_token`. Wenn Sie andere Namen verwenden, überschreiben Sie `getAuthIdentifierName()` und verwandte Methoden in einer eigenen Klasse, die `Authenticatable` implementiert.

### Per ID und Remember-Token abrufen

`retrieveById` stellt den Benutzer aus der in der Session gespeicherten Auth-ID wieder her. Wenn Sie die Anmeldung per Remember-Token unterstützen, gleichen Sie Kennung und Token im Speicher ab.

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

Beschränken Sie die Argumente von `hash_equals` auf den aus dem Speicher gelesenen String und das Token, und schreiben Sie Tokens nie in Logs. Wenn der externe Speicher keine Remember-Tokens unterstützt, lassen Sie `updateRememberToken` nicht leer, sodass es erfolgreich wirkt. Geben Sie stattdessen in der Authentifizierungskonfiguration Ihres Pakets klar an, dass die Remember-Funktion nicht verfügbar ist.

## Suche nach Anmeldedaten und Passwortprüfung trennen

### In `retrieveByCredentials` kein Passwort prüfen

`Auth::attempt()` sucht den Benutzer zuerst mit `retrieveByCredentials` und prüft danach das Passwort mit `validateCredentials`. Wenn die Suchmethode auch Passwörter vergleicht, bricht das die vom Guard erwartete Verarbeitungsreihenfolge und das Passwort-Rehashing.

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

Schließen Sie nicht nur `password`, sondern auch Schlüssel wie `password_confirmation` aus den Suchkriterien des Speichers aus. Nehmen Sie Passwörter und Access-Tokens nie in Abfragen der Such-API, Logs oder Cache-Schlüssel auf. Die als Suchkriterien akzeptierten Schlüssel per Allowlist wie `email` einzuschränken, verhindert zudem, dass beliebige Felder an eine externe API gehen.

### In `validateCredentials` den Hash vergleichen

Verwenden Sie zur Prüfung den `Hasher` der Anwendung, und senden Sie Klartextpasswörter weder an den Speicher noch in 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);
}
```

Geben Sie `false` zurück, wenn `$credentials['password']` fehlt oder der Benutzer kein Passwort hat. Wenn Sie die Prüfung an eine externe Authentifizierungs-API delegieren, halten Sie denselben Vertrag ein und behandeln Sie Fehler, Timeouts und Rate-Limits gemäß der Exception-Strategie Ihres Pakets.

## Passwort-Rehashing beibehalten

Nach einer erfolgreichen Anmeldung kann Laravel prüfen, ob für das konfigurierte Hash-Verfahren ein Rehash nötig ist. Ein eigener Provider implementiert `rehashPasswordIfRequired` und aktualisiert den Hash im Speicher nur bei Bedarf.

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

Da hier in den externen Speicher geschrieben wird, ignorieren Sie Rehash-Fehler nicht. Bleibt das Passwortattribut des Benutzerobjekts nach der Aktualisierung veraltet, kann sich das Rehashing bei der nächsten Anmeldung wiederholen. Dokumentieren Sie außerdem als Paketanforderung, dass der verwendete `Hasher` zum Passwortformat des Speichers passt.

## Service-Provider und Authentifizierungsablauf testen

Ersetzen Sie in den Paket-Tests den Speicher-Client durch ein Fake und prüfen Sie jede Aufgabe des `UserProvider` einzeln. Prüfen Sie insbesondere die folgenden drei Punkte getrennt.

* `retrieveByCredentials` übergibt das Passwort nicht an den Client.
* Nur ein korrekter Hash besteht `validateCredentials`.
* Die Update-API wird nur aufgerufen, wenn ein Rehash nötig ist.

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

Ersetzen Sie `expects` oben durch die API Ihrer Mock-Bibliothek. Wenn Sie einen echten HTTP-Client verwenden, prüfen Sie den gesendeten Inhalt mit einem HTTP-Fake und testen Sie, dass das Klartextpasswort nie in Requests oder Logs erscheint.

Prüfen Sie in Integrationstests einschließlich der `Auth::provider`-Registrierung mit Testbench o. Ä. die folgende Reihenfolge.

1. Den Service-Provider des Pakets laden.
2. Den eigenen `driver` in `auth.providers` setzen.
3. Diesen Provider aus `auth.guards` referenzieren.
4. Den Guard zum ersten Mal auflösen und bestätigen, dass der Benutzerabruf an den Fake-Client delegiert wird.
5. In Tests, die Konfiguration oder Registrierung ändern, vor dem nächsten Fall `Auth::forgetGuards()` aufrufen.

## Kompatibilität bei Updates einplanen

Ein `UserProvider` liegt an der Authentifizierungsgrenze. Prüfen Sie daher bei Paket-Updates Folgendes.

* Wenn Sie die Attributnamen für ID, Passwort oder Remember-Token des `Authenticatable` ändern, legen Sie fest, wie bestehende Sessions und Remember-Cookies behandelt werden.
* Wenn Sie das ID-Format oder das Passwort-Hash-Verfahren des externen Speichers ändern, prüfen Sie, ob bestehende Benutzer wiederhergestellt werden und sich anmelden können.
* Wenn Sie die erlaubten Schlüssel von `retrieveByCredentials` einschränken, prüfen Sie die Kompatibilität mit den Bedingungen, die Nutzer an `Auth::attempt` übergeben haben.
* Unterscheiden Sie Speicherfehler von Authentifizierungsfehlern und legen Sie fest, dass Benutzer auf dem Login-Bildschirm nicht fälschlich zur erneuten Passworteingabe aufgefordert werden.
* Prüfen Sie vor dem Entfernen des Provider-Namens, der Konfigurationsschlüssel in `auth.php` oder der Verbindungseinstellungen den Konfigurations-Cache und Ihre Deployment-Schritte.

Behandeln Sie "aus welchem Speicher was als Benutzer zurückgegeben wird" und "mit welchem Hash Passwörter verwaltet werden" als öffentlichen Vertrag Ihres Pakets, und überlassen Sie den Umgang mit Anmeldedaten nicht vollständig der Anwendung.

## Verwandte Seiten

> [card] [Eigene Auth-Guards implementieren](https://kawax.biz/de/advanced/custom-auth-guard.md)
>
> Erfahren Sie, wie Sie den Guard selbst erweitern und Benutzer aus Sessions oder API-Tokens auflösen.

> [card] [Service-Provider](https://kawax.biz/de/service-providers.md)
>
> Lernen Sie die Grundlagen, um den Service-Provider Ihres Pakets zu registrieren und Erweiterungen beim Booten anzuwenden.

## Verwendete Primärquellen

* [Offizielle Laravel-Dokumentation: Adding Custom User Providers](https://github.com/laravel/docs/blob/13.x/authentication.md#adding-custom-user-providers)
* [Offizielle Laravel-Dokumentation: User Provider Contract](https://github.com/laravel/docs/blob/13.x/authentication.md#the-user-provider-contract)
* [AuthManager: provider() und Guard-Auflösung](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/AuthManager.php)
* [CreatesUserProviders: Erzeugung eigener Provider](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: Standardimplementierung](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/EloquentUserProvider.php)
* [GenericUser: Authenticatable aus Attributen](https://github.com/laravel/framework/blob/v13.43.0/src/Illuminate/Auth/GenericUser.php)


## Related topics

- [Weiterführende Themen](https://kawax.biz/de/advanced/index.md)
- [Eigene Auth-Guards implementieren](https://kawax.biz/de/advanced/custom-auth-guard.md)
- [Upgrade von Laravel 10 auf 11](https://kawax.biz/de/blog/upgrade-10-to-11.md)
- [Eigene Session-Treiber in Paketen](https://kawax.biz/de/advanced/package-session-drivers.md)
- [Eigene Cache-Stores und Verträge in Paketen](https://kawax.biz/de/advanced/package-cache-drivers.md)


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