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.
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 vonAuth::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.
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.
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.
- Der Guard
directory-webreferenziert den Providerdirectory-users. - Der
drivervondirectory-usersistdirectory, daher wird der obige Callback gewählt. - Ein
SessionGuardwird erzeugt und ruft Benutzer über den erzeugtenUserProviderab.
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.
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.
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.
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.
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.
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 implementiertrehashPasswordIfRequired und aktualisiert den Hash im Speicher nur bei Bedarf.
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 desUserProvider 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.
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.
- Den Service-Provider des Pakets laden.
- Den eigenen
driverinauth.providerssetzen. - Diesen Provider aus
auth.guardsreferenzieren. - Den Guard zum ersten Mal auflösen und bestätigen, dass der Benutzerabruf an den Fake-Client delegiert wird.
- In Tests, die Konfiguration oder Registrierung ändern, vor dem nächsten Fall
Auth::forgetGuards()aufrufen.
Kompatibilität bei Updates einplanen
EinUserProvider 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
retrieveByCredentialseinschränken, prüfen Sie die Kompatibilität mit den Bedingungen, die Nutzer anAuth::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.phpoder der Verbindungseinstellungen den Konfigurations-Cache und Ihre Deployment-Schritte.
Verwandte Seiten
Eigene Auth-Guards implementieren
Erfahren Sie, wie Sie den Guard selbst erweitern und Benutzer aus Sessions oder API-Tokens auflösen.
Service-Provider
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
- Offizielle Laravel-Dokumentation: User Provider Contract
- AuthManager: provider() und Guard-Auflösung
- CreatesUserProviders: Erzeugung eigener Provider
- UserProvider contract
- Authenticatable contract
- EloquentUserProvider: Standardimplementierung
- GenericUser: Authenticatable aus Attributen