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' | '토큰_새로 고침' | '사용자_업데이트됨' | 'SIGNED_OUT' | 'MFA_챌린지'
})
subscription.unsubscribe()
실제 실행에서는 INITIAL_SESSION, SIGNED_IN (가입), SIGNED_IN (로그인), USER_UPDATED, TOKEN_REFRESHED, SIGNED_OUT시퀀스가 생성되었습니다.
- 클라이언트는 만료되기 전에 액세스 토큰을 새로 고칩니다. 강제로 실행하려면
aura.auth.refreshSession()를 호출하세요. getSession()는 로컬이며 빠릅니다. 렌더링에 사용하세요. 서버의 현재 사용자 보기가 필요한 경우getUser()를 사용하십시오.- 다른 곳(쿠키, 서버)에서 클라이언트에 세션을 전달하려면
setSession(accessToken, refreshToken)를 사용하세요. 유효하지 않은 쌍은 거부되고 이전 세션이 유지됩니다. - 서버 측 렌더링의 경우 Next.js 앱 라우터 및 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 }) // 또한: 'sms', 'magiclink', '가입', '복구', 'email_change'
// OAuth: 표준 서명 또는 Supabase호환 개체 모양
const { data } = await aura.auth.signInWithOAuth('google', { redirectTo: 'https://app.example.com/callback' })
// 또는 : aura.auth.signInWithOAuth({ 공급자: 'google', 옵션: { 리디렉션: '...' } })를 기다립니다.
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, Created_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)를 관리합니다. 모든 방법은 인증 참조에 나열되어 있습니다.