المصادقة مع Firebase باستخدام رابط البريد الإلكتروني في JavaScript

يمكنك استخدام مصادقة Firebase لتسجيل دخول مستخدم عن طريق إرسال رسالة إلكترونية إليه تحتوي على رابط يمكنه النقر عليه لتسجيل الدخول. أثناء هذه العملية، يتم أيضًا إثبات ملكية عنوان البريد الإلكتروني الخاص بالمستخدم.

تتوفّر مزايا عديدة عند تسجيل الدخول باستخدام البريد الإلكتروني، وهي:

  • تسجيل الدخول وإنشاء الحساب بسهولة
  • تقليل مخاطر إعادة استخدام كلمة المرور نفسها في تطبيقات مختلفة، ما قد يقلّل من أمان كلمات المرور حتى تلك التي تم اختيارها بعناية
  • هي إمكانية مصادقة المستخدم مع التحقّق أيضًا من أنّه المالك الشرعي لعنوان بريد إلكتروني.
  • يحتاج المستخدم فقط إلى حساب بريد إلكتروني يمكنه الوصول إليه لتسجيل الدخول. لا يُشترط أن يكون لديك رقم هاتف أو حساب على وسائل التواصل الاجتماعي.
  • يمكن للمستخدم تسجيل الدخول بأمان بدون الحاجة إلى تقديم (أو تذكُّر) كلمة مرور، وهو أمر قد يكون مرهقًا على جهاز جوّال.
  • يمكن ترقية حساب مستخدم حالي سبق له تسجيل الدخول باستخدام معرّف بريد إلكتروني (كلمة مرور أو حساب موحّد) ليتمكّن من تسجيل الدخول باستخدام البريد الإلكتروني فقط. على سبيل المثال، يمكن للمستخدم الذي نسي كلمة المرور تسجيل الدخول بدون الحاجة إلى إعادة ضبطها.

قبل البدء

إذا لم يسبق لك إجراء ذلك، انسخ مقتطف الإعداد من وحدة تحكّم Firebase إلى مشروعك كما هو موضّح في إضافة Firebase إلى مشروع JavaScript.

لتسجيل دخول المستخدمين باستخدام رابط إلكتروني، عليك أولاً تفعيل مزوِّد خدمة البريد الإلكتروني وطريقة تسجيل الدخول باستخدام رابط إلكتروني في مشروع Firebase:

  1. في وحدة تحكّم Firebase، انتقِل إلى الأمان > المصادقة.

  2. في علامة التبويب طريقة تسجيل الدخول، فعِّل طريقة تسجيل الدخول البريد الإلكتروني/كلمة المرور. يُرجى العِلم أنّه يجب تفعيل تسجيل الدخول باستخدام عنوان البريد الإلكتروني وكلمة المرور لاستخدام تسجيل الدخول باستخدام رابط البريد الإلكتروني.

  3. في القسم نفسه، فعِّل موفّر خدمة تسجيل الدخول رابط البريد الإلكتروني (تسجيل الدخول بدون كلمة مرور).

  4. انقر على حفظ.

