المصادقة مع Firebase باستخدام رقم هاتف باستخدام JavaScript

bookmark_border تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

يمكنك استخدام Firebase Authentication لتسجيل دخول مستخدم من خلال إرسال رسالة SMS إلى هاتف المستخدم. يسجّل المستخدم الدخول باستخدام رمز صالح لمرة واحدة مضمّن في رسالة SMS.

إنّ أسهل طريقة لإضافة ميزة تسجيل الدخول باستخدام رقم الهاتف إلى تطبيقك هي استخدام FirebaseUI، الذي يتضمّن تطبيقًا مصغّرًا لتسجيل الدخول يمكن إضافته بسهولة إلى التطبيق وينفّذ عمليات تسجيل الدخول باستخدام رقم الهاتف، بالإضافة إلى تسجيل الدخول المستنِد إلى كلمة المرور وتسجيل الدخول المُفعَّل على مستوى المؤسسة. يصف هذا المستند كيفية تنفيذ مسار تسجيل الدخول باستخدام رقم الهاتف باستخدام حزمة تطوير البرامج (SDK) لمنصّة Firebase.

قبل البدء

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

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

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

تفعيل ميزة "تسجيل الدخول باستخدام رقم الهاتف" لمشروعك على Firebase

لتسجيل دخول المستخدمين من خلال الرسائل القصيرة، عليك أولاً تفعيل أسلوب تسجيل الدخول باستخدام رقم الهاتف لمشروعك على Firebase:

1. في وحدة تحكّم Firebase، افتح قسم المصادقة.
2. في صفحة طريقة تسجيل الدخول، فعِّل طريقة تسجيل الدخول رقم الهاتف.
3. في الصفحة نفسها، إذا لم يكن النطاق الذي سيستضيف تطبيقك مُدرَجًا في القسم نطاقات إعادة التوجيه عبر OAuth، أضِف نطاقك. يُرجى العلم أنّه لا يُسمح باستخدام localhost كناطاق مُستضاف لأغراض المصادقة عبر الهاتف.

إعداد أداة التحقّق من reCAPTCHA

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

لست بحاجة إلى إعداد عملاء reCAPTCHA يدويًا. عند استخدام RecaptchaVerifier في حزمة تطوير البرامج (SDK) لمنصّة Firebase، تنشئ Firebase تلقائيًا أي مفاتيح وسرّات عملاء ضرورية وتتعامل معها.

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

يمكن ترجمة اختبار reCAPTCHA المعروض الأساسي وفقًا لتفضيل المستخدم من خلال تعديل رمز اللغة في مثيل Auth قبل عرض اختبار reCAPTCHA. سينطبق أيضًا الإجراء المذكور أعلاه المتعلّق بالترجمة والنشر على الرسالة القصيرة المُرسَلة إلى المستخدم والتي تحتوي على رمز التحقّق.

import { getAuth } from "firebase/auth";

const auth = getAuth();
auth.languageCode = 'it';
// To apply the default browser preference instead of explicitly setting it.
// auth.useDeviceLanguage();
auth_set_language_code.js

firebase.auth().languageCode = 'it';
// To apply the default browser preference instead of explicitly setting it.
// firebase.auth().useDeviceLanguage();
index.js

استخدام شارة reCAPTCHA غير المرئية

لاستخدام اختبار reCAPTCHA غير المرئي، أنشئ عنصرًا من النوع RecaptchaVerifier مع ضبط المَعلمة size على invisible، مع تحديد معرّف الزر الذي يُرسِل نموذج تسجيل الدخول. على سبيل المثال:

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

const auth = getAuth();
window.recaptchaVerifier = new RecaptchaVerifier(auth, 'sign-in-button', {
  'size': 'invisible',
  'callback': (response) => {
    // reCAPTCHA solved, allow signInWithPhoneNumber.
    onSignInSubmit();
  }
});
auth_phone_recaptcha_verifier_invisible.js

window.recaptchaVerifier = new firebase.auth.RecaptchaVerifier('sign-in-button', {
  'size': 'invisible',
  'callback': (response) => {
    // reCAPTCHA solved, allow signInWithPhoneNumber.
    onSignInSubmit();
  }
});
phone-auth.js

استخدام التطبيق المصغّر reCAPTCHA

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

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

const auth = getAuth();
window.recaptchaVerifier = new RecaptchaVerifier(auth, 'recaptcha-container', {});
auth_phone_recaptcha_verifier_simple.js

window.recaptchaVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container');
phone-auth.js

اختياري: تحديد مَعلمات reCAPTCHA

