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

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

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

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

قبل البدء

إعداد مشروع Android

  1. أضِف Firebase إلى مشروع Android إذا لم يسبق لك إجراء ذلك.

  2. في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف الاعتمادية لمكتبة Firebase Authentication لنظام التشغيل Android. ننصحك باستخدام Firebase Android BoM للتحكّم في إصدارات المكتبة.

    بالإضافة إلى ذلك، كجزء من عملية إعداد Firebase Authentication، عليك إضافة حزمة تطوير البرامج (SDK) الخاصة بخدمات Google Play إلى تطبيقك.

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:34.0.0"))

    // Add the dependency for the Firebase Authentication library
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-auth")
    
    // Also add the dependency for the Google Play services library and specify its version
    implementation("com.google.android.gms:play-services-auth:21.3.0")    
}

    باستخدام Firebase Android BoM، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Firebase Android.

    (بديل)  أضِف تبعيات مكتبة Firebase بدون استخدام BoM

    إذا اخترت عدم استخدام Firebase BoM، عليك تحديد إصدار كل مكتبة من مكتبات Firebase في سطر التبعية الخاص بها.

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

    dependencies {
    // Add the dependency for the Firebase Authentication library
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-auth:24.0.0")
    
    // Also add the dependency for the Google Play services library and specify its version
    implementation("com.google.android.gms:play-services-auth:21.3.0")    
}

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

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

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

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

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

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

    Kotlin

    val actionCodeSettings = actionCodeSettings {
    // URL you want to redirect back to. The domain (www.example.com) for this
    // URL must be whitelisted in the Firebase Console.
    url = "https://www.example.com/finishSignUp?cartId=1234"
    // This must be true
    handleCodeInApp = true
    setIOSBundleId("com.example.ios")
    setAndroidPackageName(
        "com.example.android",
        true, // installIfNotAvailable
        "12", // minimumVersion
    )
}
    MainActivity.kt

    Java

    ActionCodeSettings actionCodeSettings =
        ActionCodeSettings.newBuilder()
                // URL you want to redirect back to. The domain (www.example.com) for this
                // URL must be whitelisted in the Firebase Console.
                .setUrl("https://www.example.com/finishSignUp?cartId=1234")
                // This must be true
                .setHandleCodeInApp(true)
                .setIOSBundleId("com.example.ios")
                .setAndroidPackageName(
                        "com.example.android",
                        true, /* installIfNotAvailable */
                        "12"    /* minimumVersion */)
                .build();
    MainActivity.java

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

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

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

    Kotlin

    Firebase.auth.sendSignInLinkToEmail(email, actionCodeSettings)
    .addOnCompleteListener { task ->
        if (task.isSuccessful) {
            Log.d(TAG, "Email sent.")
        }
    }
    MainActivity.kt

    Java

    FirebaseAuth auth = FirebaseAuth.getInstance();
auth.sendSignInLinkToEmail(email, actionCodeSettings)
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                if (task.isSuccessful()) {
                    Log.d(TAG, "Email sent.");
                }
            }
        });
    MainActivity.java

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

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

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

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

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

إكمال عملية تسجيل الدخول في تطبيق Android

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

ضبط Firebase Hosting

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

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

    في وحدة تحكّم Firebase، افتح قسم الاستضافة.

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

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

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

  2. إعداد تطبيقات Android:

    للتعامل مع هذه الروابط من تطبيق Android، يجب تحديد اسم حزمة تطبيقك في إعدادات مشروع Firebase على وحدة التحكّم. بالإضافة إلى ذلك، يجب تقديم خوارزميتَي SHA-1 وSHA-256 لشهادة التطبيق.

    إذا أردت أن تتم إعادة توجيه هذه الروابط إلى نشاط معيّن، عليك ضبط فلتر intent في ملف AndroidManifest.xml. يجب أن يرصد فلتر Intent روابط البريد الإلكتروني الخاصة بنطاقك. في AndroidManifest.xml:

    <intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.BROWSABLE" />
  <category android:name="android.intent.category.DEFAULT" />
  <data
    android:scheme="https"
    android:host="<PROJECT_ID>.firebaseapp.com or your custom domain"
    android:pathPrefix="/__/auth/links" />
</intent-filter>

    عندما يفتح المستخدمون رابط استضافة يتضمّن المسار /__/auth/links والمخطط والمضيف اللذين تحدّدهما، سيبدأ تطبيقك النشاط باستخدام فلتر الغرض هذا للتعامل مع الرابط.

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

Kotlin

val auth = Firebase.auth
val intent = intent
val emailLink = intent.data.toString()

