Check out what’s new from Firebase at Google I/O 2022. Learn more

Aktifkan Pemeriksaan Aplikasi dengan reCAPTCHA Enterprise di aplikasi web

Halaman ini menunjukkan cara mengaktifkan App Check di aplikasi web, menggunakan penyedia reCAPTCHA Enterprise. Saat mengaktifkan App Check, Anda membantu memastikan bahwa hanya aplikasi Anda yang dapat mengakses sumber daya Firebase proyek Anda. Lihat Ikhtisar fitur ini.

reCAPTCHA Enterprise adalah layanan berbayar dengan kuota tanpa biaya. App Check juga mendukung reCAPTCHA v3 , layanan tanpa biaya. Untuk mempelajari perbedaan antara reCAPTCHA v3 dan reCAPTCHA Enterprise, lihat perbandingan fitur .

Perhatikan bahwa App Check menggunakan kunci situs berbasis skor reCAPTCHA Enterprise, yang membuatnya tidak terlihat oleh pengguna. Penyedia reCAPTCHA Enterprise tidak akan mengharuskan pengguna untuk memecahkan tantangan kapan saja.

Jika Anda ingin menggunakan App Check dengan penyedia kustom Anda sendiri, lihat Menerapkan penyedia App Check kustom .

1. Siapkan proyek Firebase Anda

  1. Tambahkan Firebase ke proyek JavaScript Anda jika Anda belum melakukannya.

  2. Buka bagian reCAPTCHA Enterprise di Cloud console dan lakukan hal berikut:

    1. Jika Anda diminta untuk mengaktifkan reCAPTCHA Enterprise API, lakukan.
    2. Buat kunci jenis Situs Web . Anda perlu menentukan domain tempat Anda menghosting aplikasi web. Biarkan opsi "Gunakan tantangan kotak centang " tidak dipilih .
  3. Daftarkan aplikasi Anda untuk menggunakan App Check dengan penyedia reCAPTCHA Enterprise di bagian App Check di Firebase console. Anda harus memberikan kunci situs yang Anda dapatkan di langkah sebelumnya.

    Anda biasanya perlu mendaftarkan semua aplikasi proyek Anda, karena setelah Anda mengaktifkan penerapan untuk produk Firebase, hanya aplikasi terdaftar yang dapat mengakses sumber daya backend produk.

  4. Opsional : Dalam pengaturan pendaftaran aplikasi, setel waktu-untuk-langsung (TTL) khusus untuk token Pemeriksaan Aplikasi yang dikeluarkan oleh penyedia. Anda dapat mengatur TTL ke nilai apa pun antara 30 menit dan 7 hari. Saat mengubah nilai ini, perhatikan pengorbanan berikut:

    • Keamanan: TTL yang lebih pendek memberikan keamanan yang lebih kuat, karena mengurangi jendela di mana token yang bocor atau dicegat dapat disalahgunakan oleh penyerang.
    • Performa: TTL yang lebih pendek berarti aplikasi Anda akan melakukan pengesahan lebih sering. Karena proses pengesahan aplikasi menambahkan latensi ke permintaan jaringan setiap kali dilakukan, TTL singkat dapat memengaruhi kinerja aplikasi Anda.
    • Kuota dan biaya: TTL yang lebih pendek dan pengesahan ulang yang sering menghabiskan kuota Anda lebih cepat, dan untuk layanan berbayar, berpotensi lebih mahal. Lihat Kuota & batas .

    TTL default 1 jam masuk akal untuk sebagian besar aplikasi. Perhatikan bahwa pustaka App Check menyegarkan token kira-kira setengah dari durasi TTL.

2. Tambahkan perpustakaan App Check ke aplikasi Anda

Tambahkan Firebase ke aplikasi web Anda jika Anda belum melakukannya. Pastikan untuk mengimpor perpustakaan App Check.

3. Inisialisasi Pemeriksaan Aplikasi

Tambahkan kode inisialisasi berikut ke aplikasi Anda, sebelum Anda mengakses layanan Firebase apa pun. Anda harus meneruskan kunci situs reCAPTCHA Enterprise, yang Anda buat di Cloud console, untuk activate() .

Web version 9

