المصادقة مع Firebase باستخدام رابط البريد الإلكتروني على أنظمة Apple الأساسية

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

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

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

قبل البدء

استخدِم Swift Package Manager لتثبيت تبعيات Firebase وإدارتها.

  1. في Xcode، افتح مشروع تطبيقك، ثم انتقِل إلى ملف > إضافة حِزم (File > Add Packages).
  2. عندما يُطلب منك ذلك، أضِف مستودع حزمة تطوير البرامج (SDK) لمنصات Apple في Firebase:
  3.   https://github.com/firebase/firebase-ios-sdk.git
  4. اختَر مكتبة "Firebase Authentication".
  5. أضِف العلامة -ObjC إلى قسم علامات الربط الأخرى (Other Linker Flags) في إعدادات الإنشاء المستهدَفة.
  6. بعد الانتهاء، سيبدأ Xcode تلقائيًا في حلّ التبعيات وتنزيلها في الخلفية.

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

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

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

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

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

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

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

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

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

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

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

    Swift

    let actionCodeSettings = ActionCodeSettings()
    actionCodeSettings.url = URL(string: "https://www.example.com")
    // The sign-in operation has to always be completed in the app.
    actionCodeSettings.handleCodeInApp = true
    actionCodeSettings.setIOSBundleID(Bundle.main.bundleIdentifier!)
    actionCodeSettings.setAndroidPackageName("com.example.android",
                                             installIfNotAvailable: false, minimumVersion: "12")

    Objective-C

    FIRActionCodeSettings *actionCodeSettings = [[FIRActionCodeSettings alloc] init];
    [actionCodeSettings setURL:[NSURL URLWithString:@"https://www.example.com"]];
    // The sign-in operation has to always be completed in the app.
    actionCodeSettings.handleCodeInApp = YES;
    [actionCodeSettings setIOSBundleID:[[NSBundle mainBundle] bundleIdentifier]];
    [actionCodeSettings setAndroidPackageName:@"com.example.android"
                        installIfNotAvailable:NO
                               minimumVersion:@"12"];

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

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

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

    Swift

    Auth.auth().sendSignInLink(toEmail: email,
                               actionCodeSettings: actionCodeSettings) { error in
      // ...
        if let error = error {
          self.showMessagePrompt(error.localizedDescription)
          return
        }
        // 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.
        UserDefaults.standard.set(email, forKey: "Email")
        self.showMessagePrompt("Check your email for link")
        // ...
    }

    Objective-C

    [[FIRAuth auth] sendSignInLinkToEmail:email
                       actionCodeSettings:actionCodeSettings
                               completion:^(NSError *_Nullable error) {
      // ...
        if (error) {
          [self showMessagePrompt:error.localizedDescription];
           return;
        }
        // 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.
        [NSUserDefaults.standardUserDefaults setObject:email forKey:@"Email"];
        [self showMessagePrompt:@"Check your email for link"];
        // ...
    }];

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

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

يمكنك تبسيط هذا الإجراء للمستخدمين الذين يفتحون رابط تسجيل الدخول على الجهاز نفسه الذي يطلبون الرابط منه، وذلك من خلال تخزين عنوان بريدهم الإلكتروني محليًا عند إرسال رسالة تسجيل الدخول الإلكترونية. بعد ذلك، استخدِم هذا العنوان لإكمال العملية.

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

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

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

ضبط "Firebase Hosting"

يستخدم Firebase Authentication نطاقات Firebase Hosting عند إنشاء رابط وإرساله لفتحه في تطبيق للأجهزة الجوّالة. سبق أن تم إعداد نطاق Firebase Hosting تلقائي لك.

  1. ضبط نطاقات Firebase Hosting:

    في وحدة تحكّم Firebase، انتقِل إلى الاستضافة والحوسبة بدون خادم > الاستضافة.

    • إذا أردت استخدام النطاق التلقائي لرابط البريد الإلكتروني الذي يتم فتحه في تطبيقات الأجهزة الجوّالة، انتقِل إلى موقعك الإلكتروني التلقائي واطّلِع على نطاق Hosting التلقائي. عادةً ما يظهر نطاق Hosting التلقائي على النحو التالي: PROJECT_ID.firebaseapp.com.

      ستحتاج إلى هذه القيمة عند ضبط تطبيقك لاعتراض الرابط الوارد.

    • إذا أردت استخدام نطاق خاص لرابط البريد الإلكتروني، يمكنك تسجيل نطاق من خلال "Firebase Hosting" واستخدامه كنطاق للرابط.

  2. ضبط تطبيقات Apple:

    عليك ضبط النطاق الذي اخترته على أنّه نطاق مرتبط لروابط التطبيقات. لإعداد الاستحقاق في تطبيقك، افتح علامة التبويب Signing & Capabilities (التوقيع والإمكانات) الخاصة بالهدف في Xcode وأضِف نطاقات "استضافة Firebase" من الخطوة السابقة إلى إمكانية "النطاقات المرتبطة". في حال استخدام نطاق Firebase Hosting التلقائي، سيكون هذا النطاق applinks:PROJECT_ID.firebaseapp.com.

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

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