لبدء عملية المصادقة، اعرض على المستخدم واجهة تطلب منه تقديم عنوان بريده الإلكتروني، ثم استدعِ الدالة sendSignInLinkToEmail لطلب أن يرسل Firebase رابط المصادقة إلى عنوان البريد الإلكتروني للمستخدم.

  1. أنشئ العنصر ActionCodeSettings الذي يقدّم إلى Firebase تعليمات حول كيفية إنشاء رابط الرسالة الإلكترونية. اضبط الحقول التالية:

    • url: الرابط لصفحة في التطبيق الذي سيتم تضمينه وأي حالة إضافية سيتم تمريرها. أضِف نطاقك إلى قائمة النطاقات المصرّح بها إذا لم يسبق لك إجراء ذلك:

      1. في وحدة تحكّم Firebase، انتقِل إلى علامة التبويب الأمان > المصادقة > الإعدادات.

      2. في قسم النطاقات المعتمَدة، انقر على إضافة نطاق وأضِف نطاقك.

    • ‫android وios: يساعدان Firebase Authentication في تحديد ما إذا كان يجب إنشاء رابط مخصّص للويب فقط أو رابط للأجهزة الجوّالة يتم فتحه على جهاز Android أو Apple.
    • handleCodeInApp: اضبط القيمة على "صحيح". يجب دائمًا إكمال عملية تسجيل الدخول في التطبيق، على عكس إجراءات الرسائل الإلكترونية الأخرى خارج النطاق (إعادة ضبط كلمة المرور وتأكيد عنوان البريد الإلكتروني). ويرجع ذلك إلى أنّه من المتوقّع أن يكون المستخدم قد سجّل الدخول في نهاية عملية الربط، وأن يتم الاحتفاظ بحالة المصادقة داخل التطبيق.
    • linkDomain: عند تحديد نطاقات روابط Hosting مخصّصة لمشروع، حدِّد النطاق الذي تريد استخدامه عند فتح الرابط من خلال تطبيق جوّال محدّد. وإلا، سيتم تلقائيًا اختيار النطاق التلقائي (على سبيل المثال، PROJECT_ID.firebaseapp.com).

    • ‫dynamicLinkDomain: تم إيقاف هذا الحقل نهائيًا. لا تحدّد هذه المَعلمة.

      Web

      const actionCodeSettings = {
  // URL you want to redirect back to. The domain (www.example.com) for this
  // URL must be in the authorized domains list in the Firebase Console.
  url: 'https://www.example.com/finishSignUp?cartId=1234',
  // This must be true.
  handleCodeInApp: true,
  iOS: {
    bundleId: 'com.example.ios'
  },
  android: {
    packageName: 'com.example.android',
    installApp: true,
    minimumVersion: '12'
  },
  // The domain must be configured in Firebase Hosting and owned by the project.
  linkDomain: 'custom-domain.com'
};

      Web

      var actionCodeSettings = {
  // URL you want to redirect back to. The domain (www.example.com) for this
  // URL must be in the authorized domains list in the Firebase Console.
  url: 'https://www.example.com/finishSignUp?cartId=1234',
  // This must be true.
  handleCodeInApp: true,
  iOS: {
    bundleId: 'com.example.ios'
  },
  android: {
    packageName: 'com.example.android',
    installApp: true,
    minimumVersion: '12'
  },
  dynamicLinkDomain: 'example.page.link'
};

    لمزيد من المعلومات حول ActionCodeSettings، يُرجى الرجوع إلى قسم تمرير الحالة في إجراءات البريد الإلكتروني.

  2. اطلب من المستخدم إدخال عنوان بريده الإلكتروني.

  3. أرسِل رابط المصادقة إلى البريد الإلكتروني للمستخدم، واحفظ عنوان البريد الإلكتروني للمستخدم في حال أكمَل عملية تسجيل الدخول باستخدام البريد الإلكتروني على الجهاز نفسه.

    Web

    import { getAuth, sendSignInLinkToEmail } from "firebase/auth";

const auth = getAuth();
sendSignInLinkToEmail(auth, email, actionCodeSettings)
  .then(() => {
    // The link was successfully sent. Inform the user.
    // Save the email locally so you don't need to ask the user for it again
    // if they open the link on the same device.
    window.localStorage.setItem('emailForSignIn', email);
    // ...
  })
  .catch((error) => {
    const errorCode = error.code;
    const errorMessage = error.message;
    // ...
  });

    Web

    firebase.auth().sendSignInLinkToEmail(email, actionCodeSettings)
  .then(() => {
    // The link was successfully sent. Inform the user.
    // Save the email locally so you don't need to ask the user for it again
    // if they open the link on the same device.
    window.localStorage.setItem('emailForSignIn', email);
    // ...
  })
  .catch((error) => {
    var errorCode = error.code;
    var errorMessage = error.message;
    // ...
  });

المخاوف المرتبطة بالأمان

لمنع استخدام رابط تسجيل الدخول لتسجيل الدخول كمستخدم غير مقصود أو على جهاز غير مقصود، يتطلّب Firebase Auth توفير عنوان البريد الإلكتروني للمستخدم عند إكمال عملية تسجيل الدخول. لكي ينجح تسجيل الدخول، يجب أن يتطابق عنوان البريد الإلكتروني هذا مع العنوان الذي تم إرسال رابط تسجيل الدخول إليه في الأصل.