// Confirm the link is a sign-in with email link.
if (auth.isSignInWithEmailLink(emailLink)) {
    // Retrieve this from wherever you stored it
    val email = "someemail@domain.com"

    // The client SDK will parse the code from the link for you.
    auth.signInWithEmailLink(email, emailLink)
        .addOnCompleteListener { task ->
            if (task.isSuccessful) {
                Log.d(TAG, "Successfully signed in with email link!")
                val result = task.result
                // You can access the new user via result.getUser()
                // Additional user info profile *not* available via:
                // result.getAdditionalUserInfo().getProfile() == null
                // You can check if the user is new or existing:
                // result.getAdditionalUserInfo().isNewUser()
            } else {
                Log.e(TAG, "Error signing in with email link", task.exception)
            }
        }
}
MainActivity.kt

Java

FirebaseAuth auth = FirebaseAuth.getInstance();
Intent intent = getIntent();
String emailLink = intent.getData().toString();

// Confirm the link is a sign-in with email link.
if (auth.isSignInWithEmailLink(emailLink)) {
    // Retrieve this from wherever you stored it
    String email = "someemail@domain.com";

    // The client SDK will parse the code from the link for you.
    auth.signInWithEmailLink(email, emailLink)
            .addOnCompleteListener(new OnCompleteListener<AuthResult>() {
                @Override
                public void onComplete(@NonNull Task<AuthResult> task) {
                    if (task.isSuccessful()) {
                        Log.d(TAG, "Successfully signed in with email link!");
                        AuthResult result = task.getResult();
                        // You can access the new user via result.getUser()
                        // Additional user info profile *not* available via:
                        // result.getAdditionalUserInfo().getProfile() == null
                        // You can check if the user is new or existing:
                        // result.getAdditionalUserInfo().isNewUser()
                    } else {
                        Log.e(TAG, "Error signing in with email link", task.getException());
                    }
                }
            });
}
MainActivity.java

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

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

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

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

Kotlin

// Construct the email link credential from the current URL.
val credential = EmailAuthProvider.getCredentialWithLink(email, emailLink)

// Link the credential to the current user.
Firebase.auth.currentUser!!.linkWithCredential(credential)
    .addOnCompleteListener { task ->
        if (task.isSuccessful) {
            Log.d(TAG, "Successfully linked emailLink credential!")
            val result = task.result
            // You can access the new user via result.getUser()
            // Additional user info profile *not* available via:
            // result.getAdditionalUserInfo().getProfile() == null
            // You can check if the user is new or existing:
            // result.getAdditionalUserInfo().isNewUser()
        } else {
            Log.e(TAG, "Error linking emailLink credential", task.exception)
        }
    }
MainActivity.kt

Java

// Construct the email link credential from the current URL.
AuthCredential credential =
        EmailAuthProvider.getCredentialWithLink(email, emailLink);

// Link the credential to the current user.
auth.getCurrentUser().linkWithCredential(credential)
        .addOnCompleteListener(new OnCompleteListener<AuthResult>() {
            @Override
            public void onComplete(@NonNull Task<AuthResult> task) {
                if (task.isSuccessful()) {
                    Log.d(TAG, "Successfully linked emailLink credential!");
                    AuthResult result = task.getResult();
                    // You can access the new user via result.getUser()
                    // Additional user info profile *not* available via:
                    // result.getAdditionalUserInfo().getProfile() == null
                    // You can check if the user is new or existing:
                    // result.getAdditionalUserInfo().isNewUser()
                } else {
                    Log.e(TAG, "Error linking emailLink credential", task.getException());
                }
            }
        });
MainActivity.java

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

Kotlin

// Construct the email link credential from the current URL.
val credential = EmailAuthProvider.getCredentialWithLink(email, emailLink)

// Re-authenticate the user with this credential.
Firebase.auth.currentUser!!.reauthenticateAndRetrieveData(credential)
    .addOnCompleteListener { task ->
        if (task.isSuccessful) {
            // User is now successfully reauthenticated
        } else {
            Log.e(TAG, "Error reauthenticating", task.exception)
        }
    }
MainActivity.kt

Java

// Construct the email link credential from the current URL.
AuthCredential credential =
        EmailAuthProvider.getCredentialWithLink(email, emailLink);

// Re-authenticate the user with this credential.
auth.getCurrentUser().reauthenticateAndRetrieveData(credential)
        .addOnCompleteListener(new OnCompleteListener<AuthResult>() {
            @Override
            public void onComplete(@NonNull Task<AuthResult> task) {
                if (task.isSuccessful()) {
                    // User is now successfully reauthenticated
                } else {
                    Log.e(TAG, "Error reauthenticating", task.getException());
                }
            }
        });
MainActivity.java

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

كانت مصادقة رابط البريد الإلكتروني تعتمد سابقًا على Firebase Dynamic Links، وسيتم إيقافها نهائيًا في 25 أغسطس 2025.

لقد نشرنا حلاً بديلاً في الإصدار 23.2.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لنظام التشغيل Android ‏(Firebase Authentication) والإصدار 33.9.0 أو إصدار أحدث من Firebase BoM.

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

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

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

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

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

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

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

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

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

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

Kotlin

Firebase.auth.signOut()
MainActivity.kt

Java

FirebaseAuth.getInstance().signOut();
MainActivity.java