const { initializeApp } = require("firebase/app");
const { initializeAppCheck, ReCaptchaEnterpriseProvider } = require("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 version 8

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

Setelah library App Check diinstal di aplikasi Anda, terapkan.

Aplikasi klien yang diperbarui akan mulai mengirimkan token App Check bersama dengan setiap permintaan yang dibuatnya ke Firebase, tetapi produk Firebase tidak akan mengharuskan token valid sampai Anda mengaktifkan penegakan di bagian App Check di Firebase console. Lihat dua bagian berikutnya untuk detailnya.

4. Pantau metrik permintaan

Setelah aplikasi Anda yang diperbarui ada di tangan pengguna, Anda dapat mengaktifkan penerapan App Check untuk produk Firebase yang Anda gunakan. Namun, sebelum Anda melakukannya, Anda harus memastikan bahwa hal itu tidak akan mengganggu pengguna sah Anda yang sudah ada.

Database Realtime, Cloud Firestore, dan Cloud Storage

Alat penting yang dapat Anda gunakan untuk membuat keputusan ini untuk Realtime Database, Cloud Firestore, dan Cloud Storage adalah layar metrik permintaan App Check.

Untuk melihat metrik permintaan App Check untuk suatu produk, buka bagian App Check di Firebase console. Sebagai contoh:

Tangkapan layar halaman metrik Pemeriksaan Aplikasi

Metrik permintaan untuk setiap produk dipecah menjadi empat kategori:

  • Permintaan terverifikasi adalah permintaan yang memiliki token App Check yang valid. Setelah Anda mengaktifkan penerapan App Check, hanya permintaan dalam kategori ini yang akan berhasil.

  • Permintaan klien yang kedaluwarsa adalah permintaan yang tidak memiliki token App Check. Permintaan ini mungkin berasal dari versi Firebase SDK yang lebih lama sebelum App Check disertakan dalam aplikasi.

  • Permintaan asal tidak diketahui adalah permintaan yang tidak memiliki token App Check, dan sepertinya tidak berasal dari Firebase SDK. Ini mungkin dari permintaan yang dibuat dengan kunci API curian atau permintaan palsu yang dibuat tanpa Firebase SDK.

  • Permintaan yang tidak valid adalah permintaan yang memiliki token App Check yang tidak valid, yang mungkin berasal dari klien tidak autentik yang mencoba meniru aplikasi Anda, atau dari lingkungan yang diemulasi.

Distribusi kategori ini untuk aplikasi Anda harus memberi tahu saat Anda memutuskan untuk mengaktifkan penegakan. Berikut adalah beberapa pedoman:

  • Jika hampir semua permintaan terbaru berasal dari klien terverifikasi, pertimbangkan untuk mengaktifkan penegakan untuk mulai melindungi sumber daya backend Anda.

  • Jika sebagian besar permintaan terbaru berasal dari klien yang kemungkinan sudah usang, untuk menghindari mengganggu pengguna, pertimbangkan untuk menunggu lebih banyak pengguna mengupdate aplikasi Anda sebelum mengaktifkan penerapan. Menerapkan App Check pada aplikasi yang dirilis akan merusak versi aplikasi sebelumnya yang tidak terintegrasi dengan App Check SDK.

  • Jika aplikasi Anda belum diluncurkan, Anda harus segera mengaktifkan penerapan App Check, karena tidak ada klien lama yang digunakan.

Fungsi Cloud

Untuk Cloud Functions, Anda bisa mendapatkan metrik App Check dengan memeriksa log fungsi Anda. Setiap pemanggilan fungsi yang dapat dipanggil memancarkan entri log terstruktur seperti contoh berikut:

{
  "severity": "INFO",    // INFO, WARNING, or ERROR
  "logging.googleapis.com/labels": {"firebase-log-type": "callable-request-verification"},
  "jsonPayload": {
    "message": "Callable header verifications passed.",
    "verifications": {
      // ...
      "app": "MISSING",  // VALID, INVALID, or MISSING
    }
  }
}

Anda dapat menganalisis metrik ini di Google Cloud Console dengan membuat metrik penghitung berbasis log dengan filter metrik berikut:

resource.type="cloud_function"
resource.labels.function_name="YOUR_CLOUD_FUNCTION"
resource.labels.region="us-central1"
labels.firebase-log-type="callable-request-verification"

Beri label metrik menggunakan bidang jsonPayload.verifications.appCheck .

5. Aktifkan penegakan

Untuk mengaktifkan penegakan, ikuti petunjuk untuk setiap produk di bawah. Setelah Anda mengaktifkan penegakan untuk suatu produk, semua permintaan yang belum diverifikasi ke produk tersebut akan ditolak.

Database Realtime, Cloud Firestore, dan Cloud Storage

Untuk mengaktifkan penerapan Realtime Database, Cloud Firestore (iOS dan Android), dan Cloud Storage:

  1. Buka bagian App Check di Firebase console.

  2. Perluas tampilan metrik produk yang penerapannya ingin Anda aktifkan.

  3. Klik Terapkan dan konfirmasikan pilihan Anda.

Perhatikan bahwa diperlukan waktu hingga 15 menit setelah Anda mengaktifkan penerapan agar penerapannya dapat diterapkan.

Fungsi Cloud

Lihat Mengaktifkan penerapan Pemeriksaan Aplikasi untuk Cloud Functions .

Catatan tentang biaya

App Check membuat penilaian atas nama Anda untuk memvalidasi token respons pengguna setiap kali browser yang menjalankan aplikasi web Anda memperbarui token App Check-nya. Proyek Anda akan dikenakan biaya untuk setiap penilaian yang dibuat di atas kuota tanpa biaya. Lihat harga reCAPTCHA Enterprise untuk detailnya.

Secara default, aplikasi web Anda akan menyegarkan token ini dua kali setiap 1 jam . Untuk mengontrol seberapa sering aplikasi Anda memperbarui token App Check (dan dengan demikian seberapa sering penilaian baru dibuat), konfigurasikan TTL mereka .

Langkah selanjutnya

Jika, setelah Anda mendaftarkan aplikasi untuk App Check, Anda ingin menjalankan aplikasi di lingkungan yang biasanya tidak diklasifikasikan sebagai valid oleh App Check, seperti secara lokal selama pengembangan, atau dari lingkungan continuous integration (CI), Anda dapat membuat build debug aplikasi Anda yang menggunakan penyedia debug App Check alih-alih penyedia pengesahan nyata.

Lihat Menggunakan Pemeriksaan Aplikasi dengan penyedia debug di aplikasi web .