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

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

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

قبل البدء

1. عليك تفعيل مقدِّم خدمة واحد على الأقل يتيح MFA. يُرجى العلم أنّ جميع مقدّمي الخدمات باستثناء ما يلي يتيحون استخدام "MFA":

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

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

3. ثبِّت حزمة تطوير البرامج (SDK) لنظام التشغيل Android من Firebase إذا لم يسبق لك تثبيتها.

   لا يتوافق TOTP MFA إلا مع الإصدار 22.1.0 من Android SDK والإصدارات الأحدث.

تفعيل TOTP MFA

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

لاستخدام SDK للمشرف، نفِّذ ما يلي:

1. ثبِّت حزمة تطوير البرامج Node.js SDK لمشرف Firebase إذا لم يسبق لك إجراء ذلك.

   لا يتوفّر TOTP MFA إلا على الإصدار 11.6.0 والإصدارات الأحدث من حزمة SDK Admin Node.js في Firebase.

2. نفِّذ ما يلي:

   import { getAuth } from 'firebase-admin/auth';
   
   getAuth().projectConfigManager().updateProjectConfig(
   {
         multiFactorConfig: {
             providerConfigs: [{
                 state: "ENABLED",
                 totpProviderConfig: {
                     adjacentIntervals: {
                         NUM_ADJ_INTERVALS
                     },
                 }
             }]
         }
   })
   

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

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

     تعمل أدوات TOTP من خلال التأكد من أنه عندما ينشئ طرفان (المثبت والمدقق) كلمات المرور نفسها خلال الفترة الزمنية نفسها (عادةً ما تبلغ 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: عدد الفواصل الزمنية من صفر إلى عشرة العدد التلقائي هو خمسة.

  تعمل أدوات TOTP من خلال التأكد من أنه عندما ينشئ طرفان (المثبت والمدقق) كلمات المرور نفسها خلال الفترة الزمنية نفسها (عادةً ما تبلغ 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. يجب أن يطلب تدفق MFA في تطبيقك أولاً من المستخدم اختيار العامل الثاني الذي يريد استخدامه. يمكنك الحصول على قائمة بالعوامل الثانية المتوافقة من خلال فحص السمة hints لمثيل MultiFactorResolver:

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

3. إذا اختار المستخدم استخدام TOTP، اطلب منه كتابة 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.
                    }
            }
        }
    }

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

• إدارة المستخدمين متعددي العوامل آليًا باستخدام SDK للمشرف.