使用 Firebase App Check 防止 Gemini API 遭濫用

直接從行動或網頁應用程式呼叫 API 時，API 容易遭到未經授權的用戶端濫用。如要直接從行動或網頁應用程式呼叫 Gemini API，請使用 Firebase AI Logic 並強制執行 Firebase App Check，防止 API 遭到濫用。強制執行 App Check 後，系統只會允許來自實際應用程式和/或未經竄改裝置的已驗證傳入要求。

跳到設定操作說明

Firebase AI Logic 提供 Proxy 閘道，可讓您與 Firebase App Check 整合，並在行動和網頁應用程式直接呼叫 Gemini API 時保護該 API。對 Firebase AI Logic 強制執行 App Check，有助於保護 Gemini Developer API 和 Agent Platform Gemini API (formerly Vertex AI)。

Firebase AI Logic 的 App Check 也支援重送攻擊防護，也就是說，App Check 權杖只能使用一次。


App Check 運作方式概略摘要

使用 App Check 時，執行應用程式的裝置會使用應用程式或裝置認證供應商，驗證下列一或兩項：

  • 要求來自您的正版應用程式
  • 要求來自未經竄改的正版裝置

應用程式使用 Firebase AI Logic SDK 發出的每項要求都會附加這項認證。強制執行 App Check 後，系統會拒絕來自未提供有效認證的用戶端要求，以及來自未經授權應用程式或平台的要求。

設定 App Check 時，建議您新增重放攻擊防護機制，讓 App Check 權杖只能使用一次。這個選項提供比基準防護更強的強化防護，可讓您根據應用程式和用途設定適當的防護等級。

如要查看 的 App Check詳細資訊，請參閱說明文件，包括認證供應商的說明，以及任何適用的配額和限制。

設定「App Check」

以下操作說明經過最佳化，可為Firebase AI Logic設定Firebase App Check強制執行。

步驟 1：強制執行 App Check

2026 年 7 月初起，在 Firebase 控制台的引導式設定工作流程中，Firebase 會自動對 Firebase AI Logic 強制執行 Firebase App Check，協助保護 Gemini API。

不過，如果您在 2026 年 7 月初之前，已在 Firebase 專案中設定 Firebase AI Logic (或因其他原因未強制執行 App Check)，則可按照下列操作說明自行強制執行 App Check。

  1. 檢查是否已對 Firebase AI Logic 強制執行 App Check。

    1. 在 Firebase 控制台中，依序前往「Security」(安全性) >「App Check」 >「APIs」(API) 分頁標籤。

    2. 找出 Firebase AI Logic 所在的資料列。如果顯示 Unenforced，請繼續執行其餘操作說明。

  2. 按一下 Firebase AI Logic 所在的資料列，即可查看指標圖表。按一下圖表下方的「設定」。

  3. 在對話方塊的第一個畫面 (「Baseline protection」(基本保護)) 中，選取「Enforced」(強制執行)，然後按一下「Continue」(繼續)。

  4. 在下一個畫面 (「Replay protection」(重播保護)) 中，選取「Disabled」(已停用)，然後按一下「Continue」(繼續)。

  5. 在最後一個畫面中，請詳閱強制執行 App Check 的注意事項，確認您已準備好強制執行 App Check。準備好後，請按一下「Continue」(繼續)。

    如果您只想強制執行 App Check，且僅在正式生產前應用程式中搭配 Firebase AI Logic 使用偵錯服務，則不需要註冊應用程式。不過，當您準備好向使用者發布應用程式時，就必須註冊應用程式，才能設定正式版認證服務 (例如 App Attest、Play Integrity 或 reCAPTCHA Enterprise)。

步驟 2：設定本機開發偵錯服務

如果是本機開發，您可以設定 App Check 偵錯服務，並繼續對 Firebase AI Logic 強制執行 App Check。

Swift

