使用 App Check 保護 API 金鑰

Firebase App Check 會封鎖來自非合法應用程式的流量，為應用程式對 Google 地圖平台的呼叫提供保護。方法是檢查 App Attest 等認證供應商提供的權杖。將應用程式與 App Check 整合，有助於防範惡意要求，避免您因未經授權的 API 呼叫而遭到收費。

我是否適合使用 App Check？

在大多數情況下，建議您使用 App Check，但在下列情況下，App Check 並非必要或不受支援：

  • 您使用的是原始的 Places SDK。App Check 僅支援 Places SDK (新版)。
  • 私人或實驗性應用程式。如果您的應用程式不開放公開存取，則不需要使用 App Check。
  • 如果您的應用程式只用於伺服器對伺服器，則不需要使用 App Check。不過，如果與 GMP 通訊的伺服器是由公開用戶端 (例如行動應用程式) 使用，建議您使用 App Check 保護該伺服器，而非 GMP。
  • 在裝置遭到入侵或不受信任時，App Check 建議的認證服務供應器將無法運作。如果您需要支援這類裝置，可以部署自訂認證服務。詳情請參閱操作說明。

導入步驟總覽

整體來說，您必須按照下列步驟將應用程式與 App Check 整合：

  1. 將 Firebase 新增至應用程式。
  2. 新增及初始化 App Check 程式庫。
  3. 在應用程式中新增權杖供應工具。
  4. 初始化 Places 和 App Check API。
  5. 啟用偵錯功能。
  6. 監控應用程式要求，並決定是否要執行。

整合 App Check 後，您就能在 Firebase 控制台中查看後端流量指標。這些指標會依據請求是否附帶有效的 App Check 權杖，提供請求的詳細資料。詳情請參閱 Firebase App Check 說明文件。

當您確定大部分要求都來自合法來源，且使用者已更新至包含 App Check 實作功能的最新版應用程式，即可啟用強制執行機制。強制執行之後，App Check 就會拒絕所有未取得有效 App Check 權杖的流量。

規劃 App Check 整合時的注意事項

規劃整合時，請考量以下幾點：

  • 我們推薦的認證服務供應商 (Device Check 或 App Attest) 須遵守 Apple 設定的配額和限制。

    您可以選擇使用自訂認證提供者，但這是進階用途。詳情請參閱 Firebase App Check 說明文件。

  • 您的應用程式使用者在啟動時會遇到一些延遲。不過，之後任何定期重新認證作業都會在背景執行，使用者應該不會再遇到任何延遲情形。啟動時的延遲時間長短取決於您選擇的認證服務供應商。

    App Check 權杖的有效時間 (稱為「存留時間」或 TTL) 會決定重新認證的頻率。您可以在 Firebase 控制台中設定這個時間長度。在 TTL 過半時，系統會重新認證。詳情請參閱認證服務供應商的 Firebase 說明文件。

將應用程式與 App Check 整合

必要條件

  • 已安裝 Places SDK 9.2 以上版本的應用程式。
  • 應用程式的軟體包 ID。
  • 在 Apple Member Center 的「Membership」(會員) 下方找到你的團隊 ID。
  • 如果您打算使用裝置檢查功能，請準備好私密金鑰檔案和金鑰 ID。
  • 您必須是 Cloud 控制台中應用程式的擁有者。
  • 您需要 Cloud 控制台中的應用程式專案 ID

步驟 1：將 Firebase 新增至應用程式

請按照 Firebase 開發人員說明文件中的操作說明，將 Firebase 新增至應用程式。

註冊應用程式後，您會收到設定檔 GoogleService-Info.plist。將這個未經修改的檔案新增至應用程式的根層級。

Swift

import FirebaseCore
import FirebaseAppCheck
import GooglePlaces

Objective-C

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

步驟 2：新增 App Check 程式庫並初始化 App Check

Firebase 會針對每個預設認證服務供應商提供操作說明。本操作說明將說明如何設定 Firebase 專案，並將 App Check 程式庫新增至應用程式。請按照提供的程式碼範例初始化 App Check。

  1. 按照 Firebase 操作說明新增 App Check 程式庫：
  2. 初始化 App Check。
    • 如果您使用的是 App Attest，請按照 App Attest 的 Firebase 開發人員說明文件操作。

      請按照 Firebase App Check 操作說明建立 AppCheckProviderFactory 的實作項目，並將其新增至 AppDelegate 檔案。

      Swift

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

      Objective-C

      YourAppCheckProviderFactory *providerFactory =
    [[YourAppCheckProviderFactory alloc] init];
[FIRAppCheck setAppCheckProviderFactory:providerFactory];
    • 如果您使用裝置檢查功能，請將下列內容新增至 AppDelegate：

      Swift

      AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

      Objective-C

      [FIRAppCheck setAppCheckProviderFactory:providerFactory];

步驟 3：新增權杖供應器

在應用程式的根層級建立名為 AppCheckTokenProvider 的檔案 (如果您使用 Objective-C，則為兩個名為 AppCheckTokenProvider.h 和 AppCheckTokenProvider.m 的檔案)。 新增下列匯入陳述式和類別定義：

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

步驟 4：初始化 Places 和 App Check API

  1. 在 AppDelegate 檔案中，初始化 Places API：

    Swift

    GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

    Objective-C

    [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];
  2. 接著，初始化 App Check API：

    Swift

    GMSPlacesClient.setAppCheckTokenProvider(AppCheckTokenProvider())

    Objective-C

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

步驟 5：啟用偵錯功能 (選用)

如果您想在本機開發及測試應用程式，或是在持續整合 (CI) 環境中執行應用程式，可以建立應用程式的偵錯版本，使用偵錯密鑰取得有效的 App Check 符記。這樣一來，您就不會在偵錯版本中使用實際的認證提供者。

如要在模擬器或測試裝置上測試應用程式，請按照下列步驟操作：

  • 建立並設定 App Check 偵錯提供者工廠。

    這個程式碼範例會處理偵錯和實際執行情境：

    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];
}
  • 在 Xcode 專案中啟用記錄功能、啟動應用程式，然後在記錄檔中找出本機偵錯符記。
  • 將這個權杖新增至 Firebase 控制台。
  • 如需更多資訊和操作說明，請參閱 App Check 說明文件。

如要在 CI 環境中執行應用程式，請按照下列步驟操作：

  • 在 Firebase 主控台中建立偵錯權杖，然後將其新增至 CI 系統的安全金鑰存放區。
  • 在 Xcode 中，將環境變數新增至測試計畫，並將名稱 FIRAAppCheckDebugToken 和 $(APP_CHECK_DEBUG_TOKEN) (或類似的名稱) 設為值。
  • 在持續整合測試指令碼中，將偵錯符記做為環境傳遞

  • 建立並設定 App Check 偵錯提供者工廠。

    這個程式碼範例會處理偵錯和實際執行情境：

    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];
}
  • 如需更多資訊和操作說明，請參閱 App Check 說明文件。

步驟 6：監控應用程式要求並決定是否執行

在開始執行前，請務必確認不會影響應用程式的合法使用者。如要確認這點，請前往「App Check」指標畫面，查看應用程式流量中經過驗證、過時或不合法的百分比。確認大部分流量都已驗證後，即可啟用強制執行機制。

詳情請參閱 Firebase App Check 說明文件。