Scopri di più sull'utilizzo e sulla gestione delle chiavi API per Firebase

Una chiave API è una stringa univoca utilizzata per inoltrare le richieste al progetto Firebase quando interagisci con i servizi Firebase e Google. Questa pagina descrive informazioni di base sulle chiavi API, nonché best practice per l'utilizzo e la gestione delle chiavi API con le app Firebase.

Informazioni generali sulle chiavi API e su Firebase

Le chiavi API per Firebase sono diverse dalle chiavi API standard

A differenza di quanto avviene in genere con le chiavi API, le chiavi API per i servizi Firebase non vengono utilizzate per controllare l'accesso alle risorse di backend; questo può essere fatto solo con Firebase Security Rules (per controllare quali utenti finali possono accedere alle risorse) e Firebase App Check (per controllare quali app possono accedere alle risorse).

In genere, devi proteggere con attenzione le chiavi API (ad esempio, utilizzando un servizio di archiviazione o impostando le chiavi come variabili di ambiente); tuttavia, è possibile includere le chiavi API per i servizi Firebase nel codice o nei file di configurazione controllati.

Sebbene le chiavi API per i servizi Firebase siano sicure da includere nel codice, devi esaminare e applicare restrizioni e limiti appropriati.

Creazione di chiavi API

Un progetto Firebase può avere molte chiavi API, ma ogni chiave API può essere associata solo a un singolo progetto Firebase.

Chiavi API create automaticamente da Firebase per le tue app Firebase

Firebase crea automaticamente le chiavi API per il tuo progetto quando esegui una delle seguenti operazioni:

  • Crea un progetto Firebase > Browser key creato automaticamente
  • Crea un'app Apple Firebase > iOS key creata automaticamente
  • Crea un'app Firebase per Android > Android key creata automaticamente

Puoi anche creare le tue chiavi API nella console Google Cloud, ad esempio per lo sviluppo o il debug. Scopri di più su quando questa opzione potrebbe essere consigliata più avanti in questa pagina.

Trovare le chiavi API

Puoi visualizzare e gestire tutte le chiavi API del tuo progetto nel riquadro API e servizi > Credenziali della console Google Cloud.

Puoi anche trovare la chiave API associata automaticamente a un'app Firebase nei seguenti punti. Per impostazione predefinita, tutte le app Firebase del progetto per la stessa piattaforma (Apple, Android o web) utilizzeranno la stessa chiave API.

  • App per Apple di Firebase: trova la chiave API con corrispondenza automatica nel file di configurazione Firebase, GoogleService-Info.plist, nel campo API_KEY.

  • App per Android Firebase: trova la chiave API con corrispondenza automatica nel google-services.json, il file di configurazione di Firebase, nel current_key.

  • App web Firebase: trova la chiave API con corrispondenza automatica nell'oggetto di configurazione Firebase, nel campo apiKey.

Utilizzo di una chiave API

Le chiavi API vengono utilizzate per identificare il tuo progetto Firebase quando interagisci con i servizi Firebase/Google. Nello specifico, vengono utilizzati per associare le richieste API al tuo progetto per quota e fatturazione. Sono utili anche per accedere ai dati pubblici.

Ad esempio, puoi utilizzare esplicitamente una chiave API passando il relativo valore a una chiamata API REST come parametro di query. Questo esempio mostra come puoi effettuare una richiesta all'API di accorciamento dei link Dynamic Links:

POST https://firebasedynamiclinks.googleapis.com/v1/shortLinks?key=API_KEY

Quando la tua app effettua una chiamata a un'API Firebase che richiede una chiave API fornita dal client mobile/web, la tua app cercherà automaticamente la chiave API del progetto nell'oggetto/file di configurazione Firebase. Tuttavia, puoi fornire le chiavi API per la tua app utilizzando un altro meccanismo, tra cui le variabili di ambiente.

Esamina e applica le restrizioni appropriate alle chiavi API (opzione consigliata)

Sebbene non sia necessario trattare una chiave API per i servizi Firebase come un segreto, devi esaminare e applicare le limitazioni e i limiti descritti in questa sezione.

Esamina le API aggiunte automaticamente alla lista consentita per le tue chiavi API Firebase

