Аутентификация пользователей с помощью JavaScript SDK
Ежедневные потоки aura.auth с поведением каждого вызова, наблюдаемым в работающем стеке.
Зарегистрируйтесь и войдите в систему#
import { createClient, isMfaChallenge } from '@aurabase/aurabase-js'
const aura = createClient(process.env.NEXT_PUBLIC_AURABASE_URL!, process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!)
// Завести аккаунт
const { data, error } = await aura.auth.signUp({ email: 'ada@example.com', password: 'a-long-passphrase' })
// Войти
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)
// в противном случае сеанс уже существует
Оба вызова возвращают одну и ту же форму. В случае успеха data содержит access_token, refresh_token, expires_in (900 секунд) и user, и клиент сохраняет сеанс для вас. Следующий запрос уже аутентифицирован.
Действия signUp зависят от настроек вашего проекта. В нашем тестовом проекте пользователь сразу авторизовался с помощью email_verified: false, и проект может сначала потребовать подтверждения.
Сбои, с которыми вам следует справиться, как замечено:
| Вызов | Ошибка |
|---|---|
| Неправильный пароль | 401, code: 'INVALID_CREDENTIALS', «Неверный адрес электронной почты или пароль». |
| Недействительная или просроченная ссылка или код | 401, code: 'INVALID_OTP' |
| Анонимный вход, когда проект запрещает его | 403, FORBIDDEN |
signInAnonymously() создает пользователя без адреса электронной почты, но в новом проекте он отключен и возвращает 403, пока вы не включите его в настройках аутентификации проекта. Анонимный пользователь имеет роль authenticated (он владеет своими строками: установлено auth.uid()); отличайте ее от постоянной учетной записи в своих политиках с помощью auth.is_anonymous(), например ограничительной политики using (not auth.is_anonymous()).
Сессия и ее события#
const { data: { session } } = await aura.auth.getSession() // нет сетевого вызова: читает магазин
const { data: user } = await aura.auth.getUser() // спрашивает сервер
const { data: { subscription } } = aura.auth.onAuthStateChange(({ event, user }) => {
// событие: «INITIAL_SESSION» | 'SIGNED_IN' | 'TOKEN_REFRESHED' | 'USER_UPDATED' | 'SIGNED_OUT' | 'MFA_CHALLENGE'
})
subscription.unsubscribe()
Реальный запуск привел к следующей последовательности: INITIAL_SESSION, SIGNED_IN (регистрация), SIGNED_IN (вход), USER_UPDATED, TOKEN_REFRESHED, SIGNED_OUT.
- Клиент обновляет токен доступа до истечения срока его действия. Вызовите
aura.auth.refreshSession(), чтобы принудительно это сделать. getSession()является локальным и быстрым: используйте его для рендеринга. ИспользуйтеgetUser(), когда вам нужно текущее представление пользователя на сервере.- Чтобы передать сеанс клиенту из другого места (файла cookie, сервера), используйте
setSession(accessToken, refreshToken). Недействительная пара отклоняется, и предыдущий сеанс сохраняется. - Для рендеринга на стороне сервера см. Next.js App Router и SSR.
Профиль и пароль#
// Метаданные: передайте их в `data`
await aura.auth.updateUser({ data: { theme: 'dark', plan: 'free' } })
// → user.user_metadata — это { plan: 'free', theme: 'dark' }, и getUser() возвращает то же самое
// Смените электронную почту: адрес пока НЕ меняется
await aura.auth.updateUser({ email: 'new@example.com' })
// Ссылка для подтверждения ведет на новый адрес. До тех пор, пока он не будет использован, user.email сохраняет старое значение.
// Подтвердите: aura.auth.verifyOtp({ type: 'email_change', token })
// Изменить пароль
await aura.auth.updatePassword('a-new-long-passphrase', 'a-long-passphrase')
Сервер отменяет все сеансы при изменении пароля. updatePassword очищает локальный сеанс и выдает SIGNED_OUT: войдите снова с новым паролем. В реальном запуске getSession() был пуст сразу после вызова, и вход с новым паролем сработал.
Забыли пароль: aura.auth.resetPasswordForEmail({ email }) отправляет электронное письмо для сброса пароля. Затем пользователь завершает его с помощью verifyOtp({ type: 'recovery', token, password }).
Удалить учетную запись: aura.auth.deleteUser(password) запрашивает текущий пароль, удаляет учетную запись и очищает локальный сеанс.
Ссылки, коды и OAuth#
// Волшебная ссылка по электронной почте
await aura.auth.signInWithMagicLink({ email })
// → общее подтверждающее сообщение
// Ответ один и тот же независимо от того, существует учетная запись или нет: утечки учетных записей не происходит.
// Одноразовые коды
await aura.auth.signInWithEmailOtp(email)
await aura.auth.signInWithSmsOtp(phone)
await aura.auth.verifyOtp({ type: 'email', email, code }) // также: «смс», «магическая ссылка», «регистрация», «восстановление», «email_change»
// OAuth: каноническая подпись или Supabase-совместимая форма объекта.
const { data } = await aura.auth.signInWithOAuth('google', { redirectTo: 'https://app.example.com/callback' })
// или: await aura.auth.signInWithOAuth({Provider: 'google', options: {redirectTo: '...' } })
if (data?.url) window.location.href = data.url
signInWithOAuth возвращает URL-адрес для открытия; он не перемещается сам по себе. Поставщик должен быть включен и настроен в проекте, иначе стартовый URL будет отвечать PROVIDER_NOT_CONFIGURED.
signInWithOAuth принимает либо signInWithOAuth('google', { redirectTo }), либо форму объекта signInWithOAuth({ provider: 'google', options: { redirectTo } }). Оба синтаксиса полностью типизированы и поддерживаются.
После обратного перенаправления клиент самостоятельно считывает сеанс по URL-адресу (detectSessionInUrl). Для потока PKCE передайте flowType: 'pkce', сохраните постоянное хранилище по умолчанию, и клиент заменит вам код.
Свяжите второго провайдера с зарегистрированной учетной записью с помощью linkIdentity(provider), перечислите его с помощью listIdentities() и удалите одного с помощью unlinkIdentity(identityId).
Многофакторная аутентификация#
// 1. Регистрация: через пространство имен aura.auth.mfa или плоский метод.
const { data: enrol } = await aura.auth.mfa.enroll() // → { секрет, otpauth_url }
// 2. Подтвердите первый код из приложения аутентификации: вы получите коды восстановления.
const { data: confirm } = await aura.auth.mfa.verifySetup(codeFromApp) // → { коды_восстановления: [...] }
// 3. С этого момента при входе в систему вместо сеанса возвращается вызов.
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) (или mfaUnenroll) отключает его, а mfa.regenerateRecoveryCodes(code) выдает новые коды восстановления. При вызове генерируется MFA_CHALLENGE, и сеанс не сохраняется до тех пор, пока mfaVerify не завершится успешно.
Устройства и сеансы#
const { data } = await aura.auth.listSessions()
// [{ id, device_info, ip_address, созданный_at, expires_at, Last_used_at, is_current }, …]
await aura.auth.revokeSession(sessionId) // выйти из одного устройства
await aura.auth.revokeAllSessions() // выхожу везде, включая этот
await aura.auth.signOut() // только это устройство
is_current отмечает сеанс, который вы используете. signOut отзывает токен обновления на сервере, если он есть, очищает локальный сеанс и выдает SIGNED_OUT.
Администрирование пользователей#
Для администрирования пользователей необходим ключ service_role. Он доступен только на сервере: чтение aura.authAdmin в браузере выдаёт ошибку.
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') // → { ссылка, токен }
await admin.authAdmin.deleteUser(created!.id)
const { data: stats } = await admin.authAdmin.getUserStats() // → { всего, проверено, забанено, mfa_enabled, new_7d }
generateLink принимает 'magic', 'recovery' или 'invite'. Клиент администратора также управляет настройками аутентификации проекта (getSettings, updateSettings), шаблонами электронной почты, сеансами каждого пользователя и журналом аудита (getAuditLog). Каждый метод указан в ссылке на аутентификацию auth reference.