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

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

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

قبل البدء

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

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

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

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

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

تفعيل المصادقة المتعدّدة العوامل (MFA) المستندة إلى كلمة مرور لمرة واحدة مستندة إلى الوقت (TOTP)

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

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

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

   لا تتوافق المصادقة المتعدّدة العوامل (MFA) المستندة إلى كلمة مرور لمرة واحدة مستندة إلى الوقت (TOTP) إلا مع حزمة تطوير البرامج (SDK) لـ Firebase Admin Node.js، الإصدارات 11.6.0 والإصدارات الأحدث.

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

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

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

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

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

لتفعيل المصادقة المتعدّدة العوامل (MFA) المستندة إلى كلمة مرور لمرة واحدة مستندة إلى الوقت (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: عدد الفواصل الزمنية، من صفر إلى عشرة. القيمة التلقائية هي خمسة.

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

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

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

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

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

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

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

تسجيل المستخدمين في المصادقة المتعدّدة العوامل (MFA) المستندة إلى كلمة مرور لمرة واحدة مستندة إلى الوقت (TOTP)

بعد تفعيل المصادقة المتعدّدة العوامل (MFA) المستندة إلى كلمة مرور لمرة واحدة مستندة إلى الوقت (TOTP) كعامل ثانٍ لتطبيقك، عليك تنفيذ منطق من جهة العميل لتسجيل المستخدمين في المصادقة المتعدّدة العوامل (MFA) المستندة إلى كلمة مرور لمرة واحدة مستندة إلى الوقت (TOTP):

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

   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) بسرعة من خلال مسح رمز استجابة سريعة ضوئيًا يمثّل معرّف موارد موحّد للمفتاح متوافق مع Google Authenticator. لإنشاء رمز استجابة سريعة لهذا الغرض، أنشِئ معرّف الموارد الموحّد باستخدام generateQrCodeUrl() ثمّ ارمِزه باستخدام مكتبة رمز الاستجابة السريعة التي تختارها. على سبيل المثال:

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

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

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

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

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

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

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

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

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

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

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

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

إلغاء التسجيل في المصادقة المتعدّدة العوامل (MFA) المستندة إلى كلمة مرور لمرة واحدة مستندة إلى الوقت (TOTP)

يوضّح هذا القسم كيفية التعامل مع إلغاء تسجيل المستخدم في المصادقة المتعدّدة العوامل (MFA) المستندة إلى كلمة مرور لمرة واحدة مستندة إلى الوقت (TOTP).

إذا اشترك المستخدم في خيارات متعدّدة للمصادقة المتعدّدة العوامل (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
        );
    }
}

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

• إدارة المستخدمين الذين يستخدمون المصادقة المتعدّدة العوامل (MFA) آليًا باستخدام Admin SDK.