المصادقة في 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.12.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.5.1")    
}

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

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

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

    ملاحظة: إذا كنت تستخدم مكتبات متعددة من Firebase في تطبيقك، ننصحك بشدة باستخدام 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.1")
    
    // Also add the dependency for the Google Play services library and specify its version
    implementation("com.google.android.gms:play-services-auth:21.5.1")    
}

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

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

  1. في وحدة تحكّم FirebaseFirebase، افتح قسم المصادقة.
  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
    )
}

    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();

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

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

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

    Kotlin

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

    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.");
                }
            }
        });

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

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

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

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

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

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

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

ضبط Firebase Hosting

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

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

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

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

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

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

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

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

    إذا كنت تريد أن تتم إعادة توجيه هذه الروابط إلى نشاط معيّن، عليك ضبط intent filter في ملف AndroidManifest.xml. يجب أن يرصد فلتر الأهداف روابط البريد الإلكتروني لنطاقك. في 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)
            }
        }
}

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());
                    }
                }
            });
}

لمزيد من المعلومات عن كيفية التعامل مع تسجيل الدخول باستخدام رابط البريد الإلكتروني في تطبيق 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)
        }
    }

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());
                }
            }
        });

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

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)
        }
    }

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());
                }
            }
        });

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

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

لقد نشرنا حلاً بديلاً في Firebase Authentication Android SDK v23.2.0 والإصدارات الأحدث وFirebase BoM v33.9.0 والإصدارات الأحدث.

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

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

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

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

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

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

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

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

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

لتسجيل خروج مستخدم، استدعِ الدالة signOut:

Kotlin

Firebase.auth.signOut()

Java

FirebaseAuth.getInstance().signOut();