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

إذا كنت قد أجريت ترقية إلى الإصدار Firebase Authentication with Identity Platform، يمكنك إضافة المصادقة المتعدّدة العوامل (MFA) المستندة إلى كلمة المرور لمرة واحدة المستندة إلى الوقت (TOTP) إلى تطبيقك.

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

قبل البدء

1. فعِّل موفِّرًا واحدًا على الأقل يتيح ميزة "التحقّق من الهوية في عدة مراحل". يُرجى العلم أنّ جميع مقدّمي الخدمة سوى مقدّمي الخدمة التاليين يتيحون ميزة "التحقّق من الهوية الإضافي":

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

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

3. ثبِّت حزمة تطوير البرامج (SDK) لـ Firebase JavaScript إذا لم يسبق لك إجراء ذلك.

   لا تتوافق ميزة TOTP MFA إلا مع حزمة تطوير البرامج (SDK) المستندة إلى الويب، والتي تشمل الإصدار 9.19.1 والإصدارات الأحدث.

تفعيل TOTP MFA

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

لاستخدام Admin SDK، اتّبِع الخطوات التالية:

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

   لا يتوافق TOTP MFA إلّا مع الإصدار 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 منها، من صفر إلى عشرة الإعداد الافتراضي هو خمسة.

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

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

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

اختيار نمط التسجيل

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

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

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

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

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

تسجيل المستخدمين في المصادقة المتعدّدة العوامل باستخدام بروتوكول TOTP

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

1. استورِد فئات وظائف المصادقة المتعددة العوامل المطلوبة:

   import {
     multiFactor,
     TotpMultiFactorGenerator,
     TotpSecret,
     getAuth,
   } from "firebase/auth";
   

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

3. أنشئ سرًا لبروتوكول TOTP للمستخدم الذي تمّت مصادقة هويته:

   // Generate a TOTP secret.
   const multiFactorSession = await multiFactor(currentUser).getSession();
   const totpSecret = await TotpMultiFactorGenerator.generateSecret(
     multiFactorSession
   );
   

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

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

   const totpUri = totpSecret.generateQrCodeUrl(
       currentUser.email,
       "Your App's Name"
   );
   await QRExampleLib.toCanvas(totpUri, qrElement);
   

   بغض النظر عما إذا كنت تعرض رمز الاستجابة السريعة، احرص دائمًا على عرض المفتاح السري لإتاحة تطبيقات المصادقة التي لا يمكنها قراءة رموز الاستجابة السريعة:

   // Also display this key:
   const secret = totpSecret.secretKey;
   

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

5. اطلب من المستخدم كتابة مفتاح المصادقة المتغير في الوقت (TOTP) المعروض على تطبيق المصادقة واستخدامه لإكمال عملية تسجيل ميزة "التحقّق المتعدّد العوامل":

   // Ask the user for a verification code from the authenticator app.
   const verificationCode = // Code from user input.
   
   // Finalize the enrollment.
   const multiFactorAssertion = TotpMultiFactorGenerator.assertionForEnrollment(
     totpSecret,
     verificationCode
   );
   await multiFactor(currentUser).enroll(multiFactorAssertion, mfaDisplayName);
   

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

لتسجيل دخول المستخدمين باستخدام المصادقة المتعدّدة العوامل من خلال رمز مرور متغيّر (TOTP)، استخدِم الرمز التالي:

1. استيراد فئات ودوال MFA المطلوبة:

   import {
       getAuth,
       getMultiFactorResolver,
       TotpMultiFactorGenerator,
   } from "firebase/auth";
   

2. اتصل بإحدى طرق signInWith كما لو لم تكن تستخدم ميزة "التحقّق من الهوية الإضافية". (على سبيل المثال، signInWithEmailAndPassword().) إذا ظهرت رسالة خطأ auth/multi-factor-auth-required، ابدأ عملية مصادقة ثنائية العوامل في تطبيقك.

   try {
       const userCredential = await signInWithEmailAndPassword(
           getAuth(),
           email,
           password
       );
       // 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.)
   
       // ...
   } catch (error) {
       switch (error.code) {
           case "auth/multi-factor-auth-required":
               // Initiate your second factor sign-in flow. (See next step.)
               // ...
               break;
           case ...:  // Handle other errors, such as wrong passwords.
               break;
       }
   }
   

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

   const mfaResolver = getMultiFactorResolver(getAuth(), error);
   const enrolledFactors = mfaResolver.hints.map(info => info.displayName);
   

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

   switch (mfaResolver.hints[selectedIndex].factorId) {
       case TotpMultiFactorGenerator.FACTOR_ID:
           const otpFromAuthenticator = // OTP typed by the user.
           const multiFactorAssertion =
               TotpMultiFactorGenerator.assertionForSignIn(
                   mfaResolver.hints[selectedIndex].uid,
                   otpFromAuthenticator
               );
           try {
               const userCredential = await mfaResolver.resolveSignIn(
                   multiFactorAssertion
               );
               // Successfully signed in!
           } catch (error) {
               // Invalid or expired OTP.
           }
           break;
       case PhoneMultiFactorGenerator.FACTOR_ID:
           // Handle SMS second factor.
           break;
       default:
           // Unsupported second factor?
           break;
   }
   

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

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

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

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

import {
    EmailAuthProvider,
    TotpMultiFactorGenerator,
    getAuth,
    multiFactor,
    reauthenticateWithCredential,
} from "firebase/auth";

try {
    // Unenroll from TOTP MFA.
    await multiFactor(currentUser).unenroll(mfaEnrollmentId);
} catch  (error) {
    if (error.code === 'auth/user-token-expired') {
        // 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.

        const credential = EmailAuthProvider.credential(email, password);
        await reauthenticateWithCredential(
            currentUser,
            credential
        );
    }
}

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

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