يمكنك اختياريًا ضبط دوالّ الاستدعاء في عنصر RecaptchaVerifier التي يتمّ استدعاؤها عندما يحلّ المستخدم اختبار reCAPTCHA أو تنتهي صلاحية reCAPTCHA قبل أن يُرسِل المستخدم النموذج:

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

const auth = getAuth();
window.recaptchaVerifier = new RecaptchaVerifier(auth, 'recaptcha-container', {
  'size': 'normal',
  'callback': (response) => {
    // reCAPTCHA solved, allow signInWithPhoneNumber.
    // ...
  },
  'expired-callback': () => {
    // Response expired. Ask user to solve reCAPTCHA again.
    // ...
  }
});
auth_phone_recaptcha_verifier_visible.js

window.recaptchaVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container', {
  'size': 'normal',
  'callback': (response) => {
    // reCAPTCHA solved, allow signInWithPhoneNumber.
    // ...
  },
  'expired-callback': () => {
    // Response expired. Ask user to solve reCAPTCHA again.
    // ...
  }
});
phone-auth.js

اختياري: معالجة reCAPTCHA مسبقًا

إذا أردت عرض reCAPTCHA مسبقًا قبل إرسال طلب تسجيل الدخول، يُرجى الاتصال بالرقم render:

recaptchaVerifier.render().then((widgetId) => {
  window.recaptchaWidgetId = widgetId;
});
auth_phone_recaptcha_render.js

recaptchaVerifier.render().then((widgetId) => {
  window.recaptchaWidgetId = widgetId;
});
phone-auth.js

بعد حلّ render، ستحصل على معرّف التطبيق المصغّر لـ reCAPTCHA، والذي يمكنك استخدامه لإجراء طلبات إلى واجهة برمجة التطبيقات reCAPTCHA:

const recaptchaResponse = grecaptcha.getResponse(recaptchaWidgetId);
auth_get_recaptcha_response.js

const recaptchaResponse = grecaptcha.getResponse(recaptchaWidgetId);
phone-auth.js

إرسال رمز إثبات ملكية إلى هاتف المستخدم

لبدء عملية تسجيل الدخول باستخدام رقم الهاتف، عليك عرض واجهة على المستخدم تطلب منه تقديم رقم هاتفه، ثم الاتصال بالرقم signInWithPhoneNumber لطلب أن ترسل Firebase رمز مصادقة إلى هاتف المستخدم عبر رسالة قصيرة SMS:

1. الحصول على رقم هاتف المستخدم

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

2. اتصل بـ signInWithPhoneNumber، مع إدخال رقم هاتف user وRecaptchaVerifier الذي أنشأته سابقًا.
   WebWeb
   import { getAuth, signInWithPhoneNumber } from "firebase/auth";
   
   const phoneNumber = getPhoneNumberFromUserInput();
   const appVerifier = window.recaptchaVerifier;
   
   const auth = getAuth();
   signInWithPhoneNumber(auth, phoneNumber, appVerifier)
       .then((confirmationResult) => {
         // SMS sent. Prompt user to type the code from the message, then sign the
         // user in with confirmationResult.confirm(code).
         window.confirmationResult = confirmationResult;
         // ...
       }).catch((error) => {
         // Error; SMS not sent
         // ...
       });
   auth_phone_signin.js

   const phoneNumber = getPhoneNumberFromUserInput();
   const appVerifier = window.recaptchaVerifier;
   firebase.auth().signInWithPhoneNumber(phoneNumber, appVerifier)
       .then((confirmationResult) => {
         // SMS sent. Prompt user to type the code from the message, then sign the
         // user in with confirmationResult.confirm(code).
         window.confirmationResult = confirmationResult;
         // ...
       }).catch((error) => {
         // Error; SMS not sent
         // ...
       });
   phone-auth.js

   إذا أدّى signInWithPhoneNumber إلى حدوث خطأ، أعِد ضبط reCAPTCHA ليتمكّن المستخدم من إعادة المحاولة:

   grecaptcha.reset(window.recaptchaWidgetId);
   
   // Or, if you haven't stored the widget ID:
   window.recaptchaVerifier.render().then(function(widgetId) {
     grecaptcha.reset(widgetId);
   });

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

تسجيل دخول المستخدم باستخدام رمز إثبات الهوية

بعد نجاح المكالمة إلى signInWithPhoneNumber، اطلب من العميل كتابة رمز التحقّق الذي تلقّاه عبر رسالة SMS. بعد ذلك، سجِّل دخول المستخدم من خلال تمرير الرمز إلى طريقة confirm لعنصر ConfirmationResult الذي تم تمريره إلى معالج الامتثال لمحاولة signInWithPhoneNumber (أي العنصر then). على سبيل المثال:

