Linee guida per la sicurezza di Google Maps Platform

Le app e i progetti che utilizzano le API e gli SDK di Google Maps Platform devono utilizzare chiavi API o, se supportato, OAuth 2.0 per autenticarsi.

Queste best practice mostrano come proteggere l'accesso a Maps Platform.

Se vuoi utilizzare OAuth 2.0 per autorizzare il traffico server-to-server, cerca l'argomento OAuth nella documentazione dell'API. Per maggiori dettagli, consulta l'articolo Utilizzare OAuth per le app lato server.

Oltre ad applicare le limitazioni delle applicazioni e delle chiavi API, segui le pratiche di sicurezza che si applicano a prodotti Google Maps Platform specifici. Ad esempio, vedi l'API Maps JavaScript di seguito in Limitazioni consigliate per applicazioni e API.

Se le tue chiavi API sono già in uso, consulta i suggerimenti riportati di seguito in Se stai limitando una chiave API in uso.

Per maggiori dettagli sulle firme digitali supportate dalle API Maps Static e Street View Static, consulta la guida alle firme digitali.

Best practice consigliate

Per una maggiore sicurezza ed evitare addebiti per utilizzo non autorizzato, segui queste best practice per la sicurezza delle API per tutte le API, gli SDK o i servizi Google Maps Platform:

Limitare le chiavi API

Utilizza chiavi API separate per ogni app

Elimina le chiavi API inutilizzate

Controllare l'utilizzo della chiave API

Fai attenzione quando ruoti le chiavi API

Dividere l'utilizzo lato client e lato server in progetti separati

Disattivare i servizi non utilizzati

Altri consigli per le app lato client

Utilizzare gli SDK lato client

Chiamate sicure ai servizi web lato client

Altri consigli per siti web o app lato client che utilizzano le API web statiche

Proteggere l'utilizzo dell'API Static Web

Altri suggerimenti per le app lato server che utilizzano servizi web

Proteggere le chiavi API del servizio web

Utilizzare OAuth per le app lato server

Se stai limitando o ruotando una chiave API in uso

  • Prima di modificare la chiave API, controlla l'utilizzo della chiave API. Questo passaggio è particolarmente importante se stai aggiungendo limitazioni per una chiave già in uso in un'applicazione di produzione.

  • Dopo aver modificato la chiave, aggiorna tutte le tue app con le nuove chiavi API, se necessario.

  • Se la tua chiave API non è stata compromessa e non viene utilizzata in modo illecito, puoi eseguire la migrazione delle tue app a più chiavi API nuove al tuo ritmo, lasciando intatta la chiave API originale finché non osservi un solo tipo di traffico e la chiave API può essere limitata in modo sicuro con un solo tipo di limitazioni dell'applicazione senza causare interruzioni del servizio non intenzionali.

    Per ulteriori istruzioni, vedi Eseguire la migrazione a più chiavi API.

    Monitora l'utilizzo nel tempo e scopri quando API, tipi di piattaforma e domini specifici sono stati migrati dalla vecchia chiave API prima di scegliere di limitare o eliminare la vecchia chiave. Per saperne di più, consulta Report e monitoraggio e Metriche.

  • Se la tua chiave API è stata compromessa, vuoi passare più rapidamente a proteggerla e interrompere l'abuso. Nelle app per Android e iOS, le chiavi non vengono sostituite finché i clienti non aggiornano le app. L'aggiornamento o la sostituzione delle chiavi nelle pagine web o nelle app lato server è molto più semplice, ma potrebbe comunque richiedere una pianificazione attenta e un lavoro rapido.

    Per saperne di più, consulta Gestire l'utilizzo non autorizzato di una chiave API.

Ulteriori informazioni

Limitazioni consigliate per applicazioni e API

Limitare le chiavi API

La best practice prevede di limitare sempre le chiavi API con un tipo di limitazioni dell'applicazione e una o più limitazioni delle API. Per le limitazioni suggerite per API, SDK o servizio JavaScript, consulta la sezione Limitazioni consigliate per applicazioni e API di seguito.

  • Limitazioni delle applicazioni Puoi limitare l'utilizzo di una chiave API a piattaforme specifiche: app per Android o iOS, siti web specifici per applicazioni lato client o indirizzi IP o subnet CIDR specifici per app lato server che effettuano chiamate API REST del servizio web.

    Limiti una chiave aggiungendo una o più limitazioni delle applicazioni dei tipi che vuoi autorizzare, dopodiché sono consentite solo le richieste provenienti da queste origini.

  • Restrizioni delle API: puoi limitare le API, gli SDK o i servizi di Google Maps Platform su cui può essere utilizzata la chiave API. Le limitazioni delle API consentono solo le richieste alle API e agli SDK specificati. Per ogni chiave API, puoi specificare tutte le limitazioni delle API necessarie. L'elenco delle API disponibili include tutte le API abilitate in un progetto.

