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

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

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

قبل البدء

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

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

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

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

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

تفعيل المصادقة المتعدّدة العوامل باستخدام رمز مصادقة الوقت المتغيّر (TOTP)

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

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

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

   لا تتوفّر ميزة "التأكّد من الهوية باستخدام كلمة مرور صالحة لمرة واحدة" إلا في الإصدار 11.6.0 من حزمة تطوير برامج (SDK) Firebase Admin Node.js والإصدارات الأحدث.

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) باستخدام واجهة برمجة التطبيقات 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

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

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

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

   // Generate a TOTP secret.
   guard let mfaSession = try? await currentUser.multiFactor.session() else { return }
   guard let totpSecret = try? await TOTPMultiFactorGenerator.generateSecret(with: mfaSession) else { return }
   
   // Display the secret to the user and prompt them to enter it into their
   // authenticator app. (See the next step.)
   

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

   // Display this key:
   let secret = totpSecret.sharedSecretKey()
   

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

   let otpAuthUri = totpSecret.generateQRCodeURL(
       withAccountName: currentUser.email ?? "default account",
       issuer: "Your App Name")
   totpSecret.openInOTPApp(withQRCodeURL: otpAuthUri)
   

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

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

   // Ask the user for a verification code from the authenticator app.
   let verificationCode = // Code from user input.
   
   // Finalize the enrollment.
   let multiFactorAssertion = TOTPMultiFactorGenerator.assertionForEnrollment(
       with: totpSecret,
       oneTimePassword: verificationCode)
   do {
       try await currentUser.multiFactor.enroll(
           with: multiFactorAssertion,
           displayName: "TOTP")
   } catch {
       // Wrong or expired OTP. Re-prompt the user.
   }
   

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

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

1. استخدِم إحدى طرق signIn(with...:) كما لو لم تكن تستخدم ميزة "التحقّق من الهوية الإضافية" (على سبيل المثال، signIn(withEmail:password:)). إذا ظهرت رسالة خطأ بالرمز secondFactorRequired، ابدأ عملية "التحقّق من الهوية الإضافية" في تطبيقك.

   do {
       let authResult = try await Auth.auth().signIn(withEmail: email, password: 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 let error as AuthErrorCode where error.code == .secondFactorRequired {
       // Initiate your second factor sign-in flow. (See next step.)
       // ...
   } catch {
       // Other auth error.
       throw error
   }
   

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

   let mfaKey = AuthErrorUserInfoMultiFactorResolverKey
   guard let resolver = error.userInfo[mfaKey] as? MultiFactorResolver else { return }
   let enrolledFactors = resolver.hints.map(\.displayName)
   

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

   let multiFactorInfo = resolver.hints[selectedIndex]
   switch multiFactorInfo.factorID {
   case TOTPMultiFactorID:
       let otpFromAuthenticator = // OTP typed by the user.
       let assertion = TOTPMultiFactorGenerator.assertionForSignIn(
           withEnrollmentID: multiFactorInfo.uid,
           oneTimePassword: otpFromAuthenticator)
       do {
           let authResult = try await resolver.resolveSignIn(with: assertion)
       } catch {
           // Wrong or expired OTP. Re-prompt the user.
       }
   default:
       return
   }
   

إلغاء التسجيل في ميزة "التأكّد من الهوية باستخدام كلمة مرور صالحة لمرة واحدة" (TOTP)

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

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

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

guard let currentUser = Auth.auth().currentUser else { return }

// Prompt the user to select a factor to unenroll, from this array:
currentUser.multiFactor.enrolledFactors

// ...

// Unenroll the second factor.
let multiFactorInfo = currentUser.multiFactor.enrolledFactors[selectedIndex]
do {
    try await currentUser.multiFactor.unenroll(with: multiFactorInfo)
} catch let error as AuthErrorCode where error.code == .invalidUserToken {
    // Second factor unenrolled, but the user was signed out. Re-authenticate
    // them.
}

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

• إدارة مستخدمي المصادقة متعددة العوامل برمجيًا باستخدام Admin SDK