Vai al contenuto
Logo Aurabase
aurabase

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.

Guida pratica11 min lettoLivello intermedioRevisionato il 12 ott 2026

Questa pagina è stata tradotta automaticamente. Fa fede la versione inglese.

Iscriviti e accedi#

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

// 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:

ChiamaErrore
Password errata401, code: 'INVALID_CREDENTIALS', "E-mail o password non valide."
Link o codice non valido o scaduto401, code: 'INVALID_OTP'
Accesso anonimo quando il progetto non lo consente403, 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#

session.tstypescript
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. Utilizza getUser() 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#

profile.tstypescript
// 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')
La modifica della password ti disconnette

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#

passwordless.tstypescript
// 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.

Firme OAuth flessibili

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#

mfa.tstypescript
// 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#

devices.tstypescript
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.

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') // → { 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.