Zum Inhalt springen
Aurabase-Logo
Aurabasis

Authentifizieren Sie Benutzer mit dem JavaScript SDK

Die alltäglichen Abläufe von aura.auth, wobei das Verhalten jedes Aufrufs anhand eines laufenden Stapels beobachtet wird.

Anleitung11 Min. gelesenEbene MittelstufeÜberarbeitet am 12.10.2026

Diese Seite wurde automatisch übersetzt. Maßgeblich ist die englische Version.

Registrieren Sie sich und melden Sie sich an#

auth.tstypescript
import { createClient, isMfaChallenge } from '@aurabase/aurabase-js'

const aura = createClient(process.env.NEXT_PUBLIC_AURABASE_URL!, process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!)

// Erstellen Sie ein Konto
const { data, error } = await aura.auth.signUp({ email: 'ada@example.com', password: 'a-long-passphrase' })

// Melden Sie sich an
const login = await aura.auth.signInWithPassword({ email: 'ada@example.com', password: 'a-long-passphrase' })
if (login.error) return showError(login.error.message)
if (login.data && isMfaChallenge(login.data)) return askForTotpCode(login.data.mfa_token)
// andernfalls existiert jetzt eine Sitzung

Beide Aufrufe geben die gleiche Form zurück. Bei Erfolg hält data access_token, refresh_token, expires_in (900 Sekunden) und user und der Client speichert die Sitzung für Sie. Die nächste Anfrage ist bereits authentifiziert.

Was signUp tut, hängt von Ihren Projekteinstellungen ab. In unserem Testprojekt hat es den Benutzer sofort mit email_verified: false angemeldet, und ein Projekt kann zuerst eine Bestätigung erfordern.

Folgende Fehler sollten Sie beheben:

Rufen Sie anFehler
Falsches Passwort401, code: 'INVALID_CREDENTIALS', „Ungültige E-Mail-Adresse oder ungültiges Passwort.“
Ungültiger oder abgelaufener Link oder Code401, code: 'INVALID_OTP'
Anonyme Anmeldung, wenn das Projekt dies nicht zulässt403, FORBIDDEN

signInAnonymously() erstellt einen Benutzer ohne E-Mail-Adresse, aber in einem neuen Projekt ist es deaktiviert und gibt 403 zurück, bis Sie es in den Authentifizierungseinstellungen des Projekts aktivieren. Ein anonymer Benutzer hat die Rolle authenticated (er besitzt seine Zeilen: auth.uid() ist festgelegt); Unterscheiden Sie es in Ihren Policen von einem dauerhaften Konto mit auth.is_anonymous(), beispielsweise einer restriktiven Police using (not auth.is_anonymous()).

Die Sitzung und ihre Ereignisse#

session.tstypescript
const { data: { session } } = await aura.auth.getSession() // kein Netzwerkaufruf: liest den Speicher
const { data: user } = await aura.auth.getUser()           // fragt der Server

const { data: { subscription } } = aura.auth.onAuthStateChange(({ event, user }) => {
  // Ereignis: 'INITIAL_SESSION' | 'SIGNED_IN' | 'TOKEN_REFRESHED' | 'USER_UPDATED' | 'SIGNED_OUT' | „MFA_CHALLENGE“
})
subscription.unsubscribe()

Ein echter Lauf erzeugte diese Sequenz: INITIAL_SESSION, SIGNED_IN (Anmeldung), SIGNED_IN (Anmeldung), USER_UPDATED, TOKEN_REFRESHED, SIGNED_OUT.

  • Der Client aktualisiert das Zugriffstoken, bevor es abläuft. Rufen Sie aura.auth.refreshSession() auf, um dies zu erzwingen.
  • getSession() ist lokal und schnell: Verwenden Sie es zum Rendern. Verwenden Sie getUser(), wenn Sie die aktuelle Sicht des Servers auf den Benutzer benötigen.
  • Um eine Sitzung von einem anderen Ort (einem Cookie, einem Server) an den Client zu übergeben, verwenden Sie setSession(accessToken, refreshToken). Ein ungültiges Paar wird abgelehnt und die vorherige Sitzung wird beibehalten.
  • Informationen zum serverseitigen Rendering finden Sie unter Next.js App Router und SSR.

Profil und Passwort#

profile.tstypescript
// Metadaten: Übergeben Sie sie in „Daten“.
await aura.auth.updateUser({ data: { theme: 'dark', plan: 'free' } })
// → user.user_metadata ist { plan: 'free', theme: 'dark' } und getUser() gibt dasselbe zurück

// E-Mail ändern: Die Adresse ändert sich noch NICHT
await aura.auth.updateUser({ email: 'new@example.com' })
// Ein Bestätigungslink führt zur neuen Adresse. Bis zur Verwendung behält user.email den alten Wert.
// Bestätigen Sie mit: aura.auth.verifyOtp({ type: 'email_change', token })

// Ändern Sie das Passwort
await aura.auth.updatePassword('a-new-long-passphrase', 'a-long-passphrase')
Wenn Sie das Passwort ändern, werden Sie abgemeldet

Der Server widerruft alle Sitzungen, wenn sich das Passwort ändert. updatePassword löscht die lokale Sitzung und gibt SIGNED_OUT aus: Melden Sie sich erneut mit dem neuen Passwort an. Im realen Durchlauf war getSession() direkt nach dem Aufruf leer und die Anmeldung mit dem neuen Passwort funktionierte.

Passwort vergessen: aura.auth.resetPasswordForEmail({ email }) sendet die Reset-E-Mail. Der Benutzer schließt es dann mit verifyOtp({ type: 'recovery', token, password }) ab.

