Impedire l'utilizzo illecito dell'API Gemini con Firebase App Check

Quando chiami un'API direttamente da un'app web o mobile, l'API è vulnerabile all'abuso da parte di client non autorizzati. Se vuoi chiamare Gemini API direttamente dalla tua app web o mobile, devi proteggerla da comportamenti illeciti utilizzando Firebase AI Logic e applicando Firebase App Check. Quando applichi App Check, verranno consentite solo le richieste in entrata verificate come provenienti dalla tua app effettiva e/o da un dispositivo non manomesso.

Vai alle istruzioni di configurazione

Firebase AI Logic fornisce un gateway proxy che ti consente di integrarti con Firebase App Check e proteggere Gemini API quando viene chiamato direttamente dalle tue app web e mobile. Quando App Check viene applicato a Firebase AI Logic, contribuisce a proteggere sia Gemini Developer API che Agent Platform Gemini API (formerly Vertex AI).

App Check per Firebase AI Logic supporta anche la protezione di riproduzione, il che significa che un token App Check può essere utilizzato una sola volta.


Riepilogo di alto livello del funzionamento di App Check

Con App Check, i dispositivi che eseguono la tua app utilizzano un fornitore di attestazione di app o dispositivo che verifica uno o entrambi i seguenti elementi:

  • Le richieste provengono dalla tua app autentica
  • Le richieste provengono da un dispositivo autentico e non manomesso

Questa attestazione viene allegata a ogni richiesta effettuata dalla tua app utilizzando un SDK Firebase AI Logic. Quando App Check viene applicato, le richieste dei client senza un'attestazione valida verranno rifiutate, così come qualsiasi richiesta proveniente da un'app o una piattaforma che non hai autorizzato.

Quando configuri App Check, valuta la possibilità di aggiungere la protezione di riproduzione, che rende i token App Check utilizzabili una sola volta. Questa opzione offre una protezione avanzata oltre a quella di base e ti consente di impostare un livello di protezione appropriato per la tua app e i tuoi casi d'uso.

Puoi trovare informazioni dettagliate su App Check nella relativa documentazione, incluse le descrizioni dei fornitori di attestazione e le eventuali quote e limiti applicabili.

Configura App Check

Le seguenti istruzioni sono ottimizzate per la configurazione dell'applicazione di Firebase App Check per Firebase AI Logic.

Passaggio 1: applica App Check

A partire dai primi giorni di luglio 2026, durante il workflow di configurazione guidata nella console Firebase, Firebase applica automaticamente Firebase App Check per Firebase AI Logic per contribuire a proteggere Gemini API.

Tuttavia, se avevi già configurato Firebase AI Logic nel tuo progetto Firebase prima dell'inizio di luglio 2026 (o se App Check non è applicato per qualche altro motivo), puoi applicarlo autonomamente seguendo le istruzioni riportate di seguito.App Check

  1. Controlla se App Check è già applicato per Firebase AI Logic.

    1. Nella console Firebase, vai alla scheda Sicurezza > App Check > API.

    2. Trova la riga per Firebase AI Logic. Se viene visualizzato Unenforced, continua con il resto di queste istruzioni.

  2. Fai clic sulla riga relativa a Firebase AI Logic e vedrai i grafici delle metriche. Sotto i grafici, fai clic su Configura.

  3. Nella prima schermata della finestra di dialogo (Protezione di base), seleziona Applicata, quindi fai clic su Continua.

  4. Nella schermata successiva (Protezione da replay), seleziona Disattivata e poi fai clic su Continua.

  5. Nella schermata finale, esamina le considerazioni per l'applicazione di App Check per assicurarti di essere pronto a farlo App Check. Se è tutto pronto, fai clic su Continua.

    Non devi registrare le tue app se vuoi solo applicare App Check e utilizzare solo il provider di debug con Firebase AI Logic in un'app pre-produzione. Tuttavia, quando sei pronto a rilasciare la tua app agli utenti finali, devi registrarla nell'ambito della configurazione di un provider di attestazioni di produzione (come App Attest, Play Integrity o reCAPTCHA Enterprise).

Passaggio 2: configura il provider di debug per lo sviluppo locale

Per lo sviluppo locale, puoi configurare il provider di debug App Check e mantenere comunque l'applicazione di App Check per Firebase AI Logic.

Swift