يمكنك تبسيط هذه العملية للمستخدمين الذين يفتحون رابط تسجيل الدخول على الجهاز نفسه الذي طلبوا إرسال الرابط إليه، وذلك من خلال تخزين عنوان بريدهم الإلكتروني محليًا، مثلاً باستخدام localStorage أو ملفات تعريف الارتباط، عند إرسال رسالة إلكترونية لتسجيل الدخول. بعد ذلك، استخدِم هذا العنوان لإكمال عملية التحقّق. لا تمرِّر عنوان البريد الإلكتروني للمستخدم في مَعلمات عنوان URL لإعادة التوجيه، ولا تعِد استخدامه لأنّ ذلك قد يتيح عمليات إدخال الجلسات.

بعد إكمال عملية تسجيل الدخول، ستتم إزالة أي آلية سابقة غير مؤكَّدة لتسجيل الدخول من حساب المستخدم، وسيتم إبطال أي جلسات حالية. على سبيل المثال، إذا سبق لأحد المستخدمين إنشاء حساب غير مؤكّد باستخدام عنوان البريد الإلكتروني وكلمة المرور نفسيهما، ستتم إزالة كلمة مرور المستخدم لمنع المنتحل الذي ادّعى الملكية وأنشأ هذا الحساب غير المؤكّد من تسجيل الدخول مرة أخرى باستخدام عنوان البريد الإلكتروني وكلمة المرور غير المؤكّدَين.

تأكَّد أيضًا من استخدام عنوان URL يبدأ بـ HTTPS في مرحلة الإنتاج لتجنُّب اعتراض الخوادم الوسيطة المحتمل للرابط.

إكمال عملية تسجيل الدخول في صفحة ويب

يكون تنسيق رابط الصفحة في التطبيق المستند إلى البريد الإلكتروني هو نفسه التنسيق المستخدَم في الإجراءات غير المباشرة المتعلقة بالبريد الإلكتروني (تأكيد عنوان البريد الإلكتروني وإعادة ضبط كلمة المرور وإلغاء تغيير عنوان البريد الإلكتروني). تسهّل خدمة Firebase Auth عملية التحقّق هذه من خلال توفير واجهة برمجة التطبيقات isSignInWithEmailLink للتحقّق مما إذا كان الرابط هو رابط تسجيل الدخول باستخدام البريد الإلكتروني.

لإكمال عملية تسجيل الدخول على الصفحة المقصودة، اتّصِل بـ signInWithEmailLink باستخدام عنوان البريد الإلكتروني للمستخدم ورابط البريد الإلكتروني الفعلي الذي يتضمّن الرمز الصالح لمرة واحدة.

Web

import { getAuth, isSignInWithEmailLink, signInWithEmailLink } from "firebase/auth";

// Confirm the link is a sign-in with email link.
const auth = getAuth();
if (isSignInWithEmailLink(auth, window.location.href)) {
  // Additional state parameters can also be passed via URL.
  // This can be used to continue the user's intended action before triggering
  // the sign-in operation.
  // Get the email if available. This should be available if the user completes
  // the flow on the same device where they started it.
  let email = window.localStorage.getItem('emailForSignIn');
  if (!email) {
    // User opened the link on a different device. To prevent session fixation
    // attacks, ask the user to provide the associated email again. For example:
    email = window.prompt('Please provide your email for confirmation');
  }
  // The client SDK will parse the code from the link for you.
  signInWithEmailLink(auth, email, window.location.href)
    .then((result) => {
      // Clear email from storage.
      window.localStorage.removeItem('emailForSignIn');
      // You can access the new user by importing getAdditionalUserInfo
      // and calling it with result:
      // getAdditionalUserInfo(result)
      // You can access the user's profile via:
      // getAdditionalUserInfo(result)?.profile
      // You can check if the user is new or existing:
      // getAdditionalUserInfo(result)?.isNewUser
    })
    .catch((error) => {
      // Some error occurred, you can inspect the code: error.code
      // Common errors could be invalid email and invalid or expired OTPs.
    });
}

Web