在模擬器中以互動方式執行應用程式時 (例如在本機開發期間)，請按照下列步驟使用偵錯服務：

  1. 在 Xcode 專案中，請先匯入 FirebaseAppCheck，並使用偵錯服務工廠初始化 App Check，再設定 Firebase。

    import SwiftUI
import FirebaseCore
import FirebaseAppCheck

@main
struct YourApp: App {
  init() {
    let providerFactory = AppCheckDebugProviderFactory()
    AppCheck.setAppCheckProviderFactory(providerFactory)
    FirebaseApp.configure()
  }

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

  2. 取得偵錯權杖：

    1. 在模擬器或測試裝置上啟動應用程式。

    2. 開啟 Xcode 控制台，找出 App Check 偵錯權杖。例如：

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.

    3. 複製權杖 (例如 123a4567-b89c-12d3-e456-789012345678)。

  3. 向 App Check 註冊偵錯權杖：

    1. 在 Firebase 控制台中，依序前往「Security」(安全性) >「App Check」 >「Apps」(應用程式) 分頁標籤。

    2. 找到應用程式，按一下溢位選單 ()，然後選取「Manage debug tokens」。

    3. 按照畫面上的指示註冊偵錯權杖。

如要進一步瞭解偵錯服務 (包括如何取得新的偵錯權杖)，請參閱官方 App Check 文件。

Kotlin

在模擬器中以互動方式執行應用程式時 (例如在本機開發期間)，請按照下列步驟使用偵錯服務：

  1. 在偵錯版本中，將 App Check 設為使用偵錯服務工廠：

    Firebase.initialize(context = this)
Firebase.appCheck.installAppCheckProviderFactory(
    DebugAppCheckProviderFactory.getInstance(),
)

  2. 取得偵錯權杖：

    1. 在模擬器或測試裝置上執行應用程式。

    2. 在記錄中尋找 App Check 偵錯權杖。例如：

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. 複製權杖 (例如 123a4567-b89c-12d3-e456-789012345678)。

  3. 向 App Check 註冊偵錯權杖：

    1. 在 Firebase 控制台中，依序前往「Security」(安全性) >「App Check」 >「Apps」(應用程式) 分頁標籤。

    2. 找到應用程式，按一下溢位選單 ()，然後選取「Manage debug tokens」。

    3. 按照畫面上的指示註冊偵錯權杖。

如要進一步瞭解偵錯服務 (包括如何取得新的偵錯權杖)，請參閱官方 App Check 文件。

Java

在模擬器中以互動方式執行應用程式時 (例如在本機開發期間)，請按照下列步驟使用偵錯服務：

  1. 在偵錯版本中，將 App Check 設為使用偵錯服務工廠：

    FirebaseApp.initializeApp(/*context=*/ this);
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance());

  2. 取得偵錯權杖：

    1. 在模擬器或測試裝置上執行應用程式。

    2. 在記錄中尋找 App Check 偵錯權杖。例如：

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. 複製權杖 (例如 123a4567-b89c-12d3-e456-789012345678)。

  3. 向 App Check 註冊偵錯權杖：

    1. 在 Firebase 控制台中，依序前往「Security」(安全性) >「App Check」 >「Apps」(應用程式) 分頁標籤。

    2. 找到應用程式，按一下溢位選單 ()，然後選取「Manage debug tokens」。

    3. 按照畫面上的指示註冊偵錯權杖。

如要進一步瞭解偵錯服務 (包括如何取得新的偵錯權杖)，請參閱官方 App Check 文件。

Web

如要在 localhost 中以互動方式執行應用程式 (例如在本機開發期間)，請按照下列步驟使用偵錯服務：

  1. 在偵錯版本中，請先將 self.FIREBASE_APPCHECK_DEBUG_TOKEN 設為 true，再初始化 App Check，以啟用偵錯模式。例如：

    self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