Swift

if Auth.auth().isSignIn(withEmailLink: link) {
        Auth.auth().signIn(withEmail: email, link: self.link) { user, error in
          // ...
        }
}

Objective-C

if ([[FIRAuth auth] isSignInWithEmailLink:link]) {
    [[FIRAuth auth] signInWithEmail:email
                               link:link
                         completion:^(FIRAuthDataResult * _Nullable authResult, NSError * _Nullable error) {
      // ...
    }];
}

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

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

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

سيكون الفرق في النصف الثاني من العملية:

Swift

  let credential = EmailAuthCredential.credential(withEmail:email
                                                       link:link)
  Auth.auth().currentUser?.link(with: credential) { authData, error in
    if (error) {
      // And error occurred during linking.
      return
    }
    // The provider was successfully linked.
    // The phone user can now sign in with their phone number or email.
  }

Objective-C

  FIRAuthCredential *credential =
      [FIREmailAuthProvider credentialWithEmail:email link:link];
  [FIRAuth auth].currentUser
      linkWithCredential:credential
              completion:^(FIRAuthDataResult *_Nullable result,
                           NSError *_Nullable error) {
    if (error) {
      // And error occurred during linking.
      return;
    }
    // The provider was successfully linked.
    // The phone user can now sign in with their phone number or email.
  }];

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

Swift

  let credential = EmailAuthProvider.credential(withEmail:email
                                                       link:link)
  Auth.auth().currentUser?.reauthenticate(with: credential) { authData, error in
    if (error) {
      // And error occurred during re-authentication.
      return
    }
    // The user was successfully re-authenticated.
  }

Objective-C

  FIRAuthCredential *credential =
      [FIREmailAuthCredential credentialWithEmail:email link:link];
  [FIRAuth auth].currentUser
      reauthenticateWithCredential:credential
                        completion:^(FIRAuthDataResult *_Nullable result,
                                     NSError *_Nullable error) {
    if (error) {
      // And error occurred during re-authentication
      return;
    }
    // The user was successfully re-authenticated.
  }];

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

قبل الإصدار 11.8.0 من حزمة تطوير البرامج (SDK) لنظام التشغيل iOS من Firebase Authentication، كانت ميزة تسجيل الدخول عبر رابط البريد الإلكتروني تعتمد على Firebase Dynamic Links لفتح روابط تسجيل الدخول في التطبيق الصحيح. تم إيقاف روابط إثبات الهوية هذه نهائيًا، لأنّ Firebase Dynamic Links سيتم إيقافه نهائيًا في 25 أغسطس 2025.

إذا كان تطبيقك يستخدم الروابط ذات النمط القديم، عليك نقل تطبيقك إلى النظام الجديد المستند إلى Firebase Hosting.

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

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

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

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

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

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

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

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

لتسجيل خروج مستخدم، يمكنك استدعاء signOut:.

Swift

let firebaseAuth = Auth.auth()
do {
  try firebaseAuth.signOut()
} catch let signOutError as NSError {
  print("Error signing out: %@", signOutError)
}

Objective-C

NSError *signOutError;
BOOL status = [[FIRAuth auth] signOut:&signOutError];
if (!status) {
  NSLog(@"Error signing out: %@", signOutError);
  return;
}

قد تحتاج أيضًا إلى إضافة رمز معالجة الأخطاء لمجموعة كاملة من أخطاء المصادقة. يُرجى الاطّلاع على معالجة الأخطاء.