Autenticar usuarios con el SDK de JavaScript
Los flujos cotidianos de aura.auth, con el comportamiento de cada llamada observado en una pila en ejecución.
Regístrate e inicia sesión#
import { createClient, isMfaChallenge } from '@aurabase/aurabase-js'
const aura = createClient(process.env.NEXT_PUBLIC_AURABASE_URL!, process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!)
// Crea una cuenta
const { data, error } = await aura.auth.signUp({ email: 'ada@example.com', password: 'a-long-passphrase' })
// Iniciar sesión
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)
// de lo contrario ya existe una sesión
Ambas llamadas devuelven la misma forma. En caso de éxito, data contiene access_token, refresh_token, expires_in (900 segundos) y user, y el cliente almacena la sesión por usted. La siguiente solicitud ya está autenticada.
Lo que hace signUp depende de la configuración de su proyecto. En nuestro proyecto de prueba, el usuario inició sesión de inmediato con email_verified: false y un proyecto puede requerir confirmación primero.
Fallas que debes manejar, como se observa:
| llamar | error |
|---|---|
| Contraseña incorrecta | 401, code: 'INVALID_CREDENTIALS', "Correo electrónico o contraseña no válidos". |
| Enlace o código no válido o caducado | 401, code: 'INVALID_OTP' |
| Inicio de sesión anónimo cuando el proyecto no lo permite | 403, FORBIDDEN |
signInAnonymously() crea un usuario sin una dirección de correo electrónico, pero en un nuevo proyecto está deshabilitado y devuelve 403 hasta que lo habilite en la configuración de autenticación del proyecto. Un usuario anónimo tiene el rol authenticated (es dueño de sus filas: auth.uid() está configurado); distinga de una cuenta permanente en sus políticas con auth.is_anonymous(), por ejemplo una política restrictiva using (not auth.is_anonymous()).
La sesión y sus acontecimientos.#
const { data: { session } } = await aura.auth.getSession() // sin llamada de red: lee la tienda
const { data: user } = await aura.auth.getUser() // pregunta el servidor
const { data: { subscription } } = aura.auth.onAuthStateChange(({ event, user }) => {
// evento: 'INITIAL_SESSION' | 'SIGNED_IN' | 'TOKEN_REFRESHED' | 'USUARIO_ACTUALIZADO' | 'SIGNED_OUT' | 'MFA_CHALLENGE'
})
subscription.unsubscribe()
Una ejecución real produjo esta secuencia: INITIAL_SESSION, SIGNED_IN (registro), SIGNED_IN (inicio de sesión), USER_UPDATED, TOKEN_REFRESHED, SIGNED_OUT.
- El cliente actualiza el token de acceso antes de que caduque. Llame a
aura.auth.refreshSession()para forzarlo. getSession()es local y rápido: úselo para renderizar. UtilicegetUser()cuando necesite la vista actual del servidor del usuario.- Para entregar una sesión al cliente desde otro lugar (una cookie, un servidor), use
setSession(accessToken, refreshToken). Se rechaza un par no válido y se mantiene la sesión anterior. - Para la representación del lado del servidor, consulte Next.js App Router y SSR.
Perfil y contraseña#
// Metadatos: páselo en `datos`
await aura.auth.updateUser({ data: { theme: 'dark', plan: 'free' } })
// → user.user_metadata es { plan: 'gratis', tema: 'oscuro' }, y getUser() devuelve lo mismo
// Cambiar el correo electrónico: la dirección NO cambia todavía
await aura.auth.updateUser({ email: 'new@example.com' })
// Un enlace de confirmación va a la nueva dirección. Hasta que se utilice, user.email mantiene el valor anterior.
// Confirme con: aura.auth.verifyOtp({ tipo: 'email_change', token })
// cambiar la contraseña
await aura.auth.updatePassword('a-new-long-passphrase', 'a-long-passphrase')
El servidor revoca todas las sesiones cuando cambia la contraseña. updatePassword borra la sesión local y emite SIGNED_OUT: inicia sesión nuevamente con la nueva contraseña. En una ejecución real, getSession() estaba vacío justo después de la llamada y el inicio de sesión con la nueva contraseña funcionó.
Olvidé mi contraseña: aura.auth.resetPasswordForEmail({ email }) envía el correo electrónico de restablecimiento. Luego, el usuario lo completa con verifyOtp({ type: 'recovery', token, password }).
Eliminar la cuenta: aura.auth.deleteUser(password) solicita la contraseña actual, elimina la cuenta y borra la sesión local.
Enlaces, códigos y OAuth#
// Enlace mágico por correo electrónico
await aura.auth.signInWithMagicLink({ email })
// → un mensaje de confirmación genérico
// La respuesta es la misma exista o no la cuenta: no filtra cuentas.
// Códigos de un solo uso
await aura.auth.signInWithEmailOtp(email)
await aura.auth.signInWithSmsOtp(phone)
await aura.auth.verifyOtp({ type: 'email', email, code }) // también: 'sms', 'magiclink', 'registro', 'recuperación', 'email_change'
// OAuth: firma canónica o forma de objeto compatible con Supabase
const { data } = await aura.auth.signInWithOAuth('google', { redirectTo: 'https://app.example.com/callback' })
// o: espere aura.auth.signInWithOAuth ({ proveedor: 'google', opciones: { redirigir a: '...' } })
if (data?.url) window.location.href = data.url
signInWithOAuth devuelve la URL para abrir; no navega solo. El proveedor debe estar habilitado y configurado en el proyecto; de lo contrario, la URL de inicio responde PROVIDER_NOT_CONFIGURED.
signInWithOAuth acepta signInWithOAuth('google', { redirectTo }) o la forma del objeto signInWithOAuth({ provider: 'google', options: { redirectTo } }). Ambas sintaxis están totalmente escritas y soportadas.
Después de la redirección, el cliente lee la sesión desde la URL por sí mismo (detectSessionInUrl). Para el flujo PKCE, pase flowType: 'pkce', mantenga el almacén persistente predeterminado y el cliente intercambiará el código por usted.
Vincula un segundo proveedor a una cuenta iniciada con linkIdentity(provider), enuméralo con listIdentities() y elimina uno con unlinkIdentity(identityId).
Autenticación multifactor#
// 1. Inscríbase: a través del espacio de nombres aura.auth.mfa o el método plano
const { data: enrol } = await aura.auth.mfa.enroll() // → { secreto, otpauth_url }
// 2. Confirme con el primer código de la aplicación de autenticación: recibirá códigos de recuperación
const { data: confirm } = await aura.auth.mfa.verifySetup(codeFromApp) // → { códigos_recuperación: [...] }
// 3. A partir de ahora, iniciar sesión devuelve un desafío en lugar de una sesión.
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 desactiva y mfa.regenerateRecoveryCodes(code) emite nuevos códigos de recuperación. Un desafío emite MFA_CHALLENGE y no se almacena ninguna sesión hasta que mfaVerify tenga éxito.
Dispositivos y sesiones#
const { data } = await aura.auth.listSessions()
// [{ id, información_dispositivo, dirección_ip, creado_en, expira_en, último_usado_en, es_actual},…]
await aura.auth.revokeSession(sessionId) // cerrar sesión en un dispositivo
await aura.auth.revokeAllSessions() // cerrar sesión en todas partes, incluido este
await aura.auth.signOut() // este dispositivo solo
is_current marca la sesión que estás utilizando. signOut revoca el token de actualización en el servidor cuando hay uno, borra la sesión local y emite SIGNED_OUT.
Administrar usuarios#
La administración de usuarios necesita una clave service_role. Está disponible solo en el servidor: leer aura.authAdmin en un navegador genera un error.
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') // → { enlace, token }
await admin.authAdmin.deleteUser(created!.id)
const { data: stats } = await admin.authAdmin.getUserStats() // → { total, verificado, prohibido, mfa_enabled, new_7d }
generateLink acepta 'magic', 'recovery' o 'invite'. El cliente de administración también administra la configuración de autenticación del proyecto (getSettings, updateSettings), plantillas de correo electrónico, sesiones de cada usuario y el registro de auditoría (getAuditLog). Cada método aparece en la referencia de autenticación auth reference.