إضافة المصادقة المتعدّدة العوامل (TOTP) إلى تطبيق Android

إذا تمت الترقية إلى مصادقة Firebase باستخدام "نظام أساسي للهوية"، يمكنك إضافة كلمة مرور صالحة لمرة واحدة مصادقة متعدّدة العوامل (MFA) على تطبيقك باستخدام TOTP

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

قبل البدء

  1. يجب تفعيل مقدِّم خدمة واحد على الأقل يتوافق مع المواقع المصممة بغرض الإعلانات (MFA). يُرجى العِلم أنّ جميع مقدّمي الخدمات باستثناء المواقع المصممة بغرض الإعلانات والتي تتوافق مع المواقع المصممة لعرض الإعلانات (MFA):

    • المصادقة عبر الهاتف
    • مصادقة مجهولة
    • الرموز المميّزة المخصّصة للمصادقة
    • مركز ألعاب Apple

  2. تأكَّد من أنّ تطبيقك يتحقّق من عناوين البريد الإلكتروني للمس��خدمين. تتطلب MFA توفر عنوان بريد إلكتروني التحقق. يؤدي هذا الإجراء إلى منع الجهات الضارّة من التسجيل في إحدى الخدمات. بعنوان بريد إلكتروني لا يملكونه، ثم حجب عناوين البريد الإلكتروني مالك عنوان البريد الإلكتروني بإضافة عامل ثانٍ.

  3. ثبِّت حزمة تطوير البرامج (SDK) لنظام التشغيل Android لمنصة Firebase

    لا تتوفّر شهادة TOTP MFA إلا على الإصدار 22.1.0 من حزمة تطوير البرامج (SDK) لنظام التشغيل Android وأعلى.

تفعيل TOTP MFA

لتفعيل TOTP كعامل ثانٍ، استخدم SDK للمشرف أو اتصل بالمشروع نقطة نهاية REST الخاصة بالتهيئة.

لاستخدام حزمة تطوير البرامج (SDK) الخاصة بالمشرف، يمكنك اتّباع الخطوات التالية:

  1. ثبِّت حزمة تطوير برامج Node.js لمشرف Firebase.

    لا يتوافق TOTP MFA إلّا مع الإصدار 11.6.0 والإصدار 11.6.0 من حزمة تطوير البرامج (SDK) لمشرف Firebase. أعلاه.

  2. قم بتشغيل ما يلي:

    import { getAuth } from 'firebase-admin/auth';

getAuth().projectConfigManager().updateProjectConfig(
{
      multiFactorConfig: {
          providerConfigs: [{
              state: "ENABLED",
              totpProviderConfig: {
                  adjacentIntervals: NUM_ADJ_INTERVALS
              }
          }]
      }
})

    استبدِل ما يلي:

    • NUM_ADJ_INTERVALS: عدد العناصر المجاورة الفواصل الزمنية التي يتم قبول بروتوكولات TOTP منها، من صفر إلى عشرة. تشير رسالة الأشكال البيانية الافتراضي هو خمسة.

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

لتمكين TOTP MFA باستخدام واجهة برمجة تطبيقات REST، قم بتشغيل ما يلي:

curl -X PATCH "https://identitytoolkit.googleapis.com/admin/v2/projects/PROJECT_ID/config?updateMask=mfa" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    -d \
    '{
        "mfa": {
          "providerConfigs": [{
            "state": "ENABLED",
            "totpProviderConfig": {
              "adjacentIntervals": NUM_ADJ_INTERVALS
            }
          }]
       }
    }'

استبدِل ما يلي:

  • PROJECT_ID: رقم تعريف المشروع

  • NUM_ADJ_INTERVALS: عدد الإطار الزمني المسافات، من صفر إلى عشرة. والإعداد الافتراضي هو خمسة.

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

اختيار نقش التسجيل

يمكنك اختيار ما إذا كان تطبيقك يتطلب مصادقة متعدّدة العوامل، وكيفية ووقت تسجيل المستخدمين. وتشمل بعض الأنماط الشائعة ما يلي:

  • سجِّل العامل الثاني للمستخدم كجزء من عملية التسجيل. استخدام هذه المسودة إذا كان تطبيقك يتطلب مصادقة متعددة العوامل لجميع المستخدمين.

  • عليك توفير خيار قابل للتخطّي لتسجيل عامل ثانٍ أث��ا�� ��ل��سجيل. إذا كنت فإنك تريد تشجيع إجراء مصادقة متعددة العوامل لتطبيقك ولكن لا تشترطه التي قد تستخدم هذا النهج.

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

  • طلب إضافة عامل ثانٍ بشكل تدريجي عندما يريد المستخدم الوصول مع متطلبات أمان أعلى.

تسجيل المستخدمين في TOTP MFA

بعد تفعيل TOTP MFA كعامل ثانٍ لتطبيقك، يمكنك تنفيذه من جهة العميل. تسجيل المستخدمين في TOTP MFA:

  1. أعِد مصادقة المستخدم.

  2. إنشاء مفتاح TOTP سرّي للمستخدم الذي تمت مصادقته:

    // Generate a TOTP secret.