initializeAppCheck(app, { /* App Check options */ });

  2. 在本機造訪網頁應用程式，並開啟瀏覽器的開發人員工具。偵錯控制台會顯示偵錯權杖：

    AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
You will need to safelist it in the Firebase console for it to work.

  3. 向 App Check 註冊偵錯權杖：

    1. 在 Firebase 控制台中，依序前往「Security」(安全性) >「App Check」 >「Apps」(應用程式) 分頁標籤。

    2. 找到應用程式，按一下溢位選單 ()，然後選取「Manage debug tokens」。

    3. 按照畫面上的指示註冊偵錯權杖。

如要進一步瞭解偵錯服務 (包括如何取得新的偵錯權杖)，請參閱官方 App Check 文件。

Dart

iOS+

在模擬器中以互動方式執行應用程式時 (例如在本機開發期間)，請按照下列步驟使用偵錯服務：

  1. 初始化 Firebase 應用程式後，請立即使用偵錯服務啟用 App Check：

    import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';

// Import the firebase_app_check plugin
import 'package:firebase_app_check/firebase_app_check.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  await FirebaseAppCheck.instance.activate(
    // Set appleProvider to `AppleProvider.debug`
    appleProvider: AppleProvider.debug,
  );
  runApp(App());
}

  2. 在 Xcode 專案中啟用偵錯記錄檔功能：

    1. 依序開啟「Product」>「Scheme」>「Edit scheme」。
    2. 在左選單中選取「Run」，然後選取「Arguments」分頁標籤。
    3. 在「Arguments Passed on Launch」部分中，加入 -FIRDebugEnabled。

  3. 取得偵錯權杖：

    1. 使用 Xcode 開啟 ios/Runner.xcworkspace，然後在模擬器或測試裝置上執行應用程式。

    2. 開啟 Xcode 控制台，找出 App Check 偵錯權杖。例如：

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.

    3. 複製權杖 (例如 123a4567-b89c-12d3-e456-789012345678)。

  4. 向 App Check 註冊偵錯權杖：

    1. 在 Firebase 控制台中，依序前往「Security」(安全性) >「App Check」 >「Apps」(應用程式) 分頁標籤。

    2. 找到應用程式，按一下溢位選單 ()，然後選取「Manage debug tokens」。

    3. 按照畫面上的指示註冊偵錯權杖。

Android

在模擬器中以互動方式執行應用程式時 (例如在本機開發期間)，請按照下列步驟使用偵錯服務：

  1. 初始化 Firebase 應用程式後，請立即使用偵錯服務啟用 App Check：

    import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';

// Import the firebase_app_check plugin
import 'package:firebase_app_check/firebase_app_check.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  await FirebaseAppCheck.instance.activate(
    // Set androidProvider to `AndroidProvider.debug`
    androidProvider: AndroidProvider.debug,
  );
  runApp(App());
}

  2. 取得偵錯權杖：

    1. 在模擬器或測試裝置上執行應用程式。

    2. 在記錄中尋找 App Check 偵錯權杖。例如：

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. 複製權杖 (例如 123a4567-b89c-12d3-e456-789012345678)。

  3. 向 App Check 註冊偵錯權杖：

    1. 在 Firebase 控制台中，依序前往「Security」(安全性) >「App Check」 >「Apps」(應用程式) 分頁標籤。

    2. 找到應用程式，按一下溢位選單 ()，然後選取「Manage debug tokens」。

    3. 按照畫面上的指示註冊偵錯權杖。

網頁

如要在 localhost 以互動方式執行應用程式時 (例如在本機開發期間) 使用偵錯服務，請按照下列步驟操作：

  1. 在 web/index.html 檔案中，將 self.FIREBASE_APPCHECK_DEBUG_TOKEN 設為 true，啟用偵錯模式：

    <body>
  <script>
    self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
  </script>

  ...

</body>

  2. 在本機執行網頁應用程式，並開啟瀏覽器的開發人員工具。偵錯控制台中會顯示偵錯權杖：

    AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