Ecco come utilizzare il provider di debug durante l'esecuzione dell'app in un simulatore in modo interattivo (ad esempio, durante lo sviluppo locale):

  1. Nel progetto Xcode, importa FirebaseAppCheck e inizializza App Check con la fabbrica del provider di debug prima di configurare 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. Ottieni il token di debug:

    1. Avvia l'app nel simulatore o sul dispositivo di test.

    2. Apri la console Xcode e cerca il token di debug App Check. Ad esempio:

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

    3. Copia il token (ad esempio, 123a4567-b89c-12d3-e456-789012345678).

  3. Registra il token di debug con App Check:

    1. Nella console Firebase, vai alla scheda Sicurezza > App Check > App.

    2. Trova la tua app, fai clic sul menu extra () e poi seleziona Gestisci token di debug.

    3. Segui le istruzioni sullo schermo per registrare il token di debug.

Per informazioni dettagliate sul provider di debug (incluso come ottenere un nuovo token di debug), consulta la documentazione ufficiale di App Check.

Kotlin

Ecco come utilizzare il provider di debug durante l'esecuzione dell'app in un emulatore in modo interattivo (ad esempio, durante lo sviluppo locale):

  1. Nella build di debug, configura App Check in modo da utilizzare la fabbrica del provider di debug:

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

  2. Ottieni il token di debug:

    1. Esegui l'app nell'emulatore o sul dispositivo di test.

    2. Cerca il token di debug App Check nei log. Ad esempio:

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

    3. Copia il token (ad esempio, 123a4567-b89c-12d3-e456-789012345678).

  3. Registra il token di debug con App Check:

    1. Nella console Firebase, vai alla scheda Sicurezza > App Check > App.

    2. Trova la tua app, fai clic sul menu extra () e poi seleziona Gestisci token di debug.

    3. Segui le istruzioni sullo schermo per registrare il token di debug.

Per informazioni dettagliate sul provider di debug (incluso come ottenere un nuovo token di debug), consulta la documentazione ufficiale di App Check.

Java

Ecco come utilizzare il provider di debug durante l'esecuzione dell'app in un emulatore in modo interattivo (ad esempio, durante lo sviluppo locale):

  1. Nella build di debug, configura App Check in modo da utilizzare la fabbrica del provider di debug:

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

  2. Ottieni il token di debug:

    1. Esegui l'app nell'emulatore o sul dispositivo di test.

    2. Cerca il token di debug App Check nei log. Ad esempio:

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

    3. Copia il token (ad esempio, 123a4567-b89c-12d3-e456-789012345678).

  3. Registra il token di debug con App Check:

    1. Nella console Firebase, vai alla scheda Sicurezza > App Check > App.

    2. Trova la tua app, fai clic sul menu extra () e poi seleziona Gestisci token di debug.

    3. Segui le istruzioni sullo schermo per registrare il token di debug.

Per informazioni dettagliate sul provider di debug (incluso come ottenere un nuovo token di debug), consulta la documentazione ufficiale di App Check.

Web

Ecco come utilizzare il provider di debug durante l'esecuzione dell'app da localhost in modo interattivo (ad esempio, durante lo sviluppo locale):

  1. Nella build di debug, attiva la modalità di debug impostando self.FIREBASE_APPCHECK_DEBUG_TOKEN su true prima di inizializzare App Check. Ad esempio:

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

  2. Visita la tua app web in locale e apri gli strumenti per sviluppatori del browser. Nella console di debug, vedrai un token di debug:

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

  3. Registra il token di debug con App Check:

    1. Nella console Firebase, vai alla scheda Sicurezza > App Check > App.

    2. Trova la tua app, fai clic sul menu extra () e poi seleziona Gestisci token di debug.

    3. Segui le istruzioni sullo schermo per registrare il token di debug.

Per informazioni dettagliate sul provider di debug (incluso come ottenere un nuovo token di debug), consulta la documentazione ufficiale di App Check.

Dart

iOS+

