Przejdź do treści
Logo Aurabase
aurabaza

Uwierzytelniaj użytkowników za pomocą pakietu JavaScript SDK

Codzienne przepływy aura.auth z zachowaniem każdego wywołania obserwowanym na działającym stosie.

Przewodnik krok po kroku11 min przeczytanePoziom mediatorZmieniono 12 paź 2026

Ta strona została przetłumaczona automatycznie. Wersja angielska jest miarodajna.

Zarejestruj się i zaloguj#

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!)

// Utwórz konto
const { data, error } = await aura.auth.signUp({ email: 'ada@example.com', password: 'a-long-passphrase' })

// Zalogować się
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)
// w przeciwnym razie sesja już istnieje

Obydwa wywołania zwracają ten sam kształt. W przypadku powodzenia data wstrzymuje access_token, refresh_token, expires_in (900 sekund) i user, a klient przechowuje sesję dla Ciebie. Następne żądanie zostało już uwierzytelnione.

Działanie signUp zależy od ustawień projektu. W naszym projekcie testowym użytkownik zalogował się natychmiast za pomocą email_verified: false, a projekt może wymagać najpierw potwierdzenia.

Awarie, z którymi należy sobie poradzić, zgodnie z obserwacjami:

DzwonićBłąd
Błędne hasło401, code: 'INVALID_CREDENTIALS', „Nieprawidłowy adres e-mail lub hasło.”
Nieprawidłowy lub wygasły link lub kod401, code: 'INVALID_OTP'
Logowanie anonimowe, gdy projekt na to nie pozwala403, FORBIDDEN

signInAnonymously() tworzy użytkownika bez adresu e-mail, ale w nowym projekcie jest wyłączony i zwraca 403 do czasu włączenia go w ustawieniach autoryzacji projektu. Użytkownik anonimowy ma rolę authenticated (jest właścicielem swoich wierszy: ustawiono auth.uid()); rozróżnij to od stałego konta w swoich polisach z auth.is_anonymous(), na przykład restrykcyjnej polityki using (not auth.is_anonymous()).

Sesja i jej wydarzenia#

session.tstypescript
const { data: { session } } = await aura.auth.getSession() // brak połączenia sieciowego: czyta sklep
const { data: user } = await aura.auth.getUser()           // pyta serwer

const { data: { subscription } } = aura.auth.onAuthStateChange(({ event, user }) => {
  // wydarzenie: 'INITIAL_SESSION' | „ZAPISANE_IN” | „TOKEN_REFRESHED” | „USER_AKTUALIZACJA” | „ZAPISANA_WYŁĄCZONA” | „MFA_CHALLENGE”
})
subscription.unsubscribe()

Prawdziwy przebieg dał następującą sekwencję: INITIAL_SESSION, SIGNED_IN (rejestracja), SIGNED_IN (logowanie), USER_UPDATED, TOKEN_REFRESHED, SIGNED_OUT.

  • Klient odświeża token dostępu przed jego wygaśnięciem. Zadzwoń do aura.auth.refreshSession(), aby to wymusić.
  • getSession() jest lokalny i szybki: użyj go do renderowania. Użyj getUser(), jeśli potrzebujesz bieżącego widoku użytkownika z serwera.
  • Aby przekazać sesję klientowi z innego miejsca (plik cookie, serwer), użyj setSession(accessToken, refreshToken). Nieprawidłowa para zostaje odrzucona, a poprzednia sesja zostaje zachowana.
  • W przypadku renderowania po stronie serwera zobacz Next.js App Router i SSR.

Profil i hasło#

profile.tstypescript
// Metadane: przekaż je w `data`
await aura.auth.updateUser({ data: { theme: 'dark', plan: 'free' } })
// → user.user_metadata to { plan: 'bezpłatny', temat: 'ciemny' }, a getUser() zwraca to samo

// Zmień e-mail: adres jeszcze się NIE zmienia
await aura.auth.updateUser({ email: 'new@example.com' })
// Link potwierdzający prowadzi do nowego adresu. Do czasu użycia user.email zachowuje starą wartość.
// Potwierdź za pomocą: aura.auth.verifyOtp({ type: 'email_change', token })

// Zmień hasło
await aura.auth.updatePassword('a-new-long-passphrase', 'a-long-passphrase')
Zmiana hasła powoduje wylogowanie

Serwer odwołuje wszystkie sesje po zmianie hasła. updatePassword czyści sesję lokalną i emituje SIGNED_OUT: zaloguj się ponownie, używając nowego hasła. W rzeczywistości getSession() był pusty zaraz po połączeniu, a logowanie się przy użyciu nowego hasła zadziałało.