Impostare una limitazione delle applicazioni per una chiave API

  1. Apri la pagina Credenziali di Google Maps Platform della console Google Cloud.

  2. Seleziona la chiave API che vuoi limitare.

  3. Nella pagina Modifica chiave API, in Limitazioni della chiave, seleziona Imposta una limitazione dell'applicazione.

    Modifica pagina della chiave API

  4. Seleziona uno dei tipi di limitazione e fornisci le informazioni richieste seguendo l'elenco delle limitazioni.

    Tipo di restrizione Descrizione
    Siti web Specifica uno o più siti web referrer.
    • Gli schemi URI referrer supportati universalmente sono https e http. Non è garantito che altri schemi funzionino correttamente, poiché i browser web moderni non inviano un'intestazione "Referer" nelle richieste in uscita per motivi di privacy.
    • Fornisci sempre la stringa referrer intera, inclusi lo schema del protocollo, il nome host e la porta facoltativa (ad es. https://google.com).
    • Puoi utilizzare i caratteri jolly per autorizzare tutti i sottodomini. Ad esempio, https://*.google.com accetta tutti i siti che terminano con .google.com.
    • Fai attenzione quando autorizzi i referrer con percorso completo, ad esempio https://google.com/some/path, poiché la maggior parte dei browser web rimuove il percorso dalle richieste multiorigine per motivi di privacy.
    Indirizzi IP Specifica uno o più indirizzi IPv4 o IPv6 oppure subnet utilizzando la notazione CIDR. Gli indirizzi IP devono corrispondere all'indirizzo di origine osservato dai server di Google Maps Platform. Se utilizzi la Network Address Translation (NAT), questo indirizzo corrisponde in genere all'indirizzo IP pubblico della tua macchina.
    App Android

    Aggiungi il nome del pacchetto Android (dal file AndroidManifest.xml) e l'impronta del certificato di firma SHA-1 di ogni applicazione Android che vuoi autorizzare.

    1. Seleziona App per Android.
    2. Fai clic su + Aggiungi.
    3. Inserisci il nome del pacchetto e l'impronta del certificato SHA-1. Ad esempio: 
      com.example.android.mapexample
       
      BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75
    4. Fai clic su Salva.

    Esistono due tipi di certificati:

    • Certificato di debug: utilizza questo tipo di certificato solo con le app che stai testando e con altro codice non di produzione. Non tentare di pubblicare un'app firmata con un certificato di debug. Gli strumenti dell'SDK Android generano automaticamente questo certificato quando esegui una build di debug.
    • Certificato di rilascio: utilizza questo certificato quando è tutto pronto per rilasciare l'app in uno store. Gli strumenti Android SDK generano questo certificato quando esegui una build di rilascio.

    Per maggiori informazioni su certificati e firma dell'applicazione Android, consulta la guida Firma dell'app.

    Se utilizzi la firma dell'app di Google Play, per recuperare la fingerprint del certificato di firma, consulta Utilizzo dei fornitori di API. Se gestisci la tua chiave di firma, consulta Firma automatica dell'applicazione o fai riferimento alle istruzioni per il tuo ambiente di build.
    App per iOS

    Aggiungi l'identificatore bundle di ogni applicazione iOS che vuoi autorizzare.

    1. Seleziona App per iOS.
    2. Fai clic su + Aggiungi.
    3. Aggiungi l'ID bundle per accettare le richieste dall'app per iOS con questo ID.
    4. Fai clic su Salva.

    Per consigli su una limitazione dell'applicazione, vedi Limitazione dell'applicazione consigliata.

  5. Seleziona Salva.

Impostare le limitazioni delle API per una chiave API

  1. Apri la pagina Credenziali di Google Maps Platform della console Google Cloud.

  2. Seleziona la chiave API che vuoi limitare.

  3. Nella pagina Modifica chiave API, nella sezione Limitazioni delle API:

    • Seleziona Limita chiave.

    • Apri Seleziona API e seleziona le API o gli SDK a cui vuoi che la tua applicazione acceda utilizzando la chiave API.

    Se un'API o un SDK non è elencato, devi abilitarlo. Per maggiori dettagli, vedi Per attivare una o più API o SDK.

    Limitare un'API nella pagina Modifica chiave API

  4. Seleziona Salva.

    Dopo questo passaggio, la limitazione diventa parte della definizione della chiave API. Assicurati di fornire i dettagli appropriati e seleziona Salva per salvare le limitazioni della chiave API. Per ulteriori informazioni, consulta la guida Ottenere una chiave API nella documentazione dell'API o dell'SDK specifico di tuo interesse.

Per le limitazioni delle API consigliate, consulta la sezione Limitazioni delle API consigliate.

Controllare l'utilizzo della chiave API

Se limiti le chiavi API dopo la loro creazione o se vuoi vedere quali API vengono utilizzate da una chiave per poterle limitare, devi controllare l'utilizzo delle chiavi API. Questi passaggi mostrano in quali servizi e metodi API viene utilizzata una chiave API. Se noti un utilizzo che va oltre i servizi di Google Maps Platform, esamina la situazione per determinare se devi aggiungere ulteriori restrizioni per evitare un utilizzo indesiderato. Puoi utilizzare l'explorer delle metriche della console Google Cloud di Google Maps Platform per determinare quali restrizioni delle API e delle applicazioni applicare alla tua chiave API:

Determinare le API che utilizzano la tua chiave API

I seguenti report sulle metriche ti consentono di determinare quali API utilizzano le tue chiavi API. Utilizza questi report per:

  • Visualizzare come vengono utilizzate le chiavi API
  • Individuare utilizzi imprevisti
  • Aiuta a verificare se una chiave inutilizzata può essere eliminata in sicurezza. Per informazioni sull'eliminazione di una chiave API, vedi Eliminare le chiavi API inutilizzate.

Quando applichi le restrizioni delle API, utilizza questi report per creare un elenco di API da autorizzare o per convalidare i suggerimenti per le restrizioni delle chiavi API generati automaticamente. Per ulteriori informazioni sulle limitazioni consigliate, vedi Applicare le limitazioni consigliate. Per ulteriori informazioni sull'utilizzo di Esplora metriche, vedi Creare grafici con Esplora metriche .

  1. Vai a Esplora metriche nella console Google Cloud.

  2. Accedi e seleziona il progetto per le chiavi API che vuoi controllare.

  3. Vai alla pagina Esplora metriche per il tuo tipo di API:

    • Per le chiavi API che utilizzano qualsiasi API tranne l'API Maps Embed: vai alla pagina Explorer metriche.

    • Per le chiavi API che utilizzano l'API Maps Embed: vai a Explorer metriche.

  4. Controlla ogni chiave API:

    1. Seleziona AGGIUNGI FILTRO.

    2. Seleziona l'etichetta credential_id.

    3. Seleziona il valore corrispondente alla chiave che vuoi esaminare.

    4. Prendi nota delle API per cui viene utilizzata questa chiave API e conferma che l'utilizzo sia previsto.

    5. Al termine, seleziona Rimuovi filtro alla fine della riga del filtro attivo per eliminare il filtro aggiuntivo.

  5. Ripeti l'operazione per tutti i tasti rimanenti.

  6. Limita le chiavi API solo alle API utilizzate.

  7. Se noti un utilizzo non autorizzato, consulta Gestire l'utilizzo non autorizzato di una chiave API.

Scegliere il tipo corretto di limitazione dell'applicazione utilizzando Metrics Explorer

Dopo aver verificato e intrapreso le azioni necessarie per assicurarti che la chiave API venga utilizzata solo per i servizi Google Maps Platform che utilizza, verifica anche che la chiave API abbia le limitazioni di applicazione corrette.

Se la tua chiave API ha limitazioni consigliate, applicale. Per ulteriori informazioni, vedi Applicare le limitazioni consigliate per le chiavi API.

Se la tua chiave API non ha suggerimenti sulle limitazioni, determina il tipo di limitazione dell'applicazione da applicare in base al valore platform_type segnalato utilizzando l'Explorer metriche:

  1. Vai a Esplora metriche nella console Google Cloud.

  2. Accedi e seleziona il progetto per le API che vuoi controllare.

  3. Vai alla pagina Esplora metriche: Esplora metriche.

  4. Controlla ogni chiave API:

    1. Seleziona AGGIUNGI FILTRO.

    2. Seleziona l'etichetta credential_id.

    3. Seleziona il valore corrispondente alla chiave che vuoi esaminare.

    4. Al termine, seleziona Rimuovi filtro alla fine della riga del filtro attivo per eliminare il filtro aggiuntivo.

  5. Ripeti l'operazione per tutti i tasti rimanenti.

  6. Una volta ottenuto il tipo di piattaforma per le tue chiavi API, applica la limitazione dell'applicazione per platform_type:

    PLATFORM_TYPE_JS : applica le limitazioni relative ai siti web alla chiave.

    PLATFORM_TYPE_ANDROID : applica le limitazioni delle applicazioni per Android alla chiave.

    PLATFORM_TYPE_IOS : applica le limitazioni delle applicazioni iOS alla chiave.

    PLATFORM_TYPE_WEBSERVICE : potresti dover fare affidamento sulle limitazioni dell'indirizzo IP della chiave per limitarla correttamente.

    Per i consigli relativi all'API Maps Static e all'API Street View Static, consulta Proteggere l'utilizzo dell'API Static Web.

    Per i consigli sull'API Maps Embed, consulta la pagina Siti web con l'API Maps Embed.

    La mia chiave API utilizza più tipi di piattaforma: Il tuo traffico non può essere protetto correttamente con una sola chiave API. Devi eseguire la migrazione a più chiavi API. Per maggiori informazioni, consulta la pagina Eseguire la migrazione a più chiavi API.

Utilizzare chiavi API separate per ogni app

Questa pratica limita l'ambito di ogni chiave. Se una chiave API viene compromessa, puoi eliminare o ruotare la chiave interessata senza dover aggiornare le altre chiavi API. Puoi creare fino a 300 chiavi API per progetto. Per ulteriori informazioni, consulta Limiti delle chiavi API.

Sebbene una chiave API per applicazione sia l'ideale per motivi di sicurezza, puoi utilizzare chiavi con limitazioni su più app, a condizione che utilizzino lo stesso tipo di limitazione delle applicazioni.

Applica le limitazioni consigliate per le chiavi API

Per alcuni proprietari, editor e amministratori di chiavi API di progetti, la console Google Cloud suggerisce restrizioni specifiche per le chiavi API senza restrizioni in base all'utilizzo e all'attività di Google Maps Platform.

Se disponibili, i consigli vengono visualizzati come opzioni precompilate nella pagina Credenziali Google Maps Platform.

API e SDK Google Maps Platform supportati dai suggerimenti automatici

  • API Maps JavaScript, inclusi Directions Service (legacy), Distance Matrix Service (legacy), Elevation Service, Geocoding Service Classe Place, Widget Place Autocomplete (nuovo), API Place Autocomplete Data, Places Library, Places Service, Widget Place Autocomplete e Places UI Kit

  • API Maps Static e API Street View Static

  • API Maps Embed

  • Maps SDK for Android, Navigation SDK for Android, Places SDK for Android e Places UI Kit su Android

  • Maps SDK for iOS, Navigation SDK for iOS, Places SDK for iOS, Places Swift SDK for iOS e Places UI Kit su iOS.

Motivi per cui potresti non visualizzare un consiglio o visualizzarne uno incompleto

Motivi per cui non vengono visualizzati consigli

  • Stai utilizzando la chiave API anche su servizi diversi da Google Maps Platform o su servizi di Maps Platform non ancora supportati dai suggerimenti automatici.

    Se noti un utilizzo su altri servizi, non applicare il suggerimento senza prima fare quanto segue:

    1. Verifica che l'utilizzo dell'API visualizzato in Metrics Explorer della console Google Cloud sia legittimo.

    2. Aggiungi manualmente i servizi mancanti all'elenco delle API da autorizzare.

    3. Aggiungi manualmente le eventuali limitazioni delle applicazioni mancanti per i servizi aggiunti all'elenco delle API. Se l'altra app aggiunta richiederebbe un tipo diverso di limitazioni dell'applicazione, consulta Migrazione a più chiavi API.

  • La chiave API non viene utilizzata in API o SDK lato client.

  • Utilizzi la chiave API in un'app o un sito web a basso volume che non è stato utilizzato negli ultimi 60 giorni.

  • Hai creato una nuova chiave di recente o hai eseguito il deployment di una chiave esistente in una nuova app. In questo caso, attendi qualche giorno per consentire l'aggiornamento dei consigli.

  • Stai utilizzando la chiave API in più applicazioni che richiederebbero tipi di limitazioni delle applicazioni in conflitto o stai utilizzando la stessa chiave API in troppe app o siti web diversi. In entrambi i casi, come best practice, devi eseguire la migrazione a più chiavi. Per maggiori dettagli, vedi Eseguire la migrazione a più chiavi API.

Motivi per cui potresti visualizzare un consiglio incompleto

  • Utilizzi la chiave API in un'app o un sito web a basso volume che non è stato utilizzato negli ultimi 60 giorni.

  • Hai iniziato di recente a utilizzare una chiave esistente su una nuova API o un nuovo servizio e la pipeline di suggerimenti per la limitazione automatica delle chiavi API non ha ancora elaborato le metriche di utilizzo aggiornate. La propagazione delle metriche di utilizzo può richiedere alcuni giorni.

    Se noti un utilizzo su altri servizi, non applicare il suggerimento senza prima fare quanto segue:

    1. Verifica che l'utilizzo dell'API visualizzato in Metrics Explorer della console Google Cloud sia legittimo.

    2. Aggiungi manualmente i servizi mancanti all'elenco delle API da autorizzare.

    3. Aggiungi manualmente le eventuali limitazioni delle applicazioni mancanti per i servizi aggiunti all'elenco delle API. Se l'altra app aggiunta richiederebbe un tipo diverso di limitazioni dell'applicazione, consulta Migrazione a più chiavi API.

    4. A meno che tu non abbia urgentemente bisogno di limitare una chiave, ad esempio a causa di un utilizzo non autorizzato, potresti anche attendere un giorno o due prima che i consigli vengano aggiornati.

Motivi per cui potresti visualizzare consigli non visibili nei grafici

  • La tua app o il tuo sito web ha inviato solo picchi di traffico molto brevi. In questo caso, passa dalla visualizzazione GRAFICO per visualizzare una TABELLA o ENTRAMBE, poiché l'utilizzo è ancora visibile nella legenda. Per ulteriori informazioni, vedi Attivare/disattivare le legende complete del grafico.

  • Il tuo traffico proviene dall'API Maps Embed. Per istruzioni, consulta l'articolo Determinare le API che utilizzano la tua chiave API.

  • Il traffico dall'app o dal sito web non rientra nell'intervallo di date disponibile in Esplora metriche della console Google Cloud.

  1. Apri la pagina Credenziali di Google Maps Platform della console Google Cloud.

  2. Se disponibile, seleziona Applica limitazioni consigliate.

    Applica limitazioni consigliate

  3. Seleziona Controlla l'utilizzo dell'API per verificare su quali servizi viene utilizzata la chiave API. Se vedi servizi diversi da Google Maps Platform, metti in pausa per esaminare manualmente i passaggi del suggerimento riportati sopra. Consulta i passaggi per la risoluzione dei problemi all'inizio della sezione Applica le limitazioni consigliate per le chiavi API.

  4. Verifica che le limitazioni precompilate corrispondano ai siti web e alle app in cui prevedi di utilizzare la chiave API.

    Best practice: documenta e rimuovi eventuali limitazioni di applicazioni o API che non sono affiliate ai tuoi servizi. Se qualcosa si interrompe a causa di una dipendenza imprevista, puoi aggiungere di nuovo le app o le API richieste.

    • Se ti accorgi che un'app, un sito web o un'API manca chiaramente dal tuo consiglio, aggiungilo manualmente o attendi un paio di giorni per consentire l'aggiornamento del consiglio.

    • Se hai bisogno di ulteriore aiuto per il suggerimento consigliato, contatta l'assistenza.

  5. Seleziona Applica.

Cosa fare se la tua applicazione viene rifiutata dopo aver applicato un consiglio

Se noti che un'app o un sito web viene rifiutato dopo l'applicazione di una limitazione, cerca la limitazione dell'applicazione che devi aggiungere nel messaggio di errore della risposta API.

API e SDK lato client

App basate su browser e WebView

I browser moderni in genere oscurano l'intestazione Referer nelle richieste multiorigine per motivi di privacy, spesso riducendola a Origin. Tuttavia, il comportamento esatto dipende dal referrer-policy applicato dal sito di hosting e può variare anche in base al browser e alla versione dell'utente.

Le applicazioni web che utilizzano schemi URI opachi o locali per il caricamento dei contenuti in genere fanno in modo che il browser di rendering o la webview oscurino completamente l'intestazione Referer da qualsiasi chiamata in uscita, il che potrebbe causare errori nelle richieste che utilizzano chiavi API con limitazioni dei siti web.

Per ulteriori indicazioni, vedi Ospitare le app basate su browser su un server.

Istruzioni per la risoluzione dei problemi per le app basate su browser e WebView:

  • Per l'API Maps JavaScript, consulta la console di debug del browser per informazioni dettagliate su come autorizzare l'applicazione.

    Gli schemi URI esotici sono supportati parzialmente. Se alcune parti della tua applicazione non funzionano con uno schema URI esotico, anche dopo aver autorizzato il referrer richiesto, probabilmente dovrai ospitare l'applicazione in remoto su un server e caricarla tramite HTTPS (o HTTP).

    Se hai bisogno di aiuto con schemi URI esotici, contatta l'assistenza.

  • Altre API Maps Platform in genere restituiscono il referrer che devi autorizzare nella risposta di errore dell'API, presupponendo che il client abbia inviato queste informazioni con la richiesta rifiutata.

    Gli schemi URI esotici non sono supportati.

App Android

Utilizzare Android Debug Bridge (adb) o Logcat

App per iOS

Consulta Visualizzazione dei messaggi di log.

App che chiamano direttamente i servizi web

Per le applicazioni che chiamano direttamente gli endpoint API REST HTTPS o gRPC di Google Maps Platform senza un SDK Google Maps Platform lato client, vedi di seguito:

App per Android e iOS

Se la tua applicazione Android o iOS chiama direttamente i servizi della piattaforma Google Maps senza utilizzare nessuno degli SDK client della piattaforma Google Maps disponibili, consulta App per Android e App per iOS per ulteriori suggerimenti per la risoluzione dei problemi e Chiamate sicure ai servizi web lato client per le attuali best practice di sicurezza per i casi d'uso mobile.

Se la tua app registra le risposte di errore dell'API Google Maps Platform, le istruzioni riportate sopra per gli SDK lato client possono essere utili anche per risolvere i problemi di autenticazione.

App lato server

Le applicazioni lato server che si basano sulle chiavi API sono protette al meglio tramite le limitazioni degli indirizzi IP. Se hai applicato limitazioni all'indirizzo IP alla tua chiave e i log del servizio registrano risposte di errore dell'API Maps Platform, controlla i log di sistema per ulteriori informazioni. La risposta di errore includerà l'indirizzo IP del server che devi autorizzare.

App basate su browser o webview

Sebbene anche le API Google Maps Platform più recenti, come l'API Maps Static e l'API Street View Static, supportino le restrizioni dei referrer, tieni presente che i browser web o le webview probabilmente limiteranno l'intestazione Referer a Origin per le richieste multiorigine e probabilmente ometteranno l'invio del tutto, ad esempio per le risorse a cui si accede localmente o per le risorse gestite tramite protocolli diversi da HTTP o HTTPS.

Se non puoi utilizzare l'API Maps JavaScript nella tua applicazione e le restrizioni dei siti web non funzionano, consulta Chiamate sicure ai servizi web lato client per scoprire come effettuare chiamate ai servizi web di Maps Platform in modo sicuro dall'applicazione lato client basata sul browser.

Suggerimenti per controllare le limitazioni delle API

Per controllare le limitazioni API richieste, consulta Determinare le API che utilizzano la tua chiave API.

Se non riesci a determinare quali limitazioni applicare:

  1. Documenta le limitazioni attuali per riferimento futuro.
  2. Rimuovili temporaneamente mentre esamini il problema. Puoi controllare l'utilizzo nel tempo seguendo i passaggi descritti in Controllare l'utilizzo della chiave API.
  3. Se necessario, contatta l'assistenza.

Elimina le chiavi API inutilizzate

Prima di eliminare una chiave API, assicurati che non venga utilizzata in produzione. Se non c'è traffico, è probabile che la chiave possa essere eliminata in sicurezza. Per ulteriori informazioni, vedi Controllare l'utilizzo della chiave API.

Per eliminare una chiave API:

  1. Apri la pagina Credenziali di Google Maps Platform della console Google Cloud.

  2. Seleziona la chiave API che vuoi eliminare.

  3. Seleziona il pulsante Elimina nella parte superiore della pagina.

  4. Nella pagina Elimina credenziale, seleziona Elimina.

    L'eliminazione di una chiave API richiede alcuni minuti per la propagazione. Al termine della propagazione, tutto il traffico che utilizza la chiave API eliminata viene rifiutato.

Fai attenzione quando ruoti le chiavi API

La rotazione di una chiave API crea una nuova chiave che presenta tutte le limitazioni della chiave precedente. Durante questo periodo, vengono accettate sia la chiave precedente che quella nuova, il che ti dà la possibilità di eseguire la migrazione delle tue app per utilizzare la nuova chiave.

Prima di ruotare una chiave API:

  • Innanzitutto, prova a limitare le chiavi API come descritto in Limitare le chiavi API.

  • Se la limitazione della chiave API non è possibile a causa di tipi di limitazione dell'applicazione in conflitto, esegui la migrazione a più chiavi nuove (con limitazioni) come descritto in Eseguire la migrazione a più chiavi API. La migrazione ti consente di controllare la migrazione e il cronoprogramma di implementazione delle nuove chiavi API.

Se i suggerimenti precedenti non sono possibili e devi ruotare la chiave API per impedire l'utilizzo non autorizzato, segui questi passaggi:

  1. Apri la pagina Credenziali di Google Maps Platform della console Google Cloud.

  2. Apri la chiave API che vuoi ruotare.

  3. Nella parte superiore della pagina, seleziona Ruota chiave.

  4. (Facoltativo) Modifica il nome della chiave API.

  5. Seleziona Crea.

  6. Aggiorna le tue applicazioni in modo che utilizzino la nuova chiave.

Dopo aver aggiornato le applicazioni in modo che utilizzino la nuova chiave, elimina la vecchia chiave facendo clic sul pulsante Elimina la chiave precedente nella sezione Chiave precedente della pagina della nuova chiave API.

Eseguire la migrazione a più chiavi API

Per eseguire la migrazione dall'utilizzo di una chiave API per più app a una singola chiave API univoca per ogni app, procedi nel seguente modo:

  1. Identifica le app che richiedono nuove chiavi:

    • Le app web sono le più facili da aggiornare, in quanto controlli tutto il codice. Pianifica l'aggiornamento di tutte le chiavi delle tue app basate sul web.
    • Le app mobile sono molto più difficili, poiché i tuoi clienti devono aggiornare le app prima che le nuove chiavi possano essere utilizzate.

  2. Crea e limita le nuove chiavi: aggiungi una limitazione dell'applicazione e almeno una limitazione delle API. Per saperne di più, consulta le best practice consigliate.

  3. Aggiungi le nuove chiavi alle tue app: per le app mobile, questo processo potrebbe richiedere mesi prima che tutti gli utenti aggiornino l'app all'ultima versione con la nuova chiave API.

Dividere l'utilizzo lato client e lato server in progetti separati

Se devi chiamare i servizi di Google Maps Platform sia da applicazioni lato server sia direttamente da applicazioni lato client in esecuzione su dispositivi degli utenti finali, Google consiglia di dividere l'utilizzo tra due progetti separati.

Questo approccio ti consente di applicare limiti di quota al minuto e per utente appropriati alla maggior parte dei servizi Google Maps Platform nel tuo progetto lato client, contribuendo a garantire che tutti gli utenti finali ricevano la loro giusta quota del progetto complessivo senza influire l'uno sull'altro.

Tuttavia, poiché le limitazioni della quota per utente influiscono sia sulle applicazioni lato client che su quelle lato server, se hai bisogno di una larghezza di banda elevata anche per i job lato server, configura un progetto separato per questo caso d'uso, configurato con un limite di quota per utente più elevato o senza alcun limite.

Disattivare i servizi inutilizzati

Non lasciare abilitati servizi inutilizzati in un progetto, in quanto questa pratica è vulnerabile agli abusi, soprattutto se non hai limitato tutte le tue chiavi API pubbliche. Come best practice, abilita un servizio su un progetto solo quando è necessario per le tue applicazioni.

L'aggiunta di limitazioni API a una chiave ne impedisce l'utilizzo su servizi per i quali non è stata autorizzata, ma le limitazioni API si applicano solo a quella chiave specifica. Disabilita un servizio a livello di progetto per impedire l'uso non autorizzato del servizio su qualsiasi chiave collegata al progetto.

Utilizzare gli SDK lato client

Quando utilizzi gli SDK Google Maps Platform lato client forniti, potrai sempre applicare le limitazioni appropriate alla tua chiave API per proteggere l'utilizzo del servizio.

L'utilizzo degli SDK lato client ti consentirà anche di adottare meccanismi di sicurezza più avanzati, come Firebase App Check sulle API di Maps Platform che lo supportano. Per ulteriori dettagli, consulta Utilizzare App Check per proteggere la chiave API.

Se gli SDK lato client non sono disponibili per la tua piattaforma, consulta Proteggere le chiamate ai servizi web lato client.

Per la disponibilità degli SDK Google Maps Platform lato client per diverse piattaforme, consulta Limitazioni consigliate per applicazioni e API.

Proteggere l'utilizzo dell'API Static Web

Le API web statiche, come l'API Maps Static e l'API Street View Static, sono simili alle chiamate API del servizio web.

Entrambe vengono chiamate utilizzando un'API REST HTTPS e in genere generi l'URL della richiesta API sul server. Tuttavia, anziché restituire una risposta JSON, le API web statiche generano un'immagine che puoi incorporare nel codice HTML generato. Ancora più importante, in genere è il client dell'utente finale, non il server, a chiamare il servizio Google Maps Platform.

Utilizzare una firma digitale

Come best practice, utilizza sempre le firme digitali in aggiunta a una chiave API. Inoltre, esamina il numero di richieste non firmate che vuoi consentire al giorno e modifica le quote per le richieste non firmate di conseguenza.

Per maggiori dettagli sulle firme digitali, consulta la Guida alle firme digitali.

Proteggere il secret di firma

Per proteggere le API web statiche, non incorporare i secret di firma API direttamente nel codice o nell'albero delle origini e non esporli nelle applicazioni lato client. Segui queste best practice per proteggere i tuoi segreti di firma:

  • Genera gli URL delle richieste firmate dell'API Maps Static e dell'API Street View Static lato server quando pubblichi una pagina web o in risposta a una richiesta dalla tua applicazione mobile.

    Per i contenuti web statici, puoi utilizzare il widget Firma un URL ora nella pagina Credenziali di Google Maps Platform della console Cloud.

    Per i contenuti web dinamici, consulta gli esempi di codice disponibili per la firma delle richieste URL.

  • Memorizza i segreti di firma al di fuori del codice sorgente e dell'albero delle origini dell'applicazione. Se inserisci i secret di firma o altre informazioni private in variabili di ambiente o includi file archiviati separatamente e poi condividi il codice, i secret di firma non vengono inclusi nei file condivisi. Se memorizzi i secret di firma o altre informazioni private nei file, mantieni i file al di fuori dell'albero dei sorgenti dell'applicazione per evitare che i secret di firma vengano inclusi nel sistema di controllo del codice sorgente. Questa precauzione è particolarmente importante se utilizzi un sistema di gestione del codice sorgente pubblico, come GitHub.

Proteggere le chiavi API del servizio web

Per un utilizzo sicuro delle API e dei servizi Google Maps Platform dalle app lato client, consulta Utilizzare gli SDK lato client e Chiamate sicure ai servizi web lato client.

Memorizza le chiavi API al di fuori del codice sorgente o dell'albero delle origini dell'applicazione. Se inserisci le chiavi API o altre informazioni in variabili di ambiente o includi file archiviati separatamente e poi condividi il codice, le chiavi API non vengono incluse nei file condivisi. Ciò è particolarmente importante se utilizzi un sistema di gestione del codice sorgente pubblico, come GitHub.

Per proteggere la chiave API del tuo servizio web da un utilizzo accidentale, Google consiglia di applicare limitazioni API a qualsiasi chiave utilizzata per Maps Platform. Inoltre, l'applicazione di limitazioni dell'indirizzo IP alla chiave del servizio web la proteggerà da un utilizzo non autorizzato da altri indirizzi IP di origine, anche se la chiave viene divulgata accidentalmente.

Utilizzare OAuth per le app lato server

OAuth 2.0 è uno standard aperto per la delega dell'accesso.

Sebbene il protocollo OAuth 2.0 supporti casi d'uso in cui un utente finale autorizza un'applicazione ad accedere ai dati personali per suo conto, il caso d'uso previsto per OAuth 2.0 con Maps Platform è che lo sviluppatore utilizzi token di accesso temporanei per autorizzare la propria applicazione a chiamare un'API per conto del proprio service account del progetto Google Cloud con le autorizzazioni del service account.

Poiché un service account può disporre di autorizzazioni estremamente ampie, OAuth 2.0 è consigliato per autorizzare le chiamate server-to-server tra le applicazioni lato server attendibili di uno sviluppatore e i server di Google Maps Platform.

Per le applicazioni lato client in esecuzione sui dispositivi degli utenti finali, sono consigliati altri metodi di autenticazione, come le chiavi API.

Se vuoi utilizzare OAuth 2.0 per autorizzare il traffico server-to-server, cerca l'argomento OAuth nella documentazione dell'API.

Ad esempio, ecco l'argomento OAuth per l'API Address Validation.

Chiamate sicure ai servizi web lato client

Se gli SDK lato client non sono disponibili, consulta i suggerimenti riportati di seguito.

Utilizzare un server proxy

L'utilizzo di un server proxy sicuro fornisce una fonte solida per interagire con un endpoint del servizio web di Google Maps Platform da un'applicazione lato client senza esporre la chiave API, il segreto di firma o il service account Google Cloud a utenti non autorizzati.

Punti chiave:

  • Crea le richieste di Google Maps Platform sul server proxy. Non consentire ai client di inoltrare chiamate API arbitrarie utilizzando il proxy.

  • Post-elabora le risposte di Google Maps Platform sul tuo server proxy. Filtra i dati che il cliente non ha bisogno.

Per saperne di più sull'utilizzo di un server proxy, consulta Living Vicariously: Using Proxy Servers with the Google Data API Client Libraries.

Chiamate sicure ai servizi web mobile diretti

Se non riesci a configurare un server proxy sicuro per la tua app lato client, proteggi l'applicazione seguendo questi passaggi:

  1. Utilizza le intestazioni HTTP:

    • Android: utilizza le intestazioni HTTP X-Android-Package e X-Android-Cert.

    • iOS: utilizza l'intestazione HTTP X-Ios-Bundle-Identifier.

  2. Aggiungi le limitazioni delle applicazioni corrispondenti alla tua chiave Android o iOS.

  3. Prima di prendere in considerazione l'emissione di chiamate direttamente dalla tua applicazione mobile a un servizio web API REST di Google Maps Platform, verifica che le richieste con identificatori di applicazione Android o iOS errati vengano rifiutate.

    Se le limitazioni delle applicazioni Android e iOS non sono supportate sull'endpoint testato, Google consiglia vivamente di utilizzare un server proxy sicuro tra i client mobile e l'endpoint del servizio web Google Maps Platform.

Suggerimenti per le app per Android:

  • Prima di integrare la tua applicazione per Android con i servizi Google Maps Platform, verifica che l'ID applicazione (chiamato anche nome del pacchetto) sia formattato correttamente. Per maggiori dettagli, vedi Configurare il modulo dell'app nella documentazione di Android.

  • Per trasmettere X-Android-Package direttamente dalla tua applicazione, cercalo in modo programmatico utilizzando Context.getPackageName().

  • Per trasmettere X-Android-Cert direttamente dalle tue applicazioni, calcola l'impronta SHA-1 richiesta dei certificati di firma delle tue applicazioni, accessibili tramite PackageInfo.signingInfo.

  • Se autorizzi la tua applicazione Android utilizzando la console Google Cloud, tieni presente che la UI prevede che l'impronta SHA-1 sia una stringa delimitata da due punti, ad esempio 00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33. Tuttavia, lo strumento gcloud e l'API API keys prevedono la stringa esadecimale senza delimitatori.

Suggerimenti per le applicazioni per iOS:

  • Prima di integrare l'applicazione per iOS con i servizi di Google Maps Platform, verifica che l'ID bundle sia formattato correttamente.

  • In genere, devi sempre trasmettere l'ID bundle del tuo bundle principale nell'intestazione X-Ios-Bundle-Identifier quando autorizzi la tua applicazione per iOS.

Per ulteriori informazioni, consulta gli articoli Gestire le chiavi API e Utilizzare le chiavi API per accedere alle API.

Ospita le app basate su browser su un server

Framework come Apache Cordova ti consentono di creare comodamente app ibride multipiattaforma in esecuzione all'interno di una WebView. Tuttavia, non è garantito che le limitazioni dei siti web con chiave API funzionino correttamente, a meno che la tua app web non venga caricata tramite HTTP o HTTPS da un sito web che controlli e hai autorizzato.

Le risorse in bundle, caricate localmente dall'interno di un'applicazione ibrida o a cui si accede utilizzando un URL di file locale, in molti casi impediscono l'autorizzazione basata sul referrer, poiché il motore del browser che alimenta la webview omette l'invio dell'intestazione Referer. Per evitare questo problema, ospita le tue applicazioni web lato server, non lato client.

In alternativa, per le applicazioni mobile, valuta la possibilità di utilizzare gli SDK nativi per Android e iOS di Google Maps Platform, anziché un SDK basato sul web.

Utilizzare App Check per proteggere la chiave API

Alcuni SDK e API Maps ti consentono di eseguire l'integrazione con Firebase App Check. App Check fornisce protezione per le chiamate dalla tua app a Google Maps Platform bloccando il traffico proveniente da origini diverse dalle app legittime. Per farlo, verifica la presenza di un token di un fornitore di attestazioni. L'integrazione delle tue app con App Check ti aiuta a proteggerti da richieste dannose, in modo da non pagare chiamate API non autorizzate.

Istruzioni per l'integrazione di App Check:

Gestire l'utilizzo non autorizzato di una chiave API

Se rilevi un utilizzo non autorizzato della tua chiave API, procedi nel seguente modo per risolvere il problema:

  1. Limita le chiavi: se hai utilizzato la stessa chiave in più app, esegui la migrazione a più chiavi API e utilizza chiavi API separate per ogni app. Per maggiori dettagli, consulta:

  2. Se utilizzi Places SDK o l'API Maps JavaScript, puoi anche utilizzare App Check per proteggere la tua chiave API.

  3. Sostituisci o ruota le chiavi solo se si verifica quanto segue:

    • Rilevi un utilizzo non autorizzato su chiavi che non possono essere limitate o che sono già limitate e App Check non è applicabile.

    • Vuoi passare più rapidamente alla protezione della tua chiave API e interrompere l'abuso, anche se ciò potrebbe influire sul traffico legittimo della tua applicazione.

    Prima di procedere, leggi Fai attenzione quando ruoti le chiavi API.

  4. Se i problemi persistono o hai bisogno di aiuto, contatta l'assistenza.

Limitazioni consigliate per applicazioni e API

Le sezioni seguenti suggeriscono restrizioni appropriate per applicazioni e API per ogni API, SDK o servizio Google Maps Platform.

Limitazioni delle API consigliate

Le seguenti linee guida per le limitazioni delle API si applicano a tutti i servizi di Google Maps Platform:

  • Limita la tua chiave API solo alle API per cui la utilizzi, con le seguenti eccezioni:

    • Se la tua app utilizza Places SDK for Android o Places SDK for iOS, autorizza Places API (New) o Places API, a seconda delle versioni dell'SDK che utilizzi. 1

    • Se la tua app utilizza l'API Maps JavaScript, autorizzala sempre sulla tua chiave.

    • Se utilizzi anche uno dei seguenti servizi dell'API Maps JavaScript, devi autorizzare anche le API corrispondenti:

      Servizio Restrizione delle API
      Servizio Directions (legacy) API Directions (legacy)
      Servizio Distance Matrix (legacy) API Distance Matrix (legacy)
      Servizio di elevazione API Elevation
      Servizio Geocoding API Geocoding
      Classe Place, widget Place Autocomplete (nuovo) e API Place Autocomplete Data API Places (Novità)2
      Libreria Places, servizio Places e widget Place Autocomplete API Places2

1 Per maggiori dettagli, consulta la documentazione di Places SDK for Android e di Places SDK for iOS.

2 Se non sai se devi autorizzare l'API Places (New) o l'API Places, consulta la documentazione dell'API Maps JavaScript.

Ecco alcuni esempi:

  • Utilizzi Maps SDK for Android e Places SDK for Android, quindi includi Maps SDK for Android e Places API (New) come limitazioni dell'API.

  • Il tuo sito web utilizza il servizio di elevazione dell'API Maps JavaScript e l'API Maps Static, quindi aggiungi limitazioni API per tutte le API seguenti:

    • API Maps JavaScript
    • API Elevation
    • API Maps Static

Limitazione delle applicazioni consigliata

Siti web

Per i siti web che utilizzano i servizi dell'API Maps JavaScript, dell'API Maps Static o dell'API Street View Static o che chiamano direttamente i servizi Google Maps Platform recenti tramite l'API REST HTTPS o gRPC, utilizza la restrizione delle applicazioni Siti web:

1 Per le applicazioni mobile, valuta la possibilità di utilizzare Maps SDK for Android e Maps SDK for iOS nativi.

2 Per le applicazioni mobile, valuta la possibilità di utilizzare l'SDK Places per Android e l'SDK Places per iOS nativi.

3 Vedi anche Proteggere l'utilizzo dell'API Static Web.

Siti web con l'API Maps Embed

Sebbene l'utilizzo dell'API Maps Embed non preveda costi, devi comunque limitare qualsiasi chiave API utilizzata per evitare abusi su altri servizi.

Best practice: crea una chiave API separata per l'utilizzo dell'API Maps Embed e limita questa chiave solo all'API Maps Embed. Questa limitazione protegge sufficientemente la chiave, impedendone l'utilizzo non autorizzato su qualsiasi altro servizio Google. Per avere il controllo completo su dove può essere utilizzata la tua chiave API Maps Embed, Google consiglia di applicare anche le limitazioni delle applicazioni Siti web.

Se non riesci a separare l'utilizzo dell'API Maps Embed in una chiave API separata, proteggi la chiave esistente utilizzando la limitazione dell'applicazione Siti web.

App e server che utilizzano servizi web

Per i server e le app lato client di reti interne aziendali attendibili che utilizzano servizi web insieme alle chiavi API, utilizza la limitazione dell'applicazione IP addresses.

Utilizzo per app e server che utilizzano queste API:

4 Per le applicazioni mobile, valuta la possibilità di utilizzare l'SDK per la navigazione.

5 Per un utilizzo sicuro del cellulare, utilizza un server proxy sicuro.

6 Per le applicazioni lato client, valuta la possibilità di utilizzare il servizio di geolocalizzazione nativo offerto dalla piattaforma, ad esempio W3C Geolocation per i browser web, LocationManager o l'API Fused Location Provider per Android o il framework Core Location di Apple per iOS.

7 Per le applicazioni mobile, valuta la possibilità di utilizzare l'SDK Places per Android e l'SDK Places per iOS nativi.

8 Per un utilizzo sicuro lato client, utilizza un server proxy sicuro.

App Android

Per le app su Android, utilizza la limitazione delle applicazioni Android apps. Utilizzo per app che utilizzano questi SDK:

Inoltre, impedisci l'inserimento accidentale di chiavi API nel controllo della versione utilizzando il plug-in Secrets Gradle per inserire i secret da un file locale anziché archiviarli nel file manifest Android.

App per iOS

Per le app su iOS, utilizza la limitazione delle applicazioni iOS apps. Utilizzo per app e server che utilizzano questi SDK:

Per approfondire