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

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

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

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

قبل البدء

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

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

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

  1. في وحدة تحكّم Firebase، افتح قسم المصادقة.
  2. في علامة التبويب طريقة تسجيل الدخول، فعِّل موفّر البريد الإلكتروني/كلمة المرور. ملاحظة يجب تفعيل تسجيل الدخول باستخدام البريد الإلكتروني وكلمة المرور لاستخدام تسجيل الدخول باستخدام رابط البريد الإلكتروني.
  3. في القسم نفسه، فعِّل طريقة تسجيل الدخول رابط إلكتروني (تسجيل الدخول بدون كلمة مرور).
  4. انقر على حفظ.

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

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

    • استبدِل url بالرابط لصفحة في التطبيق الذي تريد تضمينه وأي حالة إضافية تريد تمريرها. يجب إضافة نطاق الرابط إلى القائمة البيضاء في قائمة النطاقات المصرّح بها في "وحدة تحكّم Firebase"، ويمكنك العثور عليها من خلال الانتقال إلى علامة التبويب "طريقة تسجيل الدخول" (المصادقة -> طريقة تسجيل الدخول).
    • 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 Hosting من الخطوة السابقة إلى إذن "النطاقات المرتبطة" (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;
}

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