Zapomniałem hasła: aura.auth.resetPasswordForEmail({ email }) wysyła e-mail z resetem. Następnie użytkownik uzupełnia go za pomocą verifyOtp({ type: 'recovery', token, password }).

Usuń konto: aura.auth.deleteUser(password) pyta o aktualne hasło, usuwa konto i czyści sesję lokalną.

Linki, kody i OAuth#

passwordless.tstypescript
// Magiczny link e-mailem
await aura.auth.signInWithMagicLink({ email })
// → ogólny komunikat potwierdzający
// Odpowiedź jest taka sama, niezależnie od tego, czy konto istnieje: nie powoduje wycieku kont.

// Kody jednorazowe
await aura.auth.signInWithEmailOtp(email)
await aura.auth.signInWithSmsOtp(phone)
await aura.auth.verifyOtp({ type: 'email', email, code })     // także: „sms”, „magiclink”, „rejestracja”, „odzyskiwanie”, „email_change”

// OAuth: podpis kanoniczny lub kształt obiektu zgodny z Supabase
const { data } = await aura.auth.signInWithOAuth('google', { redirectTo: 'https://app.example.com/callback' })
// lub: czekaj na aura.auth.signInWithOAuth({ dostawca: 'google', opcje: { redirectTo: '...' } })
if (data?.url) window.location.href = data.url

signInWithOAuth zwraca adres URL do otwarcia; nie nawiguje samodzielnie. Dostawca musi być włączony i skonfigurowany w projekcie, w przeciwnym razie początkowy adres URL będzie odpowiadał PROVIDER_NOT_CONFIGURED.

Elastyczne podpisy OAuth

signInWithOAuth akceptuje signInWithOAuth('google', { redirectTo }) lub kształt obiektu signInWithOAuth({ provider: 'google', options: { redirectTo } }). Obie składnie są w pełni wpisane i obsługiwane.

Po przekierowaniu zwrotnym klient samodzielnie odczytuje sesję z adresu URL (detectSessionInUrl). W przypadku przepływu PKCE przekaż flowType: 'pkce', zachowaj domyślny magazyn trwały, a klient wymieni kod za Ciebie.

Połącz drugiego dostawcę z zalogowanym kontem za pomocą linkIdentity(provider), wymień go za pomocą listIdentities() i usuń jednego za pomocą unlinkIdentity(identityId).

Uwierzytelnianie wieloskładnikowe#

mfa.tstypescript
// 1. Zarejestruj się: poprzez przestrzeń nazw aura.auth.mfa lub metodą płaską
const { data: enrol } = await aura.auth.mfa.enroll()   // → { sekret, otpauth_url }
// 2. Potwierdź pierwszym kodem z aplikacji uwierzytelniającej: otrzymasz kody odzyskiwania
const { data: confirm } = await aura.auth.mfa.verifySetup(codeFromApp) // → {kody_odzyskiwania: [...] }

// 3. Od tej chwili logowanie zwraca wyzwanie zamiast sesji
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) (lub mfaUnenroll) wyłącza to, a mfa.regenerateRecoveryCodes(code) wystawia nowe kody odzyskiwania. Wyzwanie emituje MFA_CHALLENGE i żadna sesja nie jest przechowywana, dopóki mfaVerify się nie powiedzie.

Urządzenia i sesje#

devices.tstypescript
const { data } = await aura.auth.listSessions()
// [{ id, informacje o urządzeniu, adres_ip, utworzony_at, wygasa_at, last_used_at, is_current }, …]

await aura.auth.revokeSession(sessionId)   // wyloguj się z jednego urządzenia
await aura.auth.revokeAllSessions()        // wylogowuj się wszędzie, łącznie z tym
await aura.auth.signOut()                  // tylko to urządzenie

is_current oznacza sesję, której używasz. signOut odwołuje token odświeżania na serwerze, jeśli taki istnieje, czyści sesję lokalną i emituje SIGNED_OUT.

Administruj użytkownikami#

Administracja użytkownikami potrzebuje klucza service_role. Dostępna jest tylko na serwerze: odczyt aura.authAdmin w przeglądarce wyrzuca błąd.

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() // → { łącznie, zweryfikowane, zbanowane, mfa_enabled, new_7d }

generateLink akceptuje 'magic', 'recovery' lub 'invite'. Klient administracyjny zarządza także ustawieniami autoryzacji projektu (getSettings, updateSettings), szablonami e-maili, sesjami każdego użytkownika i dziennikiem audytu (getAuditLog). Każda metoda jest wymieniona w odnośniku autoryzacji auth reference.