Firebase.auth.currentUser.multiFactor.session
    .addOnSuccessListener { multiFactorSession ->
        TotpMultiFactorGenerator.generateSecret(multiFactorSession)
            .addOnSuccessListener { totpSecret ->
                // Display the secret to the user and prompt them to
                // enter it into their authenticator app. (See the next
                // step.)
            }
    }

  3. يعرض المفتاح السري للمستخدم واطلب منه إدخاله في تطبيق المصادقة:

    // Display this key:
val secret = totpSecret.sharedSecretKey

    بالإضافة إلى عرض المفتاح السري، يمكنك محاولة أضِفه إلى تطبيق المصادقة التلقائي على الجهاز. لإجراء ذلك، أنشئ مخططًا معرّف الموارد المنتظم (URI) لمفتاح متوافق مع Google Authenticator، وتمريره إلى openInOtpApp():

    val qrCodeUri = totpSecret.generateQrCodeUrl(
    currentUser.email ?: "default account",
    "Your App Name")
totpSecret.openInOtpApp(qrCodeUri)

    بعد أن يضيف المستخدم الرمز السرّي إلى تطبيق المصادقة الخاص به، سيبدأ إنشاء قوائم تشغيل (TOTP).

  4. الطلب من المستخدم كتابة "بروتوكول النقل العام" (TOTP) الذي يعرضه تطبيق المصادقة استخدامه لإنهاء عملية التسجيل في المواقع المصممة بغرض الإعلانات (MFA):

    // Ask the user for a verification code from the authenticator app.
val verificationCode = // Code from user input.

// Finalize the enrollment.
val multiFactorAssertion = TotpMultiFactorGenerator
    .getAssertionForEnrollment(totpSecret, verificationCode)
Firebase.auth.currentUser.multiFactor.enroll(multiFactorAssertion, "TOTP")
    .addOnSuccessListener {
        // Enrollment complete.
    }

تسجيل دخول المستخدمين بعامل ثانٍ

لتسجيل دخول المستخدمين من خلال TOTP MFA، استخدِم الرمز التالي:

  1. يمكنك استدعاء إحدى الطريقتين (signInWith) كما تفعل في حال عدم استخدام المواقع المصممة بغرض الإعلانات (MFA). (على سبيل المثال، signInWithEmailAndPassword().) إذا طرحت الطريقة الرمز FirebaseAuthMultiFactorException، يمكنك بدء مسار MFA الخاص بتطبيقك.

    Firebase.auth.signInWithEmailAndPassword(email, password)
    .addOnSuccessListener { result ->
        // If the user is not enrolled with a second factor and provided valid
        // credentials, sign-in succeeds.

        // (If your app requires MFA, this could be considered an error
        // condition, which you would resolve by forcing the user to enroll a
        // second factor.)

        // ...
    }
    .addOnFailureListener { exception ->
        when (exception) {
            is FirebaseAuthMultiFactorException -> {
                // Initiate your second factor sign-in flow. (See next step.)
                // ...
            }
        }
    }

  2. يجب أن يطلب تدفق التطبيقات المصممة بغرض الإعلانات من المستخدم أولاً اختيار العامل الثاني ما يريدون استخدامه. يمكنك الحصول على قائمة بالعوامل الثانية المتوافقة من خلال فحص السمة hints لمثيل MultiFactorResolver:

    val enrolledFactors = exception.resolver.hints.map { it.displayName }

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

    when (exception.resolver.hints[selectedIndex].factorId) {
    TotpMultiFactorGenerator.FACTOR_ID -> {
        val otpFromAuthenticator = // OTP typed by the user.
        val assertion = TotpMultiFactorGenerator.getAssertionForSignIn(
            exception.resolver.hints[selectedIndex].uid,
            otpFromAuthenticator
        )
        exception.resolver.resolveSignIn(assertion)
            .addOnSuccessListener { result ->
                // Successfully signed in!
            }
            .addOnFailureListener { resolveError ->
                // Invalid or expired OTP.
            }
    }
    PhoneMultiFactorGenerator.FACTOR_ID -> {
        // Handle SMS second factor.
    }
}

إلغاء التسجيل في TOTP MFA

يصف هذا القسم كيفية التعامل مع إلغاء تسجيل مستخدم في TOTP MFA.

إذا اشترك مستخدم في خيارات MFA المتعددة، وفي حال إلغاء التسجيل من أحدث خيار تم تفعيله، سيحصلون على auth/user-token-expired ويتم تسجيل خروجهم. على المستخدم تسجيل الدخول مرة أخرى وإثبات ملكية بيانات الاعتماد الحالية، مثل عنوان البريد الإلكتروني وكلمة المرور.

لإلغاء تسجيل المستخدم ومعالجة الخطأ وبدء إعادة المصادقة، استخدم الرمز التالي:

Firebase.auth.currentUser.multiFactor.unenroll(mfaEnrollmentId)
    .addOnSuccessListener {
        // Second factor unenrolled.
    }
    .addOnFailureListener { exception ->
        when (exception) {
            is FirebaseAuthInvalidUserException -> {
                // Second factor unenrolled. If the user was signed out, re-authenticate
                // them.

                // For example, if they signed in with a password, prompt them to
                // provide it again, then call `reauthenticateWithCredential()` as shown
                // below.
                val credential = EmailAuthProvider.getCredential(email, password)
                currentUser.reauthenticate(credential)
                    .addOnSuccessListener { 
                        // Success!
                    }
                    .addOnFailureListener { 
                        // Bad email address and password combination.
                    }
            }
        }
    }

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