Quando Firebase crea una chiave API nel tuo progetto, aggiungiamo automaticamente"limitazioni API" alla chiave. Le API aggiunte a questa lista consentita sono API correlate a Firebase che richiedono al client di fornire una chiave API insieme alla chiamata. Tieni presente che la maggior parte delle API richieste per l'utilizzo dei servizi Firebase non deve necessariamente essere presente nella lista consentita per le tue chiavi API.

Poiché Firebase aggiunge le API necessarie per tutti i servizi Firebase, la lista consentita per una chiave API potrebbe includere API per prodotti che non utilizzi. Puoi rimuovere le API dalla lista consentita, ma devi fare molta attenzione a non rimuovere le API richieste per Firebase e per i servizi Firebase che utilizzi (consulta l'elenco delle API correlate a Firebase che devono essere incluse nella lista consentita per ogni servizio / prodotto). In caso contrario, riceverai errori quando effettui chiamate ai servizi Firebase.

Se utilizzi Authentication basato su password, riduci la quota

Se utilizzi Firebase Authentication basato su password e qualcuno ottiene la tua chiave API, non potrà accedere al database o ai dati Cloud Storage del tuo progetto Firebase a condizione che questi dati siano protetti da Firebase Security Rules. Tuttavia, potrebbero utilizzare la tua chiave API per accedere agli endpoint di autenticazione di Firebase e inviare richieste di autenticazione per il tuo progetto.

Per ridurre la possibilità che qualcuno possa utilizzare impropriamente una chiave API per tentare un attacco di forza bruta, puoi restringere la quota predefinita degli endpoint identitytoolkit.googleapis.com in modo che rifletta le normali aspettative di traffico della tua app. Tieni presente che, se restringi questa quota e la tua app guadagna improvvisamente utenti, potresti ricevere errori di accesso finché non aumenti la quota. Puoi modificare le quote API del progetto nella console Google Cloud.

Utilizzare chiavi API separate e con limitazioni per qualsiasi servizio non Firebase

Sebbene in genere le chiavi API utilizzate per i servizi Firebase non debbano essere trattate come segrete, devi adottare alcune precauzioni aggiuntive per le chiavi API che utilizzi con altre API Google Cloud.

Se utilizzi un'API Google Cloud (su qualsiasi piattaforma) non destinata a un servizio / prodotto Firebase, ti consigliamo vivamente di creare chiavi API separate e limitate da utilizzare con queste API. Ciò è particolarmente importante se l'API è per un servizio Google Cloud fatturabile.

Ad esempio, se utilizzi Firebase ML e le API Cloud Vision su iOS, devi creare chiavi API separate da utilizzare solo per accedere alle API Cloud Vision.

Utilizzando chiavi API separate e limitate per le API non Firebase, puoi ruotare o sostituire le chiavi in caso di necessità e aggiungere ulteriori limitazioni alle chiavi API senza interrompere l'utilizzo dei servizi Firebase.

Queste istruzioni descrivono come creare una chiave API separata con limitazioni per un'API falsificata denominata Super Service API.

Passaggio 1: configura le chiavi API esistenti per non consentire l'accesso a Super Service API

  1. Apri la pagina Credenziali della console Google Cloud. Quando richiesto, seleziona il tuo progetto.

  2. Per ogni chiave API esistente nell'elenco, apri la visualizzazione di modifica.

  3. Nella sezione Restrizioni delle API, seleziona Limita chiave, quindi aggiungi all'elenco tutte le API a cui vuoi che la chiave API abbia accesso. Assicurati di non includere l'API per la quale stai creando una chiave API separata (in questo esempio, Super Service API).

    Quando configuri le limitazioni delle API di una chiave API, dichiari esplicitamente le API a cui la chiave ha accesso. Per impostazione predefinita, quando nella sezione Restrizioni delle API è selezionata l'opzione Non limitare la chiave, una chiave API può essere utilizzata per accedere a qualsiasi API abilitata per il progetto.

Ora le tue chiavi API esistenti non concederanno l'accesso a Super Service API, ma ogni chiave continuerà a funzionare per tutte le API che hai aggiunto all'elenco delle limitazioni delle API.

Passaggio 2: crea e utilizza una nuova chiave API per accedere a Super Service API

  1. Torna alla pagina Credenziali. Assicurati che il progetto Firebase sia ancora selezionato.

  2. Fai clic su Crea credenziali > Chiave API. Prendi nota della nuova chiave API, quindi fai clic su Limita chiave.

  3. Nella sezione Restrizioni delle API, seleziona Limita chiave e poi aggiungi Super Service API all'elenco solo.

    Questa nuova chiave API concede l'accesso solo a Super Service API.

  4. Configura l'app e i servizi in modo che utilizzino la nuova chiave API.

Utilizza chiavi API specifiche per l'ambiente (opzione consigliata)

Se configuri progetti Firebase diversi per ambienti diversi, come la gestione temporanea e la produzione, è importante che ogni istanza dell'app interagisca con il progetto Firebase corrispondente. Ad esempio, l'istanza dell'app di staging non deve mai comunicare con il progetto Firebase di produzione. Ciò significa anche che la tua app di staging deve utilizzare le chiavi API associate al progetto Firebase di staging.

Per ridurre i problemi di promozione delle modifiche al codice dallo sviluppo allo staging alla produzione, anziché includere le chiavi API nel codice stesso, impostale come variabili di ambiente o includile in un file di configurazione.

Tieni presente che se utilizzi Firebase Local Emulator Suite per lo sviluppo insieme a Firebase ML, devi creare e utilizzare una chiave API solo per il debug. Le istruzioni per creare questo tipo di chiave sono riportate nella documentazione di Firebase ML.

Domande frequenti e risoluzione dei problemi

Domande frequenti

Sì, per impostazione predefinita, a tutte le chiavi API di cui Firebase esegue il provisioning automatico per l'utilizzo con le API correlate a Firebase vengono applicate automaticamente le "Restrizioni API". Consulta l'elenco delle API correlate a Firebase presenti in questa lista consentita.

Le API aggiunte a questa lista consentita sono quelle chiamate dai servizi Firebase dal codice client e richiedono chiavi API per l'identificazione del progetto o dell'app Firebase. Tieni presente che la maggior parte delle API richieste per l'utilizzo dei servizi Firebase non deve necessariamente essere presente nella lista consentita per le tue chiavi API.

Poiché Firebase aggiunge le API necessarie per tutti i servizi Firebase, la lista consentita per una chiave API potrebbe includere API per prodotti che non utilizzi. Puoi rimuovere le API dalla lista consentita, ma devi fare molta attenzione a non rimuovere le API richieste per Firebase e per i servizi Firebase che utilizzi (consulta l'elenco delle API correlate a Firebase che devono essere incluse nella lista consentita per ogni servizio / prodotto). In caso contrario, riceverai errori quando effettui chiamate ai servizi Firebase.

Puoi visualizzare tutte le tue chiavi API e le relative "limitazioni API" nel riquadro API e servizi > Credenziali nella console Google Cloud.

Tieni presente quanto segue su come Firebase applica queste "limitazioni dell'API":

  • A partire da maggio 2024, tutte le nuove chiavi API di cui è stato eseguito il provisioning automatico da Firebase sono automaticamente limitate all'elenco delle API correlate a Firebase.

  • A partire da maggio 2024, tutte le chiavi API esistenti e senza restrizioni di cui Firebase aveva eseguito precedentemente il provisioning automatico saranno limitate all'elenco delle API correlate a Firebase più a qualsiasi API attualmente abilitata del progetto.

  • Le chiavi API esistenti e già soggette a restrizioni di cui Firebase aveva eseguito in precedenza il provisioning automatico non sono state modificate.

  • Le eventuali chiavi API esistenti di cui non è stato eseguito il provisioning automatico da parte di Firebase non sono state modificate.

Puoi utilizzare una delle seguenti opzioni per determinare quale chiave API è associata alla tua app Firebase:

  1. Vai a Impostazioni progetto, quindi scorri verso il basso fino alla scheda Le tue app.

  2. Seleziona l'app che ti interessa.

  3. Ottieni l'oggetto/il file di configurazione Firebase per l'app che ti interessa, quindi individua la relativa chiave API:

    • Apple: scarica il GoogleService-Info.plist e individua il campo API_KEY

    • Android: scarica il file google-services.json, individua la configurazione per l'app di interesse (cerca il nome del pacchetto) e poi individua il campo current_key

    • Web: seleziona l'opzione Config e individua il campo apiKey

  1. Ottieni l'oggetto/il file di configurazione di Firebase per l'app di interesse eseguendo il seguente comando:

    firebase apps:sdkconfig PLATFORM FIREBASE_APP_ID
    • PLATFORM (uno dei seguenti): IOS | ANDROID | WEB
    • FIREBASE_APP_ID: l'identificatore univoco assegnato da Firebase per la tua app Firebase (trova il tuo ID app)
  2. Nella configurazione Firebase stampata dell'app, trova la relativa chiave API:

    • Apple: trova il campo API_KEY

    • Android: individua la configurazione dell'app di interesse (cerca il nome del pacchetto) e poi il campo current_key

    • Web: trova il campo apiKey

  1. Ottieni il valore apiKeyId (UID) della chiave API chiamando l'endpoint applicabile per l'app di interesse e poi passando il valore apiKeyId al passaggio successivo.

  2. Ottieni la stringa della chiave API chiamando projects.locations.keys.getKeyString.

    Questo keyString è lo stesso valore che puoi trovare nell'elemento di configurazione dell'app (Apple | Android | Web).

  • App Apple Firebase: ogni app ha il proprio file di configurazione e può avere elencata una sola chiave API.

  • App per Android di Firebase: tutte le app per Android nel progetto Firebase sono elencate nello stesso file di configurazione e ogni app può avere una sola chiave API elencata. Tuttavia, ogni app in questo file di configurazione può avere una chiave diversa elencata.

  • App web di Firebase: ogni app ha il proprio oggetto di configurazione e può avere elencata una sola chiave API.

Tuttavia, puoi utilizzare più chiavi API con un'app. Devi fornire un meccanismo per consentire alla tua app di accedere a queste altre chiavi API, ad esempio tramite una variabile di ambiente. Il meccanismo per accedere alle altre chiavi API non può dipendere dalle chiavi API elencate nell'oggetto/file di configurazione di Firebase.

Quando ottieni per la prima volta l'oggetto/il file di configurazione Firebase della tua app, Firebase controlla se nel tuo progetto sono presenti chiavi API con "Restrizioni per le applicazioni" corrispondenti all'app (ad esempio un ID bundle corrispondente per l'app Apple).

Se Firebase non trova chiavi limitate corrispondenti, nell'oggetto/file di configurazione verranno elencate le chiavi iOS key per le app Apple, Android key per le app Android e Browser key per le app web (supponendo che queste chiavi esistano e non abbiano "limitazioni per le applicazioni" che ne impediscono la corrispondenza all'app).

Sì, puoi eliminare manualmente la chiave API dall'oggetto/dal file di configurazione. Tuttavia, devi fornire un altro meccanismo per consentire alla tua app di accedere a una chiave API (ad esempio tramite una variabile di ambiente). In caso contrario, tutte le chiamate ai servizi Firebase non andranno a buon fine.

Sì, puoi modificare manualmente un file/oggetto di configurazione per associare una chiave API diversa a un'app.

Tieni presente che se recuperi di nuovo l'oggetto/il file di configurazione dell'app dalla console, verranno sempre elencate le chiavi API che Firebase abbina automaticamente all'app. Pertanto, dovrai ripetere le modifiche manuali, se necessario.

No, una chiave API identifica solo un progetto specifico e non può essere spostata in un altro progetto.

Se elimini una chiave API in uso da un'app, le chiamate API da quell'app non andranno a buon fine. Potresti ricevere report, email o errori che indicano che stai tentando di utilizzare una chiave API non valida.

L'eliminazione di una chiave API è definitiva e non può essere annullata.

Per una chiave API Firebase, le uniche API che devono essere presenti nella lista consentita "Restrizioni API" della chiave sono quelle che richiedono al client di fornire una chiave API insieme alla chiamata. Tieni presente che pochissime API correlate a Firebase hanno questo requisito. La maggior parte delle API correlate a Firebase attivate nel progetto non deve essere presente nella lista consentita "Restrizioni API" della chiave.

Utilizza la tabella seguente per determinare quali API correlate a Firebase devono essere incluse nella lista consentita "Restrizioni API" per una chiave API Firebase. Ricorda che le chiavi API di Firebase devono essere utilizzate solo per i servizi Firebase. Scopri di più sulla creazione di chiavi API separate e con limitazioni per tipi specifici di API.

Puoi visualizzare e gestire le chiavi API del tuo progetto nel riquadro API e servizi > Credenziali nella console Google Cloud.

Nome API (nome del servizio) Nome visualizzato dell'API
Servizio / prodotto Firebase
associato
firebase.googleapis.com API Firebase Management tutti i prodotti
logging.googleapis.com API Cloud Logging tutti i prodotti
firebaseinstallations.googleapis.com API Firebase Installations Cloud Messaging, Crashlytics, In-App Messaging, Performance Monitoring, Remote Config, Firebase ML
firebaseappcheck.googleapis.com API Firebase App Check App Check
firebaseappdistribution.googleapis.com API Firebase App Distribution App Distribution
firebaseapptesters.googleapis.com API Firebase App Testers App Distribution
identitytoolkit.googleapis.com API Identity Toolkit Authentication
securetoken.googleapis.com API Token Service Authentication
firebaserules.googleapis.com * API Firebase Rules Cloud Firestore, Cloud Storage, Realtime Database
datastore.googleapis.com API Cloud Datastore Cloud Firestore
firestore.googleapis.com API Google Cloud Firestore Cloud Firestore
fcmregistrations.googleapis.com API FCM Registration Cloud Messaging
firebasestorage.googleapis.com API Cloud Storage for Firebase Cloud Storage
firebasedynamiclinks.googleapis.com API Firebase Dynamic Links Dynamic Links
firebasehosting.googleapis.com * API Firebase Hosting Hosting
firebaseinappmessaging.googleapis.com API Firebase In-App Messaging In-App Messaging
firebaseml.googleapis.com API Firebase ML Firebase ML
mlkit.googleapis.com ** API ML Kit Firebase ML
mobilecrashreporting.googleapis.com Mobile Crash Reporting API Performance Monitoring
play.googleapis.com API Google Play Android Developer Performance Monitoring
firebaseremoteconfig.googleapis.com API Firebase Remote Config Performance Monitoring, Remote Config
firebaseremoteconfigrealtime.googleapis.com API Firebase Remote Config in tempo reale Performance Monitoring, Remote Config
cloudconfig.googleapis.com ** N/D Remote Config
firebasedatabase.googleapis.com * API Firebase Realtime Database Realtime Database
firebasevertexai.googleapis.com API Vertex AI in Firebase Vertex AI in Firebase

* Obbligatorio solo se utilizzi la chiave API Firebase con strumenti di terze parti o con accesso REST diretto al servizio / prodotto Firebase.

** Obbligatorio per le versioni precedenti dell'SDK del prodotto. Se utilizzi la versione più recente dell'SDK, l'API non deve essere presente nella lista consentita della chiave.

Risoluzione dei problemi

Segui le indicazioni riportate in queste domande frequenti se ricevi un messaggio di errore API_KEY_SERVICE_BLOCKED o un messaggio di errore simile al seguente:

Forbidden: 403 POST https://example-service.googleapis.com/method: Requests to this API example-service.googleapis.com method google.example-service.rest.method are blocked.

È probabile che alla chiave API utilizzata dalla tua app per chiamare l'API siano state applicate "limitazioni API" e che la lista consentita della chiave non includa l'API.

È probabile che alla chiave API utilizzata dalla tua app web siano state applicate le "limitazioni API". In questo caso, assicurati che l'API Firebase Management sia presente nell'elenco delle API consentite.

Di seguito sono riportate alcune delle cause più comuni di chiavi API non valide:

  • Alla chiave API sono state applicate "Restrizioni relative alle chiavi API" che la rendono non corrispondente all'app che tenta di utilizzarla ("Restrizioni delle applicazioni") o inutilizzabile per l'API chiamata ("Restrizioni API").

  • La chiave API è stata eliminata dal progetto nella console Google Cloud.

  • La chiave API non è stata creata per l'ID progetto elencato nell'oggetto/file di configurazione Firebase dell'app.

Un modo per risolvere il problema è ottenere la versione aggiornata dell'oggetto/del file di configurazione Firebase della tua app, quindi sostituire l'oggetto/il file di configurazione precedente con l'oggetto/il file aggiornato. Prima di inviare un file di configurazione per il download o di visualizzare un oggetto di configurazione nella console, Firebase controlla che le chiavi API elencate corrispondano alle app.