Menggunakan App Check untuk mengamankan kunci API Anda

Firebase App Check memberikan perlindungan untuk panggilan dari aplikasi Anda ke Google Maps Platform dengan memblokir traffic yang berasal dari sumber selain aplikasi yang sah. Hal ini dilakukan dengan memeriksa token dari penyedia pengesahan seperti reCAPTCHA Enterprise. Mengintegrasikan aplikasi Anda dengan App Check membantu melindungi dari permintaan berbahaya, sehingga Anda tidak ditagih untuk panggilan API yang tidak sah.

Apakah App Check cocok untuk saya?

App Check direkomendasikan dalam sebagian besar kasus, tetapi App Check tidak diperlukan atau tidak didukung dalam kasus berikut:

Aplikasi pribadi atau eksperimental. Jika aplikasi Anda tidak dapat diakses secara publik, App Check tidak diperlukan.
Jika aplikasi Anda hanya digunakan server-ke-server, App Check tidak diperlukan. Namun, jika server yang berkomunikasi dengan GMP digunakan oleh klien publik (seperti aplikasi seluler), pertimbangkan untuk menggunakan App Check untuk melindungi server tersebut, bukan GMP.

Ringkasan langkah-langkah penerapan

Secara umum, berikut langkah-langkah yang akan Anda ikuti untuk mengintegrasikan aplikasi dengan App Check:

Tambahkan Firebase ke aplikasi Anda.
Tambahkan dan lakukan inisialisasi library App Check.
Tambahkan penyedia token ke aplikasi Anda.
Lakukan inisialisasi Maps JS dan App Check API.
Aktifkan proses debug.
Pantau permintaan aplikasi Anda dan tentukan penegakan.

Setelah terintegrasi dengan App Check, Anda dapat melihat metrik traffic backend di Firebase console. Metrik ini memberikan perincian permintaan berdasarkan apakah permintaan tersebut disertai dengan token App Check yang valid. Lihat dokumentasi Firebase App Check untuk mengetahui informasi selengkapnya.

Jika Anda yakin bahwa sebagian besar permintaan berasal dari sumber yang sah dan pengguna telah mengupdate ke aplikasi versi terbaru yang menyertakan penerapan App Check, Anda dapat mengaktifkan penegakan. Setelah penerapan diaktifkan, App Check akan menolak semua traffic tanpa token App Check yang valid.

Pertimbangan saat merencanakan integrasi App Check

Berikut beberapa hal yang perlu dipertimbangkan saat Anda merencanakan integrasi:

Salah satu penyedia pengesahan yang kami rekomendasikan, reCAPTCHA Enterprise,mengenakan biaya untuk lebih dari 10.000 penilaian per bulan.
Penyedia pengesahan lain yang kami rekomendasikan, reCAPTCHA v3, memiliki kuota, setelah itu traffic tidak akan dievaluasi.

Anda dapat memilih untuk menggunakan penyedia pengesahan kustom, meskipun ini adalah kasus penggunaan lanjutan. Lihat dokumentasi App Check untuk mengetahui informasi selengkapnya.
Pengguna aplikasi Anda akan mengalami beberapa latensi saat aplikasi dimulai. Namun, setelahnya, pengesahan ulang berkala akan terjadi di latar belakang dan pengguna tidak akan lagi mengalami latensi. Jumlah latensi yang tepat saat startup bergantung pada penyedia pengesahan yang Anda pilih.

Jumlah waktu validitas token App Check (time to live, atau TTL) menentukan frekuensi pengesahan ulang. Durasi ini dapat dikonfigurasi di Firebase console. Pengesahan ulang terjadi saat sekitar setengah TTL telah berlalu. Untuk mengetahui informasi selengkapnya, lihat dokumen Firebase untuk penyedia pengesahan Anda.

Mengintegrasikan aplikasi Anda dengan App Check

Prasyarat dan persyaratan

Aplikasi dengan Maps JS API versi mingguan atau kuartalan terbaru dan library Core dimuat.
Project Cloud dengan Maps JS API diaktifkan.
Anda harus menjadi pemilik aplikasi di Konsol Cloud.
Anda akan memerlukan project ID aplikasi dari Konsol Cloud

Langkah 1: Menambahkan Firebase ke aplikasi Anda

Ikuti petunjuk dalam dokumentasi developer Firebase untuk menambahkan Firebase ke aplikasi Anda.

Langkah 2: Tambahkan library App Check dan inisialisasi App Check