You will need to safelist it in the Firebase console for it to work.

    這個權杖會儲存在瀏覽器本機，只要在同一部機器上使用同一個瀏覽器，就會用到這個權杖。如要在其他瀏覽器或機器上使用權杖，請將 self.FIREBASE_APPCHECK_DEBUG_TOKEN 設為權杖字串，而非 true。

  3. 向 App Check 註冊偵錯權杖：

    1. 在 Firebase 控制台中，依序前往「Security」(安全性) >「App Check」 >「Apps」(應用程式) 分頁標籤。

    2. 找到應用程式，按一下溢位選單 ()，然後選取「Manage debug tokens」。

    3. 按照畫面上的指示註冊偵錯權杖。

如要進一步瞭解偵錯服務 (包括如何取得新的偵錯權杖)，請參閱官方 App Check 文件。

Unity

在模擬器中以互動方式執行應用程式時 (例如在本機開發期間)，請按照下列步驟使用偵錯服務：

  1. 在 Firebase 控制台中建立偵錯權杖：

    1. 在 Firebase 控制台中，依序前往「Security」(安全性) >「App Check」 >「Apps」(應用程式) 分頁標籤。

    2. 找到應用程式，按一下溢位選單 ()，然後選取「Manage debug tokens」。

    3. 按照畫面上的指示建立新的偵錯權杖。

  2. 在應用程式的初始化程式碼中，加入以下內容：

    using Firebase.AppCheck;

void InitializeFirebase() {
  // Configure the Debug Provider factory with your debug token.
  DebugAppCheckProviderFactory.Instance.SetDebugToken("YOUR_DEBUG_TOKEN");

  // Set App Check to use the debug provider factory
  FirebaseAppCheck.SetAppCheckProviderFactory(
    DebugAppCheckProviderFactory.Instance);

  // Proceed to initialize Firebase as normal
}

如要進一步瞭解偵錯服務 (包括如何取得新的偵錯權杖)，請參閱官方 App Check 文件。

步驟 3：為使用者和正式環境設定 App Check

準備好向使用者發布應用程式時，您需要註冊應用程式，並設定正式版認證供應商 (例如 App Attest、Play Integrity 或 reCAPTCHA Enterprise)。

  1. 選擇正式環境認證供應商，並按照下列連結中的實作操作說明操作：

    請注意，如果這些認證供應商都不符合您的需求，您可以導入自訂供應商，使用第三方認證供應商或您自己的認證技術。

  2. (建議) 新增重放攻擊防護機制，強化防護效果，也就是 App Check 權杖只能使用一次。

新增重播防護機制，強化防護

建議使用最新版 SDK，但請務必至少使用下列其中一個版本，才能使用重送防護功能：
Apple 平台 v12.2.0 以上版本 | Android BoM v34.14.0 以上版本 (App Check v19.1.0 以上版本) | Web v12.14.0 以上版本 | Flutter v4.15.0 以上版本 (App Check v4.10.0 以上版本) | Unity v13.12.0 以上版本

根據預設，App Check 會使用工作階段符記，其存留時間 (TTL) 可設為 30 分鐘到 7 天。App Check SDK 會快取這些工作階段符記，並隨應用程式的要求一併傳送，且可重複使用，直到存留時間到期為止。使用工作階段符記屬於基本保護措施。

不過，您可以強制執行重放攻擊防護機制，改用有限使用權杖，進一步強化防護。強制執行重放攻擊防護機制時，會發生下列情況：

  • App Check 會封鎖使用工作階段符記傳送至 Firebase AI Logic 的要求。App Check 只會允許使用新產生的有限使用權杖向 Firebase AI Logic 提出的要求。

  • 有限使用權杖通過驗證後，就會被消耗掉，因此只能使用一次，可防範重放攻擊。

  • App Check SDK 會為「每個」要求產生新的有限使用權杖。請注意，這項程序可能會增加一些延遲時間，有時也會產生費用 (取決於認證供應商)，進而影響要求。