const code = getCodeFromUserInput();
confirmationResult.confirm(code).then((result) => {
  // User signed in successfully.
  const user = result.user;
  // ...
}).catch((error) => {
  // User couldn't sign in (bad verification code?)
  // ...
});
auth_phone_verify_code.js

const code = getCodeFromUserInput();
confirmationResult.confirm(code).then((result) => {
  // User signed in successfully.
  const user = result.user;
  // ...
}).catch((error) => {
  // User couldn't sign in (bad verification code?)
  // ...
});
phone-auth.js

إذا نجحت المكالمة إلى confirm، يتم تسجيل دخول المستخدم بنجاح.

الحصول على عنصر AuthCredential الوسيط

إذا كنت بحاجة إلى الحصول على عنصر AuthCredential لحساب المستخدم، عليك تمرير رمز التحقّق من نتيجة التأكيد ورمز التحقّق إلى PhoneAuthProvider.credential بدلاً من استدعاء confirm:

var credential = firebase.auth.PhoneAuthProvider.credential(confirmationResult.verificationId, code);

بعد ذلك، يمكنك تسجيل دخول المستخدم باستخدام بيانات الاعتماد:

firebase.auth().signInWithCredential(credential);

إجراء الاختبار باستخدام أرقام هواتف خيالية

يمكنك إعداد أرقام هواتف خيالية لاستخدامها في مرحلة التطوير من خلال وحدة تحكّم Firebase. يوفّر الاختبار باستخدام أرقام هواتف خيالية المزايا التالية:

• يمكنك اختبار مصادقة رقم الهاتف بدون استهلاك حصة الاستخدام.
• يمكنك اختبار مصادقة رقم الهاتف بدون إرسال رسالة SMS فعلية.
• إجراء اختبارات متتالية باستخدام رقم الهاتف نفسه بدون تقييد السرعة يقلل ذلك من خطر الرفض أثناء عملية المراجعة في متجر التطبيقات إذا صادف أن استخدم المُراجع رقم الهاتف نفسه للاختبار.
• إجراء الاختبارات بسهولة في بيئات التطوير بدون أي جهد إضافي، مثل إمكانية التطوير في محاكي iOS أو محاكي Android بدون "خدمات Google Play"
• كتابة اختبارات الدمج بدون أن يتم حظرها من خلال عمليات التحقّق من الأمان التي يتم تطبيقها عادةً على أرقام الهواتف الحقيقية في بيئة الإنتاج

يجب أن تستوفي أرقام الهواتف الخيالية المتطلبات التالية:

1. تأكَّد من استخدام أرقام هواتف خيالية وغير متوفّرة. لا تسمح لك Firebase Authentication بضبط أرقام هواتف حالية يستخدمها مستخدمون حقيقيون كأرقام اختبارية. أحد الخيارات هو استخدام الأرقام التي تبدأ بالبادئة 555 كأرقام هواتف تجريبية في الولايات المتحدة، على سبيل المثال: +1 650-555-3434
2. يجب تنسيق أرقام الهواتف بشكل صحيح وفقًا للطول والقيود الأخرى. وسيخضع هذا الرقم لعملية التحقّق نفسها التي يخضع لها رقم هاتف المستخدم الحقيقي.
3. يمكنك إضافة ما يصل إلى 10 أرقام هواتف لاستخدامها في مرحلة التطوير.
4. استخدِم أرقام هواتف أو رموز اختبارية يصعب تخمينها وغيِّرها بشكل متكرر.

إنشاء أرقام هواتف ورموز إثبات ملكية خيالية

1. في وحدة تحكّم Firebase، افتح قسم المصادقة.
2. في علامة التبويب طريقة تسجيل الدخول، فعِّل مزوّد خدمة الهاتف إذا لم يسبق لك ذلك.
3. افتح قائمة أرقام الهواتف للاختبار.
4. أدخِل رقم الهاتف الذي تريد اختباره، على سبيل المثال: ‎+1 650-555-3434.
5. أدخِل رمز التحقّق المكوّن من 6 أرقام لهذا الرقم المحدّد، على سبيل المثال: 654321.
6. أضِف الرقم. إذا لزم الأمر، يمكنك حذف رقم الهاتف ورمزه من خلال التمرير فوق الصف المقابل والنقر على رمز المهملات.

الاختبار اليدوي

