مصادقة المستخدمين باستخدام 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"
})
subscription.unsubscribe()
أنتج التشغيل الحقيقي هذا التسلسل: INITIAL_SESSION, SIGNED_IN (تسجيل)، SIGNED_IN (تسجيل الدخول)، USER_UPDATED, TOKEN_REFRESHED, SIGNED_OUT.
- يقوم العميل بتحديث رمز الوصول قبل انتهاء صلاحيته. اتصل بـ
aura.auth.refreshSession()لإجباره. getSession()محلي وسريع: استخدمه للعرض. استخدمgetUser()عندما تحتاج إلى عرض الخادم الحالي للمستخدم.- لتسليم جلسة إلى العميل من مكان آخر (ملف تعريف الارتباط، خادم)، استخدم
setSession(accessToken, refreshToken). يتم رفض الزوج غير الصالح ويتم الاحتفاظ بالجلسة السابقة. - بالنسبة للعرض من جانب الخادم، راجع Next.js App Router وSSR.
الملف الشخصي وكلمة المرور#
// البيانات الوصفية: قم بتمريرها في "البيانات".
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', الخيارات: { 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()
// [{ المعرف، معلومات_الجهاز، عنوان IP_، تم إنشاؤه، انتهاء_الوقت، آخر_استخدام_ات، 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.