I flussi quotidiani di aura.auth, con il comportamento di ogni chiamata osservato rispetto a uno stack in esecuzione.
Questo testo inglese è stato generato automaticamente dall'originale francese e non è stato ancora rivisto.
La fonte inglese è cambiata da questa traduzione. Alcune informazioni potrebbero non essere aggiornate.
Questa pagina è stata tradotta automaticamente. Fa fede la versione inglese.
#Nozioni di base
1. Iscriviti e accedi
auth.tstypescript
import { createClient, isMfaChallenge } from '@aurabase/aurabase-js'
const aura = createClient(process.env.AURA_URL!, process.env.AURA_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', "Identificativi non validi" |
| 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.
#Stato
2. 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.
#Conto
3. 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.
#Alternative
4. Collegamenti, codici e OAuth
passwordless.tstypescript
// Collegamento magico via e-mail
await aura.auth.signInWithMagicLink({ email })
// → { messaggio: "Se questa email esiste, un collegamento di connessione è stato inviato" }
// 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: il provider è il PRIMO argomento, una stringa
const { data } = await aura.auth.signInWithOAuth('google', { redirectTo: 'https://app.example.com/callback' })
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.
Non il modulo supabase-js
signInWithOAuth({ provider: 'google' }) restituisce l'errore invalid_provider. Passa il provider come primo argomento.
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).
#Secondo fattore
5. Autenticazione a più fattori
mfa.tstypescript
// 1. Iscriviti: mostra il codice QR creato da otpauth_url
const { data: enrol } = await aura.auth.mfaEnroll() // → { segreto, otpauth_url }
// 2. Conferma con il primo codice dell'app di autenticazione: riceverai i codici di ripristino
const { data: confirm } = await aura.auth.mfaVerifySetup(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.mfaVerify({ mfa_token: login.data.mfa_token, code: codeFromApp })
}
mfaUnenroll(password) lo disattiva e regenerateRecoveryCodes(code) emette nuovi codici di ripristino. Una sfida emette MFA_CHALLENGE e nessuna sessione viene archiviata finché mfaVerify non ha esito positivo.
#Dispositivi
6. 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, compreso 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.
#Server
7. 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.AURA_URL!, process.env.AURA_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 .