Konto löschen: aura.auth.deleteUser(password) fragt nach dem aktuellen Passwort, löscht das Konto und löscht die lokale Sitzung.

Links, Codes und OAuth#

passwordless.tstypescript
// Magischer Link per E-Mail
await aura.auth.signInWithMagicLink({ email })
// → eine allgemeine Bestätigungsnachricht
// Die Antwort ist dieselbe, unabhängig davon, ob das Konto existiert oder nicht: Es werden keine Konten preisgegeben.

// Einmalige Codes
await aura.auth.signInWithEmailOtp(email)
await aura.auth.signInWithSmsOtp(phone)
await aura.auth.verifyOtp({ type: 'email', email, code })     // auch: 'sms', 'magiclink', 'signup', 'recovery', 'email_change'

// OAuth: kanonische Signatur oder Supabase-kompatible Objektform
const { data } = await aura.auth.signInWithOAuth('google', { redirectTo: 'https://app.example.com/callback' })
// oder:wait aura.auth.signInWithOAuth({provider:'google',options:{redirectTo:'...'}})
if (data?.url) window.location.href = data.url

signInWithOAuth gibt die zu öffnende URL zurück; es navigiert nicht von selbst. Der Provider muss im Projekt aktiviert und konfiguriert sein, ansonsten antwortet die Start-URL mit PROVIDER_NOT_CONFIGURED.

Flexible OAuth-Signaturen

signInWithOAuth akzeptiert entweder signInWithOAuth('google', { redirectTo }) oder die Objektform signInWithOAuth({ provider: 'google', options: { redirectTo } }). Beide Syntaxen sind vollständig typisiert und werden unterstützt.

Nach der Rückumleitung liest der Client die Sitzung selbst aus der URL (detectSessionInUrl). Übergeben Sie für den PKCE-Fluss flowType: 'pkce', behalten Sie den standardmäßigen persistenten Speicher bei und der Client tauscht den Code für Sie aus.

Verknüpfen Sie einen zweiten Anbieter mit einem angemeldeten Konto mit linkIdentity(provider), listen Sie ihn mit listIdentities() auf und entfernen Sie einen mit unlinkIdentity(identityId).

Multi-Faktor-Authentifizierung#

mfa.tstypescript
// 1. Anmeldung: über den Namespace aura.auth.mfa oder die Flat-Methode
const { data: enrol } = await aura.auth.mfa.enroll()   // → { geheim, otpauth_url }
// 2. Bestätigen Sie mit dem ersten Code der Authentifizierungs-App: Sie erhalten Wiederherstellungscodes
const { data: confirm } = await aura.auth.mfa.verifySetup(codeFromApp) // → { Recovery_codes: [...] }

// 3. Von nun an gibt die Anmeldung eine Herausforderung statt einer Sitzung zurück
const login = await aura.auth.signInWithPassword({ email, password })
if (login.data && isMfaChallenge(login.data)) {
  await aura.auth.mfa.verify({ mfa_token: login.data.mfa_token, code: codeFromApp })
}

mfa.unenroll(password) (oder mfaUnenroll) schaltet es aus und mfa.regenerateRecoveryCodes(code) gibt neue Wiederherstellungscodes aus. Eine Herausforderung gibt MFA_CHALLENGE aus und es wird keine Sitzung gespeichert, bis mfaVerify erfolgreich ist.

Geräte und Sitzungen#

devices.tstypescript
const { data } = await aura.auth.listSessions()
// [{id, Geräteinfo, IP-Adresse, erstelltes_AT, Ablaufdatum, letztes_verwendetes_AT, is_current}, …]

await aura.auth.revokeSession(sessionId)   // Melden Sie ein Gerät ab
await aura.auth.revokeAllSessions()        // Melde dich überall ab, auch hier
await aura.auth.signOut()                  // Nur dieses Gerät

is_current markiert die von Ihnen verwendete Sitzung. signOut widerruft das Aktualisierungstoken auf dem Server, wenn eines vorhanden ist, löscht die lokale Sitzung und gibt SIGNED_OUT aus.

Benutzer verwalten#

Für die Benutzerverwaltung ist ein service_role-Schlüssel erforderlich. Es ist nur auf dem Server verfügbar: Das Lesen von aura.authAdmin in einem Browser führt zu einem Fehler.

server/users.tstypescript
import { createAdminClient } from '@aurabase/aurabase-js'

const admin = createAdminClient(process.env.NEXT_PUBLIC_AURABASE_URL!, process.env.AURABASE_SERVICE_ROLE_KEY!)

const { data: users } = await admin.authAdmin.listUsers({ limit: 20, search: 'ada' })
const { data: created } = await admin.authAdmin.createUser({ email: 'bob@example.com', password: 'a-long-passphrase', email_verified: true })
await admin.authAdmin.banUser(created!.id)
await admin.authAdmin.unbanUser(created!.id)
const { data: link } = await admin.authAdmin.generateLink(created!.id, 'magic') // → { Link, Token }
await admin.authAdmin.deleteUser(created!.id)

const { data: stats } = await admin.authAdmin.getUserStats() // → { total, verifiziert, gesperrt, mfa_enabled, new_7d }

generateLink akzeptiert 'magic', 'recovery' oder 'invite'. Der Admin-Client verwaltet außerdem die Authentifizierungseinstellungen des Projekts (getSettings, updateSettings), E-Mail-Vorlagen, Sitzungen aller Benutzer und das Prüfprotokoll (getAuditLog). Jede Methode ist in der Authentifizierungsreferenz auth reference aufgeführt.