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

إذا تمّت ترقية حسابكم إلى 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) من Firebase لنظام التشغيل Apple.

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

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

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

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

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

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

  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. أعيدوا مصادقة المستخدم.

  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.
}

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

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

  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
}

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

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

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

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