// Confirm the link is a sign-in with email link.
if (firebase.auth().isSignInWithEmailLink(window.location.href)) {
  // Additional state parameters can also be passed via URL.
  // This can be used to continue the user's intended action before triggering
  // the sign-in operation.
  // Get the email if available. This should be available if the user completes
  // the flow on the same device where they started it.
  var email = window.localStorage.getItem('emailForSignIn');
  if (!email) {
    // User opened the link on a different device. To prevent session fixation
    // attacks, ask the user to provide the associated email again. For example:
    email = window.prompt('Please provide your email for confirmation');
  }
  // The client SDK will parse the code from the link for you.
  firebase.auth().signInWithEmailLink(email, window.location.href)
    .then((result) => {
      // Clear email from storage.
      window.localStorage.removeItem('emailForSignIn');
      // You can access the new user via result.user
      // Additional user info profile not available via:
      // result.additionalUserInfo.profile == null
      // You can check if the user is new or existing:
      // result.additionalUserInfo.isNewUser
    })
    .catch((error) => {
      // Some error occurred, you can inspect the code: error.code
      // Common errors could be invalid email and invalid or expired OTPs.
    });
}

إكمال عملية تسجيل الدخول في تطبيق على جهاز جوّال

يستخدم تطبيق Firebase Authentication خدمة Firebase Hosting لإرسال رابط الرسالة الإلكترونية إلى جهاز جوّال. لإكمال عملية تسجيل الدخول من خلال تطبيق الأجهزة الجوّالة، يجب ضبط التطبيق لرصد رابط التطبيق الوارد، وتحليل الرابط الأساسي لصفحة في التطبيق، ثم إكمال عملية تسجيل الدخول كما يتم ذلك من خلال مسار الويب.

لمزيد من المعلومات حول كيفية التعامل مع تسجيل الدخول باستخدام رابط البريد الإلكتروني في تطبيق Android، يُرجى الرجوع إلى دليل Android.

لمزيد من المعلومات حول كيفية التعامل مع تسجيل الدخول باستخدام رابط البريد الإلكتروني في تطبيق Apple، يُرجى الرجوع إلى دليل منصات Apple.

يمكنك أيضًا ربط طريقة المصادقة هذه بمستخدم حالي. على سبيل المثال، إذا سبق للمستخدم إثبات ملكية حسابه باستخدام خدمة أخرى، مثل رقم الهاتف، يمكنه إضافة طريقة تسجيل الدخول هذه إلى حسابه الحالي.

سيكون الاختلاف في النصف الثاني من العملية:

Web

import { getAuth, linkWithCredential, EmailAuthProvider } from "firebase/auth";

// Construct the email link credential from the current URL.
const credential = EmailAuthProvider.credentialWithLink(
  email, window.location.href);

// Link the credential to the current user.
const auth = getAuth();
linkWithCredential(auth.currentUser, credential)
  .then((usercred) => {
    // The provider is now successfully linked.
    // The phone user can now sign in with their phone number or email.
  })
  .catch((error) => {
    // Some error occurred.
  });

Web

// Construct the email link credential from the current URL.
var credential = firebase.auth.EmailAuthProvider.credentialWithLink(
  email, window.location.href);

// Link the credential to the current user.
firebase.auth().currentUser.linkWithCredential(credential)
  .then((usercred) => {
    // The provider is now successfully linked.
    // The phone user can now sign in with their phone number or email.
  })
  .catch((error) => {
    // Some error occurred.
  });

يمكن استخدامها أيضًا لإعادة مصادقة مستخدم رابط البريد الإلكتروني قبل تنفيذ عملية حساسة.

Web

import { getAuth, reauthenticateWithCredential, EmailAuthProvider } from "firebase/auth";

// Construct the email link credential from the current URL.
const credential = EmailAuthProvider.credentialWithLink(
  email, window.location.href);

// Re-authenticate the user with this credential.
const auth = getAuth();
reauthenticateWithCredential(auth.currentUser, credential)
  .then((usercred) => {
    // The user is now successfully re-authenticated and can execute sensitive
    // operations.
  })
  .catch((error) => {
    // Some error occurred.
  });

Web

// Construct the email link credential from the current URL.
var credential = firebase.auth.EmailAuthProvider.credentialWithLink(
  email, window.location.href);

// Re-authenticate the user with this credential.
firebase.auth().currentUser.reauthenticateWithCredential(credential)
  .then((usercred) => {
    // The user is now successfully re-authenticated and can execute sensitive
    // operations.
  })
  .catch((error) => {
    // Some error occurred.
  });

