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

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

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

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

قبل البدء

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

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

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

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

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

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

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

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

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

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

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

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

    • iOSBundleID وandroidPackageName: يساعدان Firebase Authentication في تحديد ما إذا كان يجب إنشاء رابط مخصّص للويب فقط أو رابط للأجهزة الجوّالة يتم فتحه على جهاز Android أو Apple.
    • handleCodeInApp: اضبط القيمة على "صحيح". يجب دائمًا إكمال عملية تسجيل الدخول في التطبيق، على عكس الإجراءات الأخرى التي تتم خارج النطاق عبر البريد الإلكتروني (إعادة ضبط كلمة المرور وإثبات ملكية عنوان البريد الإلكتروني). ويرجع ذلك إلى أنّه من المتوقّع أن يكون المستخدم قد سجّل الدخول في نهاية عملية الربط، وأن يتم الاحتفاظ بحالة المصادقة ضمن التطبيق.
    • 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 Auth توفير عنوان البريد الإلكتروني للمستخدم عند إكمال عملية تسجيل الدخول. لكي تنجح عملية تسجيل الدخول، يجب أن يتطابق عنوان البريد الإلكتروني هذا مع العنوان الذي تم إرسال رابط تسجيل الدخول إليه في الأصل.

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

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

إكمال عملية تسجيل الدخول في تطبيق 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 من الخطوة السابقة إلى إمكانية النطاقات المرتبطة (Associated Domains). في حال استخدام النطاق التلقائي 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.
  }];

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

قبل إصدار Firebase Authentication الإصدار 11.8.0 من حزمة تطوير البرامج (SDK) لنظام التشغيل iOS، كانت ميزة تسجيل الدخول باستخدام رابط إلكتروني تعتمد على 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;
}

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