設定及強制執行重放攻擊防護機制

按一下您的Gemini API供應商，即可在這個頁面查看供應商專屬內容和程式碼。

設定及強制執行重播保護機制的步驟如下：

  1. 如果您尚未設定 App Check，請按照本頁前述的操作說明 設定。

  2. 啟用有限使用權杖。

    在應用程式中例項化時，請將 useLimitedUseAppCheckTokens 參數設為 true：

    Swift 

    
// ...

// During instantiation, enable usage of limited-use tokens.
let ai = FirebaseAI.firebaseAI(
  backend: .googleAI(),
  useLimitedUseAppCheckTokens: true
)

// ...

    Kotlin 

    
// ...

// During instantiation, enable usage of limited-use tokens.
val ai = Firebase.ai(
  backend = GenerativeBackend.googleAI(),
  useLimitedUseAppCheckTokens = true
)

// ...

    Java 

    
// ...

// During instantiation, enable usage of limited-use tokens.
FirebaseAI ai = FirebaseAI.getInstance(
  /* backend: */ GenerativeBackend.googleAI(),
  /* useLimitedUseAppCheckTokens: */ true
);

// ...

    Web 

    
// ...

// During instantiation, enable usage of limited-use tokens.
const ai = getAI(firebaseApp, {
  backend: new GoogleAIBackend(),
  useLimitedUseAppCheckTokens: true
});

// ...

    Dart 

    
// ...

// During instantiation, enable usage of limited-use tokens
final ai = await FirebaseAI.googleAI(
  useLimitedUseAppCheckTokens: true,
);

// ...

    Unity 

    // ...

// During instantiation, enable usage of limited-use tokens
var ai = FirebaseAI.GetInstance(
  useLimitedUseAppCheckTokens: true
);

// ...

  3. 強制執行重放攻擊防護機制。

    1. 在應用程式的程式碼集中，確認您已啟用有限使用權杖 (請參閱上一個步驟)。

    2. 在 Firebase 控制台，依序前往「Security」(安全性) >「App Check」。

    3. 展開「Firebase AI Logic」的指標檢視畫面。

    4. 確認「Baseline protection」(基準保護) 設為「Enforced」(強制執行)，然後按一下「Continue」(繼續)。

    5. 如要啟用重播防護功能，請選擇「Unenforced (monitoring only)」(未強制執行 (僅限監控)) 或「Enforced」(強制執行)。

      請考量下列事項，決定何時強制執行重送保護：

      • 如果您的使用者有相當多的人可能使用舊版應用程式，且未啟用有限使用權杖，建議您監控要求。如果立即強制執行重送保護，系統會封鎖這些使用者的要求。

      • 您可以特別監控「未驗證：重複使用的權杖」指標，這項指標代表要求中包含先前要求已使用過的權杖。請在 Firebase 控制台監控這項指標 (依序前往「Security」(安全性) >「App Check」 >「APIs」(API) 分頁)。

        如果近期要求有很大一部分屬於這個類別，建議您先不要強制執行重送攻擊防護措施，以免干擾使用者，等到更多使用者更新至使用有限使用權杖的應用程式版本後，再強制執行。

瞭解 Firebase AI Logic 如何與 App Check 整合

如要使用 Firebase AI Logic SDK，必須在 Firebase 專案中啟用 Firebase AI Logic API (firebasevertexai.googleapis.com)。這是因為 Firebase AI Logic SDK 發出的要求會先傳送至 Firebase AI Logic 伺服器，該伺服器會做為 Proxy 閘道，在要求獲准傳送至 Gemini API 並存取 Gemini 模型「之前」，先進行 Firebase App Check 驗證。

常見問題與疑難排解

查看與 Firebase AI Logic 相關的其他常見問題和疑難排解或錯誤代碼。