ومع ذلك، بما أنّ عملية الربط قد تنتهي على جهاز مختلف لم يسجّل فيه المستخدم الأصلي الدخول، قد لا يتم إكمال عملية الربط. في هذه الحالة، يمكن عرض رسالة خطأ للمستخدم لإجباره على فتح الرابط على الجهاز نفسه. يمكن تمرير بعض الحالات في الرابط لتوفير معلومات عن نوع العملية ومعرّف المستخدم.

إذا أنشأت مشروعك في 15 سبتمبر 2023 أو بعد هذا التاريخ، سيتم تفعيل ميزة الحماية من تعداد عناوين البريد الإلكتروني تلقائيًا. تعزّز هذه الميزة أمان حسابات المستخدمين في مشروعك، ولكنّها توقف fetchSignInMethodsForEmail()الطريقة التي كنّا ننصح بها سابقًا لتنفيذ مسارات المستخدِمين التي تتطلّب تقديم المعرّف أولاً.

على الرغم من إمكانية إيقاف ميزة الحماية من تعداد عناوين البريد الإلكتروني لمشروعك، لا ننصحك بذلك.

لمزيد من التفاصيل، يُرجى الاطّلاع على المستندات المتعلقة بحماية تعداد عناوين البريد الإلكتروني.

نموذج البريد الإلكتروني التلقائي لتسجيل الدخول باستخدام رابط

يتضمّن نموذج الرسالة الإلكترونية التلقائي طابعًا زمنيًا في الموضوع ونص الرسالة الإلكترونية حتى لا يتم تصغير الرسائل الإلكترونية اللاحقة إلى سلسلة محادثات واحدة، ما يؤدي إلى إخفاء الرابط.

ينطبق هذا النموذج على اللغات التالية:

الرمز اللغة
ar العربية
zh-CN الصينية (المبسطة)
zh-TW الصينية (التقليدية)
nl الهولندية
en الإنجليزية
en-GB الإنجليزية (المملكة المتحدة)
fr الفرنسية
de الألمانية
id الإندونيسية
it مأكولات إيطالية
ja اليابانية
ko الكورية
البولندية البولندية
pt-BR البرتغالية (البرازيل)
pt-PT البرتغالية (البرتغال)
الروسية الروسية
es الإسبانية
es-419 الإسبانية (أمريكا اللاتينية)
التايلاندية التايلاندية

الخطوات التالية

بعد أن يسجّل المستخدم الدخول للمرة الأولى، يتم إنشاء حساب مستخدم جديد وربطه ببيانات الاعتماد، أي اسم المستخدم وكلمة المرور أو رقم الهاتف أو معلومات مقدّم خدمة المصادقة التي سجّل المستخدم الدخول بها. يتم تخزين هذا الحساب الجديد كجزء من مشروع Firebase، ويمكن استخدامه لتحديد هوية المستخدم على مستوى كل تطبيق في مشروعك، بغض النظر عن طريقة تسجيل الدخول.

  • في تطبيقاتك، الطريقة المقترَحة لمعرفة حالة المصادقة للمستخدم هي ضبط مراقب على العنصر Auth. يمكنك بعد ذلك الحصول على معلومات الملف الشخصي الأساسية للمستخدم من الكائن User. راجِع مقالة إدارة المستخدمين.

  • في Firebase Realtime Database وCloud Storage قواعد الأمان، يمكنك الحصول على معرّف المستخدِم الفريد للمستخدِم الذي سجّل الدخول من المتغيّر auth، واستخدامه للتحكّم في البيانات التي يمكن للمستخدِم الوصول إليها.

يمكنك السماح للمستخدمين بتسجيل الدخول إلى تطبيقك باستخدام موفّري مصادقة متعدّدين من خلال ربط بيانات اعتماد موفّر المصادقة بحساب مستخدم حالي.

لتسجيل خروج مستخدم، اتّصِل بالرقم signOut:

Web

import { getAuth, signOut } from "firebase/auth";

const auth = getAuth();
signOut(auth).then(() => {
  // Sign-out successful.
}).catch((error) => {
  // An error happened.
});

Web

firebase.auth().signOut().then(() => {
  // Sign-out successful.
}).catch((error) => {
  // An error happened.
});