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 App Attest. Mengintegrasikan aplikasi dengan App Check membantu melindungi dari permintaan berbahaya, sehingga Anda tidak dikenai biaya untuk panggilan API yang tidak sah.

Apakah Pemeriksaan Aplikasi cocok untuk saya?

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

• Anda menggunakan Places SDK asli. App Check hanya didukung untuk Places SDK (Baru).
• Aplikasi pribadi atau eksperimental. Jika aplikasi Anda tidak dapat diakses secara publik, Pemeriksaan Aplikasi tidak diperlukan.
• Jika aplikasi Anda hanya digunakan server ke server, Pemeriksaan Aplikasi tidak diperlukan. Namun, jika server yang berkomunikasi dengan GMP digunakan oleh klien publik (seperti aplikasi seluler), sebaiknya gunakan App Check untuk melindungi server tersebut, bukan GMP.
• Penyedia pengesahan yang direkomendasikan App Check tidak akan berfungsi di perangkat yang dianggap disusupi atau tidak dapat dipercaya oleh penyedia pengesahan Anda. Jika perlu mendukung perangkat tersebut, Anda dapat men-deploy layanan pengesahan kustom. Untuk informasi selengkapnya, lihat petunjuk.

Ringkasan langkah-langkah penerapan

Pada tingkat tinggi, berikut adalah langkah-langkah yang akan Anda ikuti untuk mengintegrasikan aplikasi dengan App Check:

1. Tambahkan Firebase ke aplikasi Anda.
2. Tambahkan dan lakukan inisialisasi library App Check.
3. Tambahkan penyedia token ke aplikasi Anda.
4. Lakukan inisialisasi Places API dan App Check API.
5. Aktifkan proses debug.
6. Pantau permintaan aplikasi Anda dan tentukan penerapannya.

Setelah berintegrasi dengan App Check, Anda dapat melihat metrik traffic backend di Firebase console. Metrik ini memberikan pengelompokan 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 aplikasi ke versi terbaru yang menyertakan penerapan App Check, Anda dapat mengaktifkan penerapan. Setelah penerapan diaktifkan, App Check akan menolak semua traffic tanpa token App Check yang valid.

Catatan: Penerapan App Check tidak diaktifkan secara default.

Pertimbangan saat merencanakan integrasi App Check

Berikut beberapa hal yang perlu dipertimbangkan saat Anda merencanakan integrasi:

• Penyedia pengesahan yang kami rekomendasikan, Device Check atau App Attest, tunduk pada kuota dan batasan yang ditetapkan oleh Apple.

  Anda dapat memilih untuk menggunakan penyedia pengesahan kustom, meskipun ini adalah kasus penggunaan lanjutan. Lihat dokumentasi Firebase App Check untuk mengetahui informasi selengkapnya.

• Pengguna aplikasi Anda akan mengalami beberapa latensi saat memulai. Namun, setelah itu, setiap pengesahan ulang berkala akan terjadi di latar belakang dan pengguna tidak akan lagi mengalami latensi. Jumlah latensi yang tepat saat memulai bergantung pada penyedia pengesahan yang Anda pilih.

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

Mengintegrasikan aplikasi dengan App Check

Catatan: Dapatkan bantuan lebih cepat. Untuk mendapatkan dukungan terkait bagian proses ini yang terkait dengan Firebase, lihat dukungan Firebase. Untuk mendapatkan dukungan terkait Google Places SDK for iOS, lihat dukungan Google Maps Platform.

Prasyarat dan persyaratan

• Aplikasi dengan Places SDK versi 9.2 atau yang lebih baru telah diinstal.
• ID paket aplikasi.
• ID Tim Anda dari Apple Member Center, di bagian Membership.
• Jika Anda berencana menggunakan Pemeriksaan Perangkat, file kunci pribadi dan ID kunci Anda.
• Anda harus menjadi pemilik aplikasi di Cloud Console.
• Anda memerlukan project ID aplikasi dari Konsol Cloud

Langkah 1: Menambahkan Firebase ke aplikasi

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

Saat mendaftarkan aplikasi, Anda akan mendapatkan file konfigurasi, GoogleService-Info.plist. Tambahkan file ini, tanpa diubah, ke tingkat root aplikasi Anda.

Catatan: Pada langkah 5 dokumentasi developer Firebase, tempat Anda menambahkan modul Firebase ke file AppDelegate, tambahkan modul berikut:

Swift

import FirebaseCore
import FirebaseAppCheck
import GooglePlaces

Objective-C

@import FirebaseCore;      
@import FirebaseAppCheck;
@import GooglePlaces;

Langkah 2: Tambahkan library App Check dan lakukan 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 disediakan untuk melakukan inisialisasi App Check.

1. Ikuti petunjuk Firebase untuk menambahkan library App Check:
   • Petunjuk App Attest.
   • Petunjuk Pemeriksaan Perangkat.
