شعار أوراباسي
aurabaseمستندات
مستندات›أدلة›Authenticate users (SDK)

مصادقة المستخدمين باستخدام JavaScript SDK

التدفقات اليومية لـ aura.auth، مع سلوك كل مكالمة كما لوحظ مقابل مكدس قيد التشغيل.

11 د قراءة·المستوى وسيطة·تمت المراجعة في 12‏/10‏/2026
تم إنشاء هذا النص الإنجليزي تلقائيًا من النص الأصلي الفرنسي ولم تتم مراجعته بعد.
لقد تغير المصدر الإنجليزي منذ هذه الترجمة. قد تكون بعض المعلومات قديمة.
تمت ترجمة هذه الصفحة تلقائيًا. النسخة الإنجليزية موثوقة.
#
الأساسيات

1. قم بالتسجيل وتسجيل الدخول

auth.tstypescript
import { createClient, isMfaChallenge } from '@aurabase/aurabase-js'

const aura = createClient(process.env.AURA_URL!, process.env.AURA_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 حتى تقوم بتمكينه في إعدادات مصادقة المشروع.

#
الدولة

2. الجلسة وفعالياتها

session.tstypescript
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.
#
الحساب

3. الملف الشخصي وكلمة المرور

profile.tstypescript
// البيانات الوصفية: قم بتمريرها في "البيانات".
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) يطلب كلمة المرور الحالية، ويحذف الحساب ويمسح الجلسة المحلية.

#
البدائل

4. الروابط والأكواد وOAuth

passwordless.tstypescript
// الرابط السحري عن طريق البريد الإلكتروني
await aura.auth.signInWithMagicLink({ email })
// → { message: "إذا كان البريد الإلكتروني موجودًا، فسيكون رهن الاتصال مرسلاً" }
// الجواب هو نفسه سواء كان الحساب موجودًا أم لا: فهو لا يسرب الحسابات.

// رموز لمرة واحدة
await aura.auth.signInWithEmailOtp(email)
await aura.auth.signInWithSmsOtp(phone)
await aura.auth.verifyOtp({ type: 'email', email, code })     // أيضًا: "sms"، "magiclink"، "تسجيل"، "استرداد"، "email_change"

// OAuth: الموفر هو الوسيطة الأولى، وهي سلسلة
const { data } = await aura.auth.signInWithOAuth('google', { redirectTo: 'https://app.example.com/callback' })
window.location.href = data!.url

signInWithOAuth يُرجع عنوان URL المراد فتحه؛ لا يتنقل من تلقاء نفسه. يجب تمكين الموفر وتكوينه في المشروع، وإلا فإن عنوان URL للبدء يجيب PROVIDER_NOT_CONFIGURED.

ليس نموذج Supabase-js

signInWithOAuth({ provider: 'google' }) يُرجع الخطأ invalid_provider. قم بتمرير الموفر كوسيطة أولى.

بعد إعادة التوجيه مرة أخرى، يقرأ العميل الجلسة من عنوان URL بنفسه (detectSessionInUrl). بالنسبة لتدفق PKCE، قم بتمرير flowType: 'pkce' واحتفظ بالمخزن الدائم الافتراضي، وسيقوم العميل بتبادل الرمز لك.

اربط موفرًا ثانيًا بحساب مسجل الدخول باستخدام linkIdentity(provider)، وأدرجه باستخدام listIdentities() وقم بإزالة الآخر باستخدام unlinkIdentity(identityId).

#
العامل الثاني

5. المصادقة متعددة العوامل

mfa.tstypescript
// 1. التسجيل: أظهر رمز الاستجابة السريعة الذي تم إنشاؤه من otpauth_url
const { data: enrol } = await aura.auth.mfaEnroll()   // → { سر، otpauth_url }
// 2. قم بالتأكيد باستخدام الرمز الأول من تطبيق المصادقة: ستتلقى رموز الاسترداد
const { data: confirm } = await aura.auth.mfaVerifySetup(codeFromApp) // → {رموز الاسترداد: [...] }

// 3. من الآن فصاعدًا، يؤدي تسجيل الدخول إلى إرجاع التحدي بدلاً من الجلسة
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) بإيقاف تشغيله، ويصدر regenerateRecoveryCodes(code) رموز استرداد جديدة. يُصدر التحدي MFA_CHALLENGE ولا يتم تخزين أي جلسة حتى ينجح mfaVerify.

#
الأجهزة

6. الأجهزة والجلسات

devices.tstypescript
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.

#
الخادم

7. إدارة المستخدمين

تحتاج إدارة المستخدم إلى مفتاح service_role. إنه متاح فقط على الخادم: قراءة aura.authAdmin في المتصفح تؤدي إلى حدوث خطأ.

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') // → {رابط، رمز مميز}
await admin.authAdmin.deleteUser(created!.id)

const { data: stats } = await admin.authAdmin.getUserStats() // → { الإجمالي، تم التحقق منه، المحظور، mfa_enabled، new_7d }

generateLink يقبل 'magic' أو 'recovery' أو 'invite'. يدير العميل المسؤول أيضًا إعدادات مصادقة المشروع (getSettings, updateSettings) وقوالب البريد الإلكتروني وجلسات كل مستخدم وسجل التدقيق (getAuditLog). تم إدراج كل طريقة في مرجع المصادقة .