بدء استخدام ميزة "التحقّق من التطبيقات" مع reCAPTCHA Enterprise في تطبيقات الويب

تعرض هذه الصفحة كيفية تفعيل ميزة App Check في تطبيق ويب باستخدام موفّر reCAPTCHA Enterprise. عند تفعيل App Check، يمكنك المساعدة في ضمان عدم إمكانية وصول سوى تطبيقك إلى موارد الخلفية في مشروعك. الاطّلاع على نظرة عامة حول هذه الميزة

يُرجى العِلم أنّ App Check تستخدم مفاتيح المواقع الإلكترونية المستندة إلى درجة المخاطر في reCAPTCHA Enterprise، ما يجعلها غير مرئية للمستخدمين. لن يطلب موفّر reCAPTCHA Enterprise من المستخدمين حلّ أي تحدٍ في أي وقت.

إذا كانت حالة الاستخدام تتطلّب ميزات reCAPTCHA Enterprise غير المضمّنة في App Check، أو إذا كنت تريد استخدام App Check مع موفّر مخصّص، يُرجى الاطّلاع على مقالة تنفيذ موفّر مخصّص لـ App Check.

1. إعداد مشروع Firebase

  1. أضِف Firebase إلى مشروع JavaScript إذا لم يسبق لك إجراء ذلك.

  2. افتح قسم reCAPTCHA Enterprise في وحدة التحكم Google Cloudونفِّذ ما يلي:

    1. إذا طُلب منك تفعيل reCAPTCHA Enterprise API، يُرجى إجراء ذلك.
    2. أنشئ مفتاحًا من نوع موقع إلكتروني. عليك تحديد النطاقات التي تستضيف عليها تطبيق الويب. اترك الخيار "استخدام تحدّي مربّع الاختيار" غير محدّد.

  3. في وحدة تحكُّم Firebase، انتقِل إلى الأمان > فحص التطبيقات.

  4. في علامة التبويب التطبيقات ، سجِّل تطبيقاتك لاستخدام App Check مع موفّر reCAPTCHA Enterprise. عليك تقديم مفتاح الموقع الإلكتروني الذي حصلت عليه في وحدة تحكّم Google Cloud.

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

  5. اختياري: في إعدادات تسجيل التطبيق، اضبط مدة بقاء مخصّصة (TTL) للرموز المميّزة التي يصدرها الموفّر.App Check يمكنك ضبط مدة البقاء على أي قيمة تتراوح بين 30 دقيقة و7 أيام. عند تغيير هذه القيمة، يُرجى العِلم بالمقايضات التالية:

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

    تُعدّ مدة البقاء التلقائية التي تبلغ ساعة واحدة معقولة لمعظم التطبيقات. يُرجى العِلم أنّ مكتبة App Check تُعيد تحميل الرموز المميّزة بنصف مدة البقاء تقريبًا.

ضبط الإعدادات المتقدّمة (اختياري)

عندما يزور المستخدم تطبيق الويب، يقيّم reCAPTCHA Enterprise مستوى المخاطر التي يشكّلها تفاعل المستخدم، ويعرض درجة تتراوح بين 0.0 و1.0، بزيادات قدرها 0.1. تشير الدرجة 1.0 إلى أنّ التفاعل يشكّل خطرًا منخفضًا ومن المرجّح جدًا أن يكون مشروعًا، بينما تشير الدرجة 0.0 إلى أنّ التفاعل يشكّل خطرًا عاليًا وقد يكون احتياليًا. App Check تتيح لك ضبط حدّ مخاطر التطبيق لتعديل مدى تحمّلك لهذا الخطر.

بالنسبة إلى معظم حالات الاستخدام، ننصح باستخدام قيمة الحدّ التلقائية البالغة 0.5. إذا كانت حالة الاستخدام تتطلّب تعديلها، يمكن ضبطها في قسم App Check في وحدة تحكُّم Firebase لكل تطبيق من تطبيقات الويب.

التفاصيل