2. Lakukan inisialisasi App Check.
   • Jika Anda menggunakan App Attest, ikuti dokumentasi developer Firebase untuk App Attest..

     Ikuti petunjuk Firebase App Check untuk membuat penerapan AppCheckProviderFactory dan menambahkannya ke file AppDelegate.

     Swift

     let providerFactory = YourAppCheckProviderFactory()
     AppCheck.setAppCheckProviderFactory(providerFactory)

     Objective-C

     YourAppCheckProviderFactory *providerFactory =
         [[YourAppCheckProviderFactory alloc] init];
     [FIRAppCheck setAppCheckProviderFactory:providerFactory];
        

   • Jika Anda menggunakan Pemeriksaan Perangkat, tambahkan kode berikut ke AppDelegate:

     Swift

     AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

     Objective-C

     [FIRAppCheck setAppCheckProviderFactory:providerFactory];
           

Langkah 3: Tambahkan penyedia token

Buat file bernama AppCheckTokenProvider (atau, jika Anda menggunakan Objective-C, dua file bernama AppCheckTokenProvider.h dan AppCheckTokenProvider.m) di tingkat root aplikasi Anda. Tambahkan pernyataan impor dan definisi class berikut:

Swift

// AppCheckTokenProvider.swift

import FirebaseAppCheck
import Foundation
import GooglePlaces

class AppCheckTokenProvider: NSObject, GMSPlacesAppCheckTokenProvider {
  func fetchAppCheckToken() async throws -> String {
    return try await AppCheck.appCheck().token(forcingRefresh: false).token
  }
}

Objective-C

// AppCheckTokenProvider.h

@import Foundation;
@import GooglePlaces;

@interface AppCheckTokenProvider : NSObject <GMSPlacesAppCheckTokenProvider>
@end

// AppCheckTokenProvider.m

#import "AppCheckTokenProvider.h"

@import FirebaseAppCheck;

@implementation AppCheckTokenProvider

- (void)fetchAppCheckTokenWithCompletion:(nonnull GMSAppCheckTokenCompletion)completion {
  [[FIRAppCheck appCheck]
      tokenForcingRefresh:NO
               completion:^(FIRAppCheckToken *_Nullable token, NSError *_Nullable error) {
                 if (token) {
                   completion(token.token, nil);
                 } else {
                   completion(nil, error);
                 }
               }];
}

@end

Langkah 4: Lakukan inisialisasi Places dan App Check API

1. Dalam file AppDelegate, lakukan inisialisasi Places API:

   Swift

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

   Objective-C

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

2. Kemudian, lakukan inisialisasi App Check API:

   Swift

   GMSPlacesClient.setAppCheckTokenProvider(AppCheckTokenProvider())

   Objective-C

   [GMSPlacesClient setAppCheckTokenProvider:[[AppCheckTokenProvider alloc] init]];

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 yang sebenarnya dalam build debug.

Untuk menguji aplikasi di Simulator atau di perangkat pengujian:

• Buat dan tetapkan factory penyedia debug App Check.

  Contoh kode ini menangani skenario proses debug dan produksi:

  Swift

  #if targetEnvironment(simulator)
        let providerFactory = AppCheckDebugProviderFactory()
  #else
        let providerFactory = YourAppCheckProviderFactory()
  #endif

  Objective-C

  if (targetEnvironment == simulator){
  
  FIRAppCheckDebugProviderFactory *providerFactory =
        [[FIRAppCheckDebugProviderFactory alloc] init];
  [FIRAppCheck setAppCheckProviderFactory:providerFactory];
  }
  
  else {
  
  YourAppCheckProviderFactory *providerFactory =
        [[YourAppCheckProviderFactory alloc] init];
  [FIRAppCheck setAppCheckProviderFactory:providerFactory];
  }
      

• Aktifkan logging di project Xcode Anda, luncurkan aplikasi, dan temukan token debug lokal dalam log.
• Tambahkan token ini ke Firebase console.
• Untuk informasi dan petunjuk selengkapnya, lihat dokumentasi App Check.

Untuk menjalankan aplikasi Anda di lingkungan CI:

• Buat token debug di Firebase console dan tambahkan ke key store aman sistem CI Anda.
• Di Xcode, tambahkan variabel lingkungan ke skema pengujian Anda dengan nama FIRAAppCheckDebugToken dan $(APP_CHECK_DEBUG_TOKEN) (atau yang serupa) sebagai nilainya.
• Dalam skrip pengujian CI, teruskan token debug sebagai lingkungan

• Buat dan tetapkan factory penyedia debug App Check.

  Contoh kode ini menangani skenario proses debug dan produksi:

  Swift

    #if targetEnvironment(ci)
          let providerFactory = AppCheckDebugProviderFactory()
          AppCheck.setAppCheckProviderFactory(providerFactory)
    #else
          let providerFactory = YourAppCheckProviderFactory()
    #endif
    

  Objective-C

  if (targetEnvironment == ci) {
  FIRAppCheckDebugProviderFactory *providerFactory =
        [[FIRAppCheckDebugProviderFactory alloc] init];
  [FIRAppCheck setAppCheckProviderFactory:providerFactory];
  }
  
  else {
  YourAppCheckProviderFactory *providerFactory =
        [[YourAppCheckProviderFactory alloc] init];
  [FIRAppCheck setAppCheckProviderFactory:providerFactory];
  }

• Untuk informasi dan petunjuk selengkapnya, lihat dokumentasi App Check.

Langkah 6: Pantau permintaan aplikasi Anda dan tentukan penerapannya

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

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

Sebelum menerapkan App Check, pastikan setiap panggilan Layanan Web di project Cloud Anda menggunakan OAuth.