يمكنك بدء استخدام رقم هاتف خيالي في تطبيقك مباشرةً. يتيح لك ذلك إجراء الاختبار اليدوي أثناء مراحل التطوير بدون مواجهة مشاكل الحصة أو الحدّ من السرعة. يمكنك أيضًا إجراء الاختبار مباشرةً من محاكي iOS أو محاكي Android بدون تثبيت "خدمات Google Play".

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

عند اكتمال عملية تسجيل الدخول، يتم إنشاء مستخدم على Firebase باستخدام رقم الهاتف هذا. يمتلك المستخدم السلوك والسمات نفسها التي يمتلكها مستخدم رقم هاتف حقيقي، ويمكنه الوصول إلى Realtime Database/Cloud Firestore والخدمات الأخرى بالطريقة نفسها. يحتوي رمز التعريف الذي تم إنشاؤه أثناء هذه العملية على التوقيع نفسه المستخدَم في رمز تعريف المستخدم الذي لديه رقم هاتف حقيقي.

هناك خيار آخر وهو ضبط دور اختبار من خلال مطالبات مخصّصة لهؤلاء المستخدمين لتمييزهم كمستخدمين مزيّفين إذا كنت تريد فرض المزيد من القيود على الوصول.

اختبار الدمج

بالإضافة إلى الاختبار اليدوي، يوفّر Firebase Authentication واجهات برمجة تطبيقات للمساعدة في كتابة اختبارات الدمج لاختبار المصادقة عبر الهاتف. تعمل واجهات برمجة التطبيقات هذه على إيقاف عملية إثبات ملكية التطبيق من خلال إيقاف شرط reCAPTCHA في الويب والإشعارات الفورية الصامتة في iOS. ويجعل ذلك اختبار التشغيل الآلي ممكنًا في هذه المسارات وأسهل في التنفيذ. بالإضافة إلى ذلك، تساعد هذه الأدوات في توفير إمكانية اختبار عمليات التحقق الفوري على Android.

على الويب، اضبط appVerificationDisabledForTesting على true قبل عرض firebase.auth.RecaptchaVerifier. يؤدي ذلك إلى حلّ reCAPTCHA تلقائيًا، ما يتيح لك إدخال رقم الهاتف بدون حلّه يدويًا. يُرجى العلم أنّه حتى إذا كانت ميزة reCAPTCHA غير مفعّلة، سيظل استخدام رقم هاتف غير خيالي غير مجدٍ في إكمال عملية تسجيل الدخول. لا يمكن استخدام سوى أرقام الهواتف الخيالية مع واجهة برمجة التطبيقات هذه.

// Turn off phone auth app verification.
firebase.auth().settings.appVerificationDisabledForTesting = true;

var phoneNumber = "+16505554567";
var testVerificationCode = "123456";

// This will render a fake reCAPTCHA as appVerificationDisabledForTesting is true.
// This will resolve after rendering without app verification.
var appVerifier = new firebase.auth.RecaptchaVerifier('recaptcha-container');
// signInWithPhoneNumber will call appVerifier.verify() which will resolve with a fake
// reCAPTCHA response.
firebase.auth().signInWithPhoneNumber(phoneNumber, appVerifier)
    .then(function (confirmationResult) {
      // confirmationResult can resolve with the fictional testVerificationCode above.
      return confirmationResult.confirm(testVerificationCode)
    }).catch(function (error) {
      // Error; SMS not sent
      // ...
    });

يختلف سلوك مدقّقي التطبيقات وهميّي reCAPTCHA المرئيين وغير المرئيين عند إيقاف ميزة "التحقّق من التطبيقات":

• اختبار reCAPTCHA المرئي: عند عرض اختبار reCAPTCHA المرئي من خلال appVerifier.render()، يتم حلّه تلقائيًا بعد ثوانٍ معدودة من التأخير. ويعادل ذلك نقر المستخدم على reCAPTCHA فور ظهوره. ستنتهي صلاحية ردّ reCAPTCHA بعد بعض الوقت، ثم سيتم حلّه تلقائيًا مرة أخرى.
• Invisible reCAPTCHA: لا يتم حلّ reCAPTCHA غير المرئية تلقائيًا عند العرض، بل يتم حلّها عند appVerifier.verify()الطلب أو عند النقر على رابط زر reCAPTCHA بعد جزء من الثانية من التأخير. وبالمثل، ستنتهي صلاحية الاستجابة بعد مرور بعض الوقت، ولن يتم حلّها تلقائيًا إلا بعد طلب appVerifier.verify() أو عند النقر على رابط زر reCAPTCHA مرة أخرى.

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

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

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

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

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

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

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

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

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

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