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

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

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

قبل البدء

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

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

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

    لا يتم دعم TOTP MFA إلا على الإصدار 10.12.0 من Apple SDK أو الإصدارات الأحدث، وعلى نظام التشغيل iOS فقط.

تفعيل 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.
    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()
    

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

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

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

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

    // 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 MFA، استخدِم الرمز التالي:

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

    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 MFA

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

في حال اشترك المستخدم في عدّة خيارات MFA، وفي حال إلغاء التسجيل من أحدث خيار تم تفعيله، سيتلقّى 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.
}

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