Autentica gli utenti con l'SDK JavaScript
I flussi quotidiani di aura.auth, con il comportamento di ogni chiamata osservato rispetto a uno stack in esecuzione.
Iscriviti e accedi#
import { createClient, isMfaChallenge } from '@aurabase/aurabase-js'
const aura = createClient(process.env.NEXT_PUBLIC_AURABASE_URL!, process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!)
// Crea un account
const { data, error } = await aura.auth.signUp({ email: 'ada@example.com', password: 'a-long-passphrase' })
// Accedi
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)
// altrimenti ora esiste una sessione
Entrambe le chiamate restituiscono la stessa forma. In caso di successo, data contiene access_token, refresh_token, expires_in (900 secondi) e user e il client memorizza la sessione per te. La richiesta successiva è già autenticata.
Ciò che fa signUp dipende dalle impostazioni del tuo progetto. Nel nostro progetto di test l'utente ha effettuato l'accesso immediatamente con email_verified: false e un progetto può richiedere prima la conferma.
Errori da gestire, come osservato:
| Chiama | Errore |
|---|---|
| Password errata | 401, code: 'INVALID_CREDENTIALS', "E-mail o password non valide." |
| Link o codice non valido o scaduto | 401, code: 'INVALID_OTP' |
| Accesso anonimo quando il progetto non lo consente | 403, FORBIDDEN |
signInAnonymously() crea un utente senza indirizzo email, ma in un nuovo progetto è disabilitato e restituisce 403 finché non lo abiliti nelle impostazioni di autenticazione del progetto. Un utente anonimo ha il ruolo authenticated (possiede le sue righe: auth.uid() è impostato); distinguerlo da un account permanente nelle tue politiche con auth.is_anonymous(), ad esempio una politica restrittiva using (not auth.is_anonymous()).
La sessione e i suoi eventi#
const { data: { session } } = await aura.auth.getSession() // nessuna chiamata di rete: legge il negozio
const { data: user } = await aura.auth.getUser() // chiede il servitore
const { data: { subscription } } = aura.auth.onAuthStateChange(({ event, user }) => {
// evento: 'INITIAL_SESSION' | 'FIRMATO_IN' | 'TOKEN_REFRESHED' | 'USER_UPDATED' | 'SIGNED_OUT' | 'MFA_CHALLENGE'
})
subscription.unsubscribe()
Una corsa reale ha prodotto questa sequenza: INITIAL_SESSION, SIGNED_IN (iscrizione), SIGNED_IN (accesso), USER_UPDATED, TOKEN_REFRESHED, SIGNED_OUT.
- Il client aggiorna il token di accesso prima che scada. Chiama
aura.auth.refreshSession()per forzarlo. getSession()è locale e veloce: usalo per il rendering. UtilizzagetUser()quando hai bisogno della vista corrente dell'utente da parte del server.- Per consegnare una sessione al client da altrove (un cookie, un server), utilizzare
setSession(accessToken, refreshToken). Una coppia non valida viene rifiutata e viene mantenuta la sessione precedente. - Per il rendering lato server, consulta Next.js App Router e SSR.
Profilo e password#
// Metadati: passali in `data`
await aura.auth.updateUser({ data: { theme: 'dark', plan: 'free' } })
// → user.user_metadata è { plan: 'free', theme: 'dark' } e getUser() restituisce lo stesso
// Cambia l'e-mail: l'indirizzo NON cambia ancora
await aura.auth.updateUser({ email: 'new@example.com' })
// Un collegamento di conferma porta al nuovo indirizzo. Finché non viene utilizzato, user.email mantiene il vecchio valore.
// Conferma con: aura.auth.verifyOtp({ type: 'email_change', token })
// Cambia la password
await aura.auth.updatePassword('a-new-long-passphrase', 'a-long-passphrase')
Il server revoca tutte le sessioni quando la password cambia. updatePassword cancella la sessione locale ed emette SIGNED_OUT: accedi di nuovo con la nuova password. In una corsa reale, getSession() era vuoto subito dopo la chiamata e l'accesso con la nuova password ha funzionato.
Password dimenticata: aura.auth.resetPasswordForEmail({ email }) invia l'e-mail di ripristino. L'utente quindi lo completa con verifyOtp({ type: 'recovery', token, password }).
Elimina l'account: aura.auth.deleteUser(password) richiede la password corrente, elimina l'account e cancella la sessione locale.
Collegamenti, codici e OAuth#
// Collegamento magico via e-mail
await aura.auth.signInWithMagicLink({ email })
// → un messaggio di conferma generico
// La risposta è la stessa indipendentemente dal fatto che il conto esista o meno: non fa trapelare conti.
// Codici monouso
await aura.auth.signInWithEmailOtp(email)
await aura.auth.signInWithSmsOtp(phone)
await aura.auth.verifyOtp({ type: 'email', email, code }) // anche: 'sms', 'magiclink', 'registrazione', 'recupero', 'email_change'
// OAuth: firma canonica o forma oggetto compatibile con Supabase
const { data } = await aura.auth.signInWithOAuth('google', { redirectTo: 'https://app.example.com/callback' })
// oppure: attendono aura.auth.signInWithOAuth({ provider: 'google', opzioni: { reindirizzamentoTo: '...' } })
if (data?.url) window.location.href = data.url
signInWithOAuth restituisce l'URL da aprire; non naviga da solo. Il provider deve essere abilitato e configurato nel progetto, altrimenti l'URL di avvio risponde PROVIDER_NOT_CONFIGURED.
signInWithOAuth accetta signInWithOAuth('google', { redirectTo }) o la forma dell'oggetto signInWithOAuth({ provider: 'google', options: { redirectTo } }). Entrambe le sintassi sono completamente tipizzate e supportate.
Dopo il reindirizzamento, il client legge da solo la sessione dall'URL (detectSessionInUrl). Per il flusso PKCE, passa flowType: 'pkce', mantieni l'archivio persistente predefinito e il client scambia il codice per te.
Collega un secondo provider a un account registrato con linkIdentity(provider), elencalo con listIdentities() e rimuovine uno con unlinkIdentity(identityId).
Autenticazione a più fattori#
// 1. Iscrizione: tramite lo spazio dei nomi aura.auth.mfa o il metodo flat
const { data: enrol } = await aura.auth.mfa.enroll() // → { segreto, otpauth_url }
// 2. Conferma con il primo codice dell'app di autenticazione: riceverai i codici di ripristino
const { data: confirm } = await aura.auth.mfa.verifySetup(codeFromApp) // → {codici_recupero: [...] }
// 3. D'ora in poi, l'accesso restituirà una sfida anziché una sessione
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) (o mfaUnenroll) lo disattiva e mfa.regenerateRecoveryCodes(code) emette nuovi codici di ripristino. Una sfida emette MFA_CHALLENGE e nessuna sessione viene archiviata finché mfaVerify non ha esito positivo.
Dispositivi e sessioni#
const { data } = await aura.auth.listSessions()
// [{ id, informazioni_dispositivo, indirizzo_ip, creato_at, scade_at, last_used_at, is_current }, …]
await aura.auth.revokeSession(sessionId) // disconnettersi da un dispositivo
await aura.auth.revokeAllSessions() // esci ovunque, incluso questo
await aura.auth.signOut() // solo questo dispositivo
is_current contrassegna la sessione che stai utilizzando. signOut revoca il token di aggiornamento sul server quando ce n'è uno, cancella la sessione locale ed emette SIGNED_OUT.
Amministrare gli utenti#
L'amministrazione degli utenti necessita di una chiave service_role. È disponibile solo sul server: la lettura di aura.authAdmin in un browser genera un errore.
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') // → { collegamento, token }
await admin.authAdmin.deleteUser(created!.id)
const { data: stats } = await admin.authAdmin.getUserStats() // → { totale, verificato, vietato, mfa_enabled, new_7d }
generateLink accetta 'magic', 'recovery' o 'invite'. Il client di amministrazione gestisce anche le impostazioni di autenticazione del progetto (getSettings, updateSettings), i modelli di posta elettronica, le sessioni di ogni utente e il registro di controllo (getAuditLog). Ogni metodo è elencato nel riferimento di autenticazione auth reference.