Firebase memberikan petunjuk untuk setiap penyedia pengesahan default. Petunjuk ini menunjukkan cara menyiapkan project Firebase dan menambahkan library App Check ke aplikasi Anda. Ikuti contoh kode yang diberikan untuk menginisialisasi App Check.

Petunjuk untuk reCAPTCHA Enterprise.
Petunjuk untuk reCAPTCHA v3.

Anda harus mendaftarkan situs untuk menggunakan reCAPTCHA v3 serta mendapatkan kunci situs dan kunci rahasia reCAPTCHA v3 menggunakan alat pendaftaran situs reCAPTCHA sebelum mengaktifkan API di Konsol Cloud. Lihat dokumentasi reCAPTCHA v3 untuk mengetahui informasi dan petunjuk selengkapnya.

Langkah 3: Muat library Maps JS API

Muat library inti dan Maps seperti yang ditunjukkan dalam cuplikan berikut. Untuk mengetahui informasi dan petunjuk selengkapnya, lihat dokumentasi Maps JavaScript API.
```
async function init() {
  const {Settings} = await google.maps.importLibrary('core');
  const {Map} = await google.maps.importLibrary('maps');
}  
```

Langkah 4: Lakukan inisialisasi Maps API dan App Check API

Lakukan inisialisasi App Check menggunakan konfigurasi yang disediakan oleh Firebase console.
- Petunjuk reCAPTCHA v3.
- Petunjuk reCAPTCHA Enterprise.

Pastikan permintaan ke Maps JS API disertai dengan token App Check:

  import {initializeApp} from 'firebase/app';
  import {
    getToken,
    initializeAppCheck,
    ReCaptchaEnterpriseProvider,
  } from 'firebase/app-check';
    
  async function init() {
    const {Settings} = await google.maps.importLibrary('core');
    const {Map} = await google.maps.importLibrary('maps');
  
    const app = initializeApp({
      // Your firebase configuration object
    });
  
    // Pass your reCAPTCHA Enterprise site key to initializeAppCheck().
    const appCheck = initializeAppCheck(app, {
      provider: new ReCaptchaEnterpriseProvider(
        'abcdefghijklmnopqrstuvwxy-1234567890abcd',
      ),
  
      // Optional argument. If true, the SDK automatically refreshes App Check
      // tokens as needed.
      isTokenAutoRefreshEnabled: true,
    });
  
    Settings.getInstance().fetchAppCheckToken = () =>
        getToken(appCheck, /* forceRefresh = */ false);
  
    // Load a map
    map = new Map(document.getElementById("map"), {
      center: { lat: 37.4161493, lng: -122.0812166 },
      zoom: 8,
    });
  }

Langkah 5: Aktifkan proses debug (opsional)

Jika ingin mengembangkan dan menguji aplikasi secara lokal, atau menjalankannya di lingkungan continuous integration (CI), Anda dapat membuat build debug aplikasi yang menggunakan secret debug untuk mendapatkan token App Check yang valid. Hal ini memungkinkan Anda menghindari penggunaan penyedia pengesahan nyata dalam build debug.

Untuk menguji aplikasi Anda secara lokal:

Aktifkan penyedia debug untuk tujuan pengembangan.
Anda akan menerima UUID4 acak yang dibuat secara otomatis (disebut _token debug_ dalam dokumentasi App Check) dari log debug SDK. Tambahkan token ini ke Firebase console.
Untuk mengetahui informasi dan petunjuk selengkapnya, lihat dokumentasi App Check.

Untuk menjalankan aplikasi Anda di lingkungan CI:

Buat UUID4 acak dari Firebase console.
Tambahkan UUID4 sebagai token debug, lalu salin ke penyimpanan rahasia yang akan diakses oleh pengujian CI per pengujian.
Untuk mengetahui informasi dan petunjuk selengkapnya, lihat dokumentasi App Check.

Langkah 6: Pantau permintaan aplikasi Anda dan tentukan penegakan

Sebelum memulai penerapan, Anda harus memastikan bahwa pengguna sah aplikasi Anda tidak akan terganggu. Untuk melakukannya, buka layar metrik App Check untuk melihat persentase traffic aplikasi Anda yang terverifikasi, tidak berlaku, atau tidak sah. Setelah melihat bahwa sebagian besar traffic Anda diverifikasi, Anda dapat mengaktifkan penerapan.

Lihat dokumentasi Firebase App Check untuk mengetahui informasi dan petunjuk selengkapnya.