App Check تستخدم حدّ مخاطر التطبيق الذي تم ضبطه كأدنى درجة مطلوبة لتفاعل المستخدم في reCAPTCHA Enterprise ليتم اعتباره مشروعًا. سيتم رفض جميع درجات reCAPTCHA Enterprise الأقل من الحدّ الذي تم ضبطه. عند تعديل حدّ مخاطر التطبيق، يُرجى العِلم بما يلي:

  • من بين مستويات درجات reCAPTCHA Enterprise الـ 11 المتاحة، لا يتوفّر سوى مستويات الدرجات الأربعة التالية قبل إضافة حساب فوترة على Google Cloud إلى مشروعك: 0.1 و0.3 و0.7 و0.9. خلال هذه الفترة، لن تسمح App Check إلا بقيم حدّ مخاطر التطبيق التالية: 0.1 و0.3 و0.5 و0.7 و0.9. ننصحك أيضًا باستخدام قيمة حدّ مخاطر التطبيق البالغة 0.5 لمعظم حالات الاستخدام.

    • لتفعيل جميع مستويات درجات reCAPTCHA Enterprise الـ 11، أضِف حساب فوترة على Google Cloud إلى مشروعك. إحدى طرق إجراء ذلك هي الترقية إلى خطة Blaze المَرِنة. بعد إجراء ذلك، ستسمح لك App Check بضبط أي قيم لحدّ مخاطر التطبيق تتراوح بين 0.0 و1.0، بزيادات قدرها 0.1.

  • لمراقبة توزيع درجات reCAPTCHA Enterprise العالية والمنخفضة لتطبيق الويب، انتقِل إلى صفحة reCAPTCHA Enterprise في Google Cloud console واختَر مفتاح الموقع الإلكتروني الذي يستخدمه تطبيق الويب.

  • إذا كان لديك مدى تحمّل منخفض لمخاطر التطبيق، حرِّك شريط التمرير إلى اليسار لزيادة حدّ مخاطر التطبيق.

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

  • إذا كان لديك مدى تحمّل عالي لمخاطر التطبيق، حرِّك شريط التمرير إلى اليمين لتقليل حدّ مخاطر التطبيق.

    • لا ننصح باستخدام القيمة 0.0، لأنّ هذا الإعداد يؤدي إلى إيقاف الحماية من إساءة الاستخدام.

يُرجى الاطّلاع على مستندات reCAPTCHA Enterprise للحصول على تفاصيل إضافية.

2. إضافة مكتبة App Check إلى تطبيقك

أضِف Firebase إلى تطبيق الويب إذا لم يسبق لك إجراء ذلك. احرص على استيراد مكتبة App Check.

3. إعداد App Check

أضِف رمز الإعداد التالي إلى تطبيقك قبل الوصول إلى أي من خدمات Firebase. عليك تمرير مفتاح موقع reCAPTCHA Enterprise الإلكتروني الذي أنشأته في Cloud Console إلى activate().

Web

import { initializeApp } from "firebase/app";
import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";

const app = initializeApp({
  // Your Firebase configuration object.
});

// Create a ReCaptchaEnterpriseProvider instance using your reCAPTCHA Enterprise
// site key and pass it to initializeAppCheck().
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider(/* reCAPTCHA Enterprise site key */),
  isTokenAutoRefreshEnabled: true // Set to true to allow auto-refresh.
});

Web

firebase.initializeApp({
  // Your Firebase configuration object.
});

// Create a ReCaptchaEnterpriseProvider instance using your reCAPTCHA Enterprise
// site key and pass it to activate().
const appCheck = firebase.appCheck();
appCheck.activate(
  new firebase.appCheck.ReCaptchaEnterpriseProvider(
    /* reCAPTCHA Enterprise site key */
  ),
  true // Set to true to allow auto-refresh.
);

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

بعد تثبيت مكتبة App Check في تطبيقك، عليك نشره.

سيبدأ تطبيق العميل المعدَّل بإرسال App Check الرموز المميّزة مع كل طلب يرسله إلى Firebase، ولكن لن تطلب منتجات Firebase أن تكون الرموز المميّزة صالحة إلى أن تفعِّل فرض الحماية في قسم App Check في وحدة تحكُّم Firebase.

مراقبة المقاييس وتفعيل فرض الحماية

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

للمساعدة في اتّخاذ هذا القرار، يمكنك الاطّلاع على App Check مقاييس للـ خدمات التي تستخدمها:

تفعيل فرض الحماية لميزة "App Check"

عندما تفهم كيف ستؤثّر App Check في المستخدمين وتكون مستعدًا للمتابعة، يمكنك تفعيل فرض الحماية لميزة App Check:

استخدام App Check في بيئات تصحيح الأخطاء

إذا أردت، بعد تسجيل تطبيقك في App Check، تشغيل تطبيقك في بيئة لا تصنّفها App Check عادةً على أنّها صالحة، مثل البيئة المحلية أثناء التطوير أو من بيئة التكامل المستمر (CI)، يمكنك إنشاء إصدار مخصص لتصحيح الأخطاء من تطبيقك يستخدم موفّر تصحيح الأخطاء في App Check بدلاً من موفّر إثبات الهوية الحقيقي.

يُرجى الاطّلاع على مقالة استخدام App Check مع موفّر تصحيح الأخطاء في تطبيقات الويب.

ملاحظة حول التكلفة

App Check تنشئ تقييمًا نيابةً عنك للتحقّق من رمز استجابة المستخدم المميّز في كل مرة يُعيد فيها متصفّح يشغّل تطبيق الويب تحميل الرمز المميّز App Check. سيتم تحصيل رسوم من مشروعك مقابل كل تقييم يتم إنشاؤه فوق الحصة المجانية. يُرجى الاطّلاع على أسعار reCAPTCHA للحصول على التفاصيل.

تلقائيًا، سيُعيد تطبيق الويب تحميل هذا الرمز المميّز مرّتين كل ساعة واحدة. للتحكّم في عدد مرّات إعادة تحميل تطبيقك للرموز المميّزة App Check (وبالتالي عدد مرّات إنشاء التقييمات الجديدة)، عليك ضبط مدة البقاء لها.