Ecco come utilizzare il provider di debug durante l'esecuzione dell'app in un simulatore in modo interattivo (ad esempio, durante lo sviluppo locale):

  1. Attiva App Check con il provider di debug subito dopo aver inizializzato l'app Firebase:

    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. Attiva il logging di debug nel tuo progetto Xcode:

    1. Apri Product > Scheme > Edit scheme (Prodotto > Schema > Modifica schema).
    2. Seleziona Run (Esegui) dal menu a sinistra e poi seleziona la scheda Arguments (Argomenti).
    3. Nella sezione Arguments Passed on Launch (Argomenti passati al momento dell'avvio), aggiungi -FIRDebugEnabled.

  3. Ottieni il token di debug:

    1. Apri ios/Runner.xcworkspace con Xcode ed esegui l'app nel simulatore o sul dispositivo di test.

    2. Apri la console Xcode e cerca il token di debug App Check. Ad esempio:

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

    3. Copia il token (ad esempio, 123a4567-b89c-12d3-e456-789012345678).

  4. Registra il token di debug con App Check:

    1. Nella console Firebase, vai alla scheda Sicurezza > App Check > App.

    2. Trova la tua app, fai clic sul menu extra () e poi seleziona Gestisci token di debug.

    3. Segui le istruzioni sullo schermo per registrare il token di debug.

Android

Ecco come utilizzare il provider di debug durante l'esecuzione dell'app in un emulatore in modo interattivo (ad esempio, durante lo sviluppo locale):

  1. Attiva App Check con il provider di debug subito dopo aver inizializzato l'app Firebase:

    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. Ottieni il token di debug:

    1. Esegui l'app nell'emulatore o sul dispositivo di test.

    2. Cerca il token di debug App Check nei log. Ad esempio:

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

    3. Copia il token (ad esempio, 123a4567-b89c-12d3-e456-789012345678).

  3. Registra il token di debug con App Check:

    1. Nella console Firebase, vai alla scheda Sicurezza > App Check > App.

    2. Trova la tua app, fai clic sul menu extra () e poi seleziona Gestisci token di debug.

    3. Segui le istruzioni sullo schermo per registrare il token di debug.

Web

Ecco come utilizzare il provider di debug durante l'esecuzione dell'app da localhost in modo interattivo (ad esempio, durante lo sviluppo locale):

  1. Nel file web/index.html, attiva la modalità di debug impostando self.FIREBASE_APPCHECK_DEBUG_TOKEN su true:

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

  ...

</body>

  2. Esegui l'app web in locale e apri gli strumenti per sviluppatori del browser. Nella console di debug, vedrai un token di debug:

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

    Questo token viene archiviato localmente nel browser e verrà utilizzato ogni volta che utilizzi l'app nello stesso browser sulla stessa macchina. Se vuoi utilizzare il token in un altro browser o su un'altra macchina, imposta self.FIREBASE_APPCHECK_DEBUG_TOKEN sulla stringa del token anziché true.

  3. Registra il token di debug con App Check:

    1. Nella console Firebase, vai alla scheda Sicurezza > App Check > App.

    2. Trova la tua app, fai clic sul menu extra () e poi seleziona Gestisci token di debug.

    3. Segui le istruzioni sullo schermo per registrare il token di debug.

Per informazioni dettagliate sul provider di debug (incluso come ottenere un nuovo token di debug), consulta la documentazione ufficiale di App Check.

Unity

Ecco come utilizzare il provider di debug durante l'esecuzione dell'app in un emulatore in modo interattivo (ad esempio, durante lo sviluppo locale):

  1. Nella console Firebase, crea un token di debug:

    1. Nella console Firebase, vai alla scheda Sicurezza > App Check > App.

    2. Trova la tua app, fai clic sul menu extra () e poi seleziona Gestisci token di debug.

    3. Segui le istruzioni sullo schermo per creare un nuovo token di debug.

  2. Nel codice di inizializzazione dell'app, aggiungi quanto segue:

    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
}

Per informazioni dettagliate sul provider di debug (incluso come ottenere un nuovo token di debug), consulta la documentazione ufficiale di App Check.

Passaggio 3: configura App Check per gli utenti finali e la produzione

Quando è tutto pronto per rilasciare l'app agli utenti finali, devi registrare le tue app e configurare un provider di attestazione di produzione (come App Attest, Play Integrity o reCAPTCHA Enterprise).

  1. Scegli un fornitore di attestazioni di produzione e segui le istruzioni di implementazione ai seguenti link:

    Tieni presente che se nessuno di questi fornitori di attestazione è sufficiente per le tue esigenze, puoi implementare un fornitore personalizzato che utilizzi un fornitore di attestazione di terze parti o le tue tecniche di attestazione.

  2. (Consigliato) Migliora la protezione aggiungendo la protezione di riproduzione, il che significa che un token App Check può essere utilizzato una sola volta.

