Du startest ein neues Projekt mit PocketBase, legst die ersten Collections an, und dann kommt die Frage: Wie bauen wir den Login? Viele greifen an dieser Stelle zu eigenen Hooks, selbst geschriebenen Token-Tabellen oder einem externen Auth-Dienst. Das ist meistens unnötig. PocketBase bringt mit der Auth-Collection users bereits alles mit, was eine typische App braucht: Passwort-Login, OAuth2 mit Anbietern wie Google und GitHub, Einmalpasswörter (OTP), Multi-Faktor-Authentifizierung (MFA), E-Mail-Verifizierung und Passwort-Reset.
In diesem Beitrag gehen wir die eingebauten Authentication Methods der Reihe nach durch. Du erfährst, wo du sie aktivierst, wie du sie mit dem JavaScript SDK ansprichst und an welchen Stellen du wirklich noch selbst etwas tun musst.
Die Auth-Collection users: Dein fertiges Benutzersystem
PocketBase kennt drei Arten von Collections: Base, View und Auth. Eine Auth-Collection ist eine normale Collection mit zusätzlichen Systemfeldern wie email, emailVisibility, verified, password und tokenKey sowie eigenen API-Endpunkten für Anmeldung, Verifizierung und Passwort-Reset. Bei einer frischen Installation legt PocketBase automatisch die Collection users an. Du kannst sie um eigene Felder erweitern, etwa name, avatar oder eine Rolle.
Seit Version 0.23 findest du alle Optionen im Admin-Dashboard direkt in den Einstellungen der Collection unter dem Reiter Options. Dort schaltest du jede Methode einzeln an oder aus. Die Admins der Oberfläche leben übrigens getrennt davon in der System-Collection _superusers, deine App-Nutzer kommen also nie mit dem Dashboard in Berührung.
Eine Voraussetzung gilt für fast alle Methoden: PocketBase muss E-Mails verschicken können. Trage deshalb unter Settings > Mail settings deinen SMTP-Server ein und setze unter Application URL die richtige Adresse deiner App. Ohne SMTP landen OTP-Codes, Verifizierungs- und Reset-Links nirgends.
Passwort-Login: der Klassiker
Der Passwort-Login ist standardmäßig aktiv. In den Optionen legst du fest, welche Felder als Identität zählen. Üblich ist email, du kannst aber auch username oder jedes andere eindeutige Feld mit Unique-Index zulassen. Das Passwort speichert PocketBase gehasht mit bcrypt, darum musst du dich nicht kümmern.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
import PocketBase from 'pocketbase'; const pb = new PocketBase('https://deine-app.de'); // Registrierung await pb.collection('users').create({ email: 'anna@example.com', password: 'geheimesPasswort123', passwordConfirm: 'geheimesPasswort123', name: 'Anna' }); // Login const authData = await pb.collection('users').authWithPassword( 'anna@example.com', 'geheimesPasswort123' ); console.log(pb.authStore.isValid); // true console.log(pb.authStore.record.id); |
Das SDK speichert Token und Benutzerdaten automatisch im authStore und hängt den Token an jede weitere Anfrage. Mit pb.collection('users').authRefresh() verlängerst du eine Sitzung, mit pb.authStore.clear() meldest du den Nutzer ab. Eine eigene Session-Tabelle brauchst du also nicht.
Damit sich überhaupt jemand registrieren darf, muss die Create rule der Collection offen sein. Lässt du sie leer, ist die Registrierung öffentlich. Setzt du sie auf null (gesperrt), können nur Superuser neue Nutzer anlegen.
OAuth2 mit Google und GitHub
Social Login ist der Bereich, in dem am häufigsten unnötig selbst gebaut wird. PocketBase unterstützt über 20 OAuth2-Anbieter, darunter Google, GitHub, Apple, Microsoft, Discord und GitLab. Die Einrichtung läuft in drei Schritten:
- Lege beim Anbieter eine OAuth-App an (Google Cloud Console oder GitHub Developer Settings).
- Trage dort als Redirect URL
https://deine-app.de/api/oauth2-redirectein. - Aktiviere in PocketBase unter Options > OAuth2 den Anbieter und hinterlege Client ID und Client Secret.
Im Frontend reicht dann ein einziger Aufruf:
|
1 2 3 4 5 6 7 |
// Öffnet ein Popup, PocketBase erledigt den Rest const authData = await pb.collection('users').authWithOAuth2({ provider: 'google' // oder 'github' }); // Infos vom Anbieter, z. B. Name oder Avatar-URL console.log(authData.meta); |
Das SDK öffnet ein Popup, wartet über eine Realtime-Verbindung auf das Ergebnis und schließt das Fenster wieder. Meldet sich jemand zum ersten Mal an, legt PocketBase automatisch einen neuen Datensatz in users an. Existiert die E-Mail-Adresse bereits, wird das externe Konto mit dem vorhandenen Nutzer verknüpft. Die Verknüpfungen landen in der System-Collection _externalAuths. Über das Fields mapping in den OAuth2-Optionen kannst du außerdem festlegen, dass Name oder Avatar vom Anbieter direkt in deine eigenen Felder übernommen werden.
Tipp: Mit pb.collection('users').listAuthMethods() fragst du ab, welche Methoden und Anbieter gerade aktiv sind. So kannst du die Login-Buttons dynamisch rendern, statt sie fest einzubauen.
OTP: Login per Einmalcode
Mit OTP (One-Time Password) meldet sich ein Nutzer ohne Passwort an. PocketBase schickt einen Code per E-Mail, der Nutzer gibt ihn ein, fertig. Das eignet sich gut für Apps, in denen du gar keine Passwörter verwalten möchtest. Du aktivierst OTP unter Options > One-time password (OTP) und legst dort Gültigkeitsdauer und Länge des Codes fest. Standardmäßig ist der Code 8 Zeichen lang und 3 Minuten gültig.
|
1 2 3 4 5 6 7 8 |
// Schritt 1: Code anfordern const result = await pb.collection('users').requestOTP('anna@example.com'); // Schritt 2: Code aus der E-Mail eingeben lassen const authData = await pb.collection('users').authWithOTP( result.otpId, '12345678' ); |
Gut zu wissen: requestOTP liefert auch dann eine otpId zurück, wenn es die E-Mail-Adresse gar nicht gibt. So verrät die API nicht, welche Adressen registriert sind. Ein erfolgreicher OTP-Login setzt außerdem automatisch verified auf true, denn der Nutzer hat ja bewiesen, dass er Zugriff auf das Postfach hat.
MFA: Zwei Faktoren ohne eigene Logik
Multi-Faktor-Authentifizierung klingt nach viel Arbeit, ist in PocketBase aber nur ein Schalter. Unter Options > Multi-factor authentication (MFA) aktivierst du die Funktion. Danach muss sich jeder Nutzer mit zwei verschiedenen Methoden anmelden, zum Beispiel erst mit Passwort und dann mit einem OTP-Code. Optional kannst du eine Regel hinterlegen, damit MFA nur für bestimmte Nutzer gilt, etwa für Konten mit einer Admin-Rolle.
Im Code fängst du den ersten Fehler ab, liest die mfaId aus und gibst sie beim zweiten Login mit:
|
1 2 3 4 5 6 7 8 9 10 11 |
try { await pb.collection('users').authWithPassword('anna@example.com', 'geheimesPasswort123'); } catch (err) { const mfaId = err.response?.mfaId; if (!mfaId) throw err; // ein anderer Fehler, z. B. falsches Passwort const result = await pb.collection('users').requestOTP('anna@example.com'); // Code aus der E-Mail abfragen und mit der mfaId bestätigen await pb.collection('users').authWithOTP(result.otpId, '12345678', { mfaId }); } |
Wichtig: Für MFA müssen mindestens zwei Methoden aktiv sein, also zum Beispiel Passwort und OTP oder OAuth2 und OTP. Ein eigenes TOTP-System mit Authenticator-App bringt PocketBase derzeit nicht mit. Wenn du das unbedingt brauchst, ist das einer der wenigen Fälle, in denen sich eine eigene Erweiterung lohnt.
E-Mail-Verifizierung
Jeder Datensatz in einer Auth-Collection hat das Systemfeld verified. Es steht nach der Registrierung auf false. Um die Adresse zu bestätigen, forderst du eine Verifizierungs-Mail an und bestätigst anschließend den Token aus dem Link:
|
1 2 3 4 5 |
// Mail mit Bestätigungslink verschicken await pb.collection('users').requestVerification('anna@example.com'); // Auf deiner Bestätigungsseite: Token aus der URL lesen await pb.collection('users').confirmVerification(token); |
Der Inhalt der E-Mail und die Zieladresse des Links lassen sich unter Options > Mail templates anpassen. Dort kannst du den Link zum Beispiel auf eine eigene Seite in deinem Frontend umleiten.
Die eigentliche Stärke liegt in den API Rules. Mit einer Regel wie @request.auth.verified = true erlaubst du bestimmte Aktionen nur bestätigten Nutzern. Willst du den Login komplett sperren, bis die Adresse bestätigt ist, setzt du in den Optionen die Auth rule auf verified = true. Dafür brauchst du keinen einzigen Hook.
Passwort-Reset
Auch das “Passwort vergessen”-Feature ist bereits fertig. Der Ablauf entspricht der Verifizierung: Mail anfordern, Token bestätigen, neues Passwort setzen.
|
1 2 3 4 5 6 7 8 9 |
// Reset-Mail anfordern await pb.collection('users').requestPasswordReset('anna@example.com'); // Auf deiner Reset-Seite await pb.collection('users').confirmPasswordReset( token, 'neuesPasswort456', 'neuesPasswort456' ); |
Wenn du keine eigene Seite bauen willst, verweist der Standardlink auf eine schlichte Seite, die PocketBase selbst ausliefert. Nach einem erfolgreichen Reset werden bestehende Tokens des Nutzers ungültig, weil sich der tokenKey ändert. Auf allen Geräten muss man sich also neu anmelden. Genauso funktioniert übrigens der Wechsel der E-Mail-Adresse mit requestEmailChange() und confirmEmailChange().
Auf welcher Seite landet ein User nach dem Login?
Diese Frage taucht fast in jedem Projekt auf, und die Antwort überrascht viele: PocketBase leitet nach dem Login nirgendwohin weiter. PocketBase ist ein Backend. Die Auth-Endpunkte antworten mit JSON, das den Token und den Datensatz des Nutzers enthält. Das SDK legt beides im authStore ab, und der Nutzer bleibt erst einmal genau auf der Seite, auf der er das Login-Formular abgeschickt hat. Wohin es danach geht, entscheidet allein dein Frontend.
Eine Einstellung wie “Redirect after login” suchst du im Dashboard deshalb vergeblich. Du baust die Weiterleitung selbst, und das sind nur wenige Zeilen:
|
1 2 3 4 5 6 7 8 9 |
async function login(email, password) { await pb.collection('users').authWithPassword(email, password); // Zurück zur ursprünglich aufgerufenen Seite, sonst zum Dashboard const target = new URLSearchParams(location.search).get('redirect'); const isInternal = target && target.startsWith('/') && !target.startsWith('//'); window.location.href = isInternal ? target : '/dashboard'; } |
Die Prüfung auf einen internen Pfad ist wichtig. Ohne sie könnte jemand einen Link wie /login?redirect=https://boese-seite.de verschicken und deine Nutzer nach dem Login auf eine fremde Seite lotsen (Open Redirect). Den Parameter redirect setzt du auf geschützten Seiten, wenn kein gültiger Login vorliegt:
|
1 2 3 4 |
// Auf jeder geschützten Seite if (!pb.authStore.isValid) { window.location.href = '/login?redirect=' + encodeURIComponent(location.pathname); } |
Beachte, dass isValid nur lokal prüft, ob ein Token vorhanden und noch nicht abgelaufen ist. Ob das Konto noch existiert, erfährst du erst mit authRefresh(). Die eigentliche Absicherung deiner Daten übernehmen ohnehin die API Rules auf dem Server, die Weiterleitung ist nur Komfort für den Nutzer.
Bei den anderen Methoden gilt dasselbe Prinzip, mit kleinen Besonderheiten:
- OAuth2: Die Redirect URL
/api/oauth2-redirectist kein Ziel für deine Nutzer, sondern ein interner Endpunkt von PocketBase. Er nimmt die Antwort von Google oder GitHub im Popup entgegen, danach schließt sich das Popup. Deine Seite bleibt die ganze Zeit offen,authWithOAuth2()liefert das Ergebnis zurück und du leitest wie oben weiter. - OTP und MFA: Auch hier bleibt der Nutzer auf deiner Seite, bis
authWithOTP()erfolgreich war. Erst dann navigierst du weiter. - Links aus E-Mails: Verifizierungs- und Reset-Links führen standardmäßig auf schlichte Seiten, die PocketBase selbst ausliefert. Wenn deine Nutzer stattdessen auf einer Seite deiner App landen sollen, passt du die Zieladresse unter Options > Mail templates an und rufst dort
confirmVerification()oderconfirmPasswordReset()auf.
Was du dir sparen kannst
Bevor du eigene Auth-Logik schreibst, prüfe diese Liste. All das erledigt PocketBase schon für dich:
- Passwort-Hashing mit bcrypt und Mindestlänge
- Token-Verwaltung inklusive Refresh und Invalidierung
- Social Login mit automatischem Anlegen und Verknüpfen von Konten
- Passwortloser Login per OTP
- Zwei-Faktor-Login per MFA-Schalter
- Bestätigungs- und Reset-Mails mit anpassbaren Vorlagen
- Rate Limiting für Auth-Endpunkte unter Settings > Application
- Login-Benachrichtigung bei Anmeldung von einem neuen Gerät (Auth alert)
Eigener Code lohnt sich erst, wenn du wirklich etwas brauchst, das darüber hinausgeht, zum Beispiel TOTP per Authenticator-App, Login per SMS oder Single Sign-On mit einem Anbieter, der kein OAuth2 spricht. Für solche Fälle gibt es JavaScript- und Go-Hooks.
Fazit
Die Auth-Collection users ist eines der stärksten Features von PocketBase und wird trotzdem oft unterschätzt. Passwort-Login, OAuth2 mit Google und GitHub, OTP, MFA, E-Mail-Verifizierung und Passwort-Reset sind eingebaut, getestet und mit wenigen Klicks aktiviert. Statt Zeit in eigene Token-Tabellen oder Reset-Flows zu stecken, konfigurierst du die Optionen, richtest SMTP ein und schreibst ein paar Zeilen SDK-Code. Die gesparte Zeit steckst du besser in die Features, die deine App wirklich besonders machen.
Alle Details und Beispiele für weitere SDKs findest du in der offiziellen PocketBase-Dokumentation zur Authentifizierung.
FAQ
Nein. Passwort-Login, OAuth2, OTP, MFA, E-Mail-Verifizierung und Passwort-Reset sind in jeder Auth-Collection eingebaut. Hooks brauchst du nur für Sonderfälle wie SMS-Login oder TOTP. Nirgendwohin. Die Auth-API antwortet nur mit Token und Nutzerdaten. Auf welche Seite der Nutzer danach kommt, legst du in deinem Frontend fest, zum Beispiel mit Über 20 Anbieter, darunter Google, GitHub, Apple, Microsoft, Discord, GitLab und Facebook. Zusätzlich gibt es einen generischen OIDC-Anbieter für eigene Identity Provider. Meistens fehlt die SMTP-Konfiguration. Trage unter Settings > Mail settings deinen Mailserver ein und schicke über das Dashboard eine Test-Mail, um die Verbindung zu prüfen. Ja. Setze in den Optionen der Collection die Auth rule auf Nicht direkt. Die eingebaute MFA kombiniert zwei vorhandene Methoden, zum Beispiel Passwort und OTP per E-Mail. TOTP mit einer Authenticator-App müsstest du selbst ergänzen. Ja. Du kannst neben
Brauche ich für den Login in PocketBase eigene Hooks?
Wohin leitet PocketBase einen Nutzer nach dem Login weiter?
window.location.href oder dem Router deines Frameworks.Welche OAuth2-Anbieter unterstützt PocketBase?
Warum kommen keine E-Mails für OTP oder Passwort-Reset an?
Kann ich den Login für nicht verifizierte Nutzer sperren?
verified = true. Dann können sich nur Nutzer mit bestätigter E-Mail-Adresse anmelden.Unterstützt PocketBase MFA mit einer Authenticator-App?
Kann ich mehrere Auth-Collections anlegen?
users weitere Auth-Collections erstellen, etwa für Kunden und Mitarbeiter, jeweils mit eigenen Methoden, Regeln und Mail-Vorlagen.