Migliorare la protezione aggiungendo la protezione dal replay

Ti consigliamo di utilizzare le versioni più recenti dell'SDK, ma assicurati di utilizzare almeno una di queste versioni per utilizzare la protezione contro gli attacchi di replay:
Piattaforme 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+

Per impostazione predefinita, App Check utilizza token di sessione con un valore Time To Live (TTL) configurabile compreso tra 30 minuti e 7 giorni. Questi token di sessione vengono memorizzati nella cache dall'SDK App Check, vengono inviati insieme alle richieste della tua app e possono essere riutilizzati fino alla scadenza del TTL. L'utilizzo dei token di sessione è considerato una protezione di base.

Tuttavia, puoi migliorare la protezione oltre questa protezione di base applicando la protezione di riproduzione, che utilizza invece token a uso limitato. Quando viene applicata la protezione di riproduzione, si verifica quanto segue:

  • App Check bloccherà le richieste a Firebase AI Logic che utilizzano token di sessione. App Check consentirà solo una richiesta a Firebase AI Logic se utilizza un token a uso limitato appena creato.

  • Una volta verificato, il token a uso limitato viene consumato in modo che possa essere usato una sola volta, il che impedisce attacchi di tipo replay.

  • L'SDK App Check genera un nuovo token a uso limitato per ogni richiesta. Tieni presente che questo processo può influire sulle tue richieste aggiungendo un po' di latenza e a volte costi (a seconda del tuo fornitore di attestazioni).

Configurare e applicare la protezione di riproduzione

Fai clic sul tuo fornitore Gemini API per visualizzare i contenuti e il codice specifici del fornitore in questa pagina.

Ecco come configurare e applicare la protezione dalla riproduzione:

  1. Se non l'hai ancora fatto, configura App Check seguendo le istruzioni riportate in precedenza in questa pagina.

  2. Attiva l'utilizzo dei token a uso limitato.

    Nella tua app durante l'istanza, imposta il parametro useLimitedUseAppCheckTokens su 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. Applica la protezione di riproduzione.

    1. Nel codebase della tua app, assicurati di aver attivato l'utilizzo di token di uso limitato (vedi il passaggio precedente).

    2. Nella console Firebase, vai a Sicurezza > App Check.

    3. Espandi la visualizzazione delle metriche per Firebase AI Logic.

    4. Assicurati che Protezione di base sia Applicata, quindi fai clic su Continua.

    5. Per la protezione dalla riproduzione, scegli Non applicata (solo monitoraggio) o Applicata.

      Tieni presente quanto segue per decidere quando applicare la protezione dalla riproduzione:

      • Il monitoraggio delle richieste è consigliato se un numero considerevole di utenti utilizza probabilmente versioni precedenti della tua app senza l'utilizzo di token di uso limitato abilitato. Se applichi immediatamente la protezione dalla riproduzione, le richieste di questi utenti verranno bloccate.

      • Puoi monitorare in modo specifico la metrica Non verificato: token riutilizzato, ovvero il numero di richieste che hanno un token già utilizzato in una richiesta precedente. Monitora questa metrica nella console Firebase (vai alla scheda Sicurezza > App Check > API).

        Se una parte significativa delle richieste recenti rientra in questa categoria, puoi evitare di interrompere gli utenti e valutare la possibilità di attendere l'applicazione della protezione dal replay finché un numero maggiore di utenti non avrà eseguito l'aggiornamento a una versione della tua app che utilizza token di uso limitato.

Scopri come Firebase AI Logic si integra con App Check

Per utilizzare gli SDK Firebase AI Logic, l'API Firebase AI Logic (firebasevertexai.googleapis.com) deve essere attivata nel tuo progetto Firebase. Questo perché le richieste effettuate dagli SDK Firebase AI Logic vengono prima inviate al server Firebase AI Logic, che funge da gateway proxy in cui viene eseguita la verifica Firebase App Check prima che la richiesta possa procedere al backend del provider "Gemini API" scelto e alle API per accedere ai modelli Gemini e Imagen.

Domande frequenti e risoluzione dei problemi

Trova altre domande frequenti e risoluzione dei problemi o codici di errore relativi a Firebase AI Logic.