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 le chiavi API o, se supportato, OAuth 2.0 per l'autenticazione.

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

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

Oltre ad applicare le limitazioni relative alle applicazioni e alle chiavi API, segui le pratiche di sicurezza applicabili a prodotti Google Maps Platform specifici. Ad esempio, consulta 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 nella sezione Se stai limitando una chiave API in uso.

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

Best practice consigliate

Per una maggiore sicurezza ed evitare che ti venga addebitato l'utilizzo non autorizzato, segui queste best practice per la sicurezza delle API per tutte le API, gli SDK o i servizi di Google Maps Platform:

Limita le chiavi API

Utilizza chiavi API separate per ogni app

Elimina le chiavi API inutilizzate

Controlla l'utilizzo della chiave API

Fai attenzione quando ruoti le chiavi API

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

Disabilita i servizi inutilizzati

Ulteriori consigli per le app lato client

Utilizza gli SDK lato client

Chiamate di servizi web lato client sicure

Suggerimenti aggiuntivi per siti web o app lato client che utilizzano API web statiche

Proteggi l'utilizzo dell'API Web statica

Consigli aggiuntivi per le app lato server che utilizzano i servizi web

Proteggi le chiavi API dei servizi web

Utilizza 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 aggiungi 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 improprio, puoi eseguire la migrazione delle tue app a più nuove chiavi API al tuo ritmo, lasciando la chiave API originale invariata finché non osservi un solo tipo di traffico e la chiave API può essere limitata in sicurezza con un solo tipo di limitazioni delle applicazioni senza causare interruzioni del servizio indesiderate.

    Per ulteriori istruzioni, consulta Esegui la migrazione a più chiavi API.

    Monitora l'utilizzo nel tempo e controlla quando API, tipi di piattaforma e domini specifici hanno eseguito la migrazione dalla vecchia chiave API prima di scegliere di limitarla o eliminarla. Per saperne di più, consulta Reporting e monitoraggio e Metriche.

  • Se la tua chiave API è stata compromessa, devi agire più rapidamente per 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 Gestisci l'utilizzo non autorizzato di una chiave API.

Ulteriori informazioni

Limitazioni consigliate per applicazioni e API

Limita le chiavi API

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

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

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

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

Imposta una restrizione 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 Restrizioni delle chiavi, seleziona Imposta una restrizione delle applicazioni.

    Pagina Modifica 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 dei 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 l'intera stringa del referrer, incluso 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 la fingerprint del certificato di firma SHA-1 di ogni app per Android che vuoi autorizzare.

    1. Seleziona App per Android.
    2. Fai clic su + Aggiungi.
    3. Inserisci il nome del pacchetto e la fingerprint 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 SDK Android generano automaticamente questo certificato quando esegui una build di debug.
    • Certificato di release: utilizza questo certificato quando è tutto pronto per rilasciare l'app in uno store. Gli strumenti SDK Android generano questo certificato quando esegui una build di release.

    Per ulteriori informazioni sulla firma e sui certificati delle app per Android, consulta la guida alla firma dell'app.

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

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

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

    Per i suggerimenti relativi a una restrizione per le applicazioni, consulta Restrizione per le applicazioni consigliata.

  5. Seleziona Salva.

Imposta le restrizioni 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, in Restrizioni 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 è presente nell'elenco, devi abilitarlo. Per maggiori dettagli, consulta Per abilitare una o più API o SDK.

    Limita 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 restrizioni della chiave API. Per ulteriori informazioni, consulta la guida Ottieni una chiave API nella documentazione relativa all'API o all'SDK specifico di tuo interesse.

Per le restrizioni delle API consigliate, consulta Restrizioni delle API consigliate.

Controlla l'utilizzo della chiave API

Se limiti le chiavi API dopo che sono state create 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, indaga per determinare se devi aggiungere ulteriori limitazioni per evitare un utilizzo indesiderato. Puoi utilizzare Esplora metriche della console Cloud di Google Maps Platform per determinare quali restrizioni relative ad API e applicazioni applicare alla tua chiave API:

Determina 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:

  • Scopri come vengono utilizzate le tue chiavi API
  • Individua l'utilizzo imprevisto
  • Aiuta a verificare se è sicuro eliminare una chiave non utilizzata. Per informazioni sull'eliminazione di una chiave API, consulta Elimina 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, consulta Applica le limitazioni consigliate. Per saperne di più sull'utilizzo di Esplora metriche, consulta Crea grafici con Esplora metriche .

  1. Vai a Esplora metriche della 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 ad eccezione dell'API Maps Embed: vai alla pagina Metrics Explorer.

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

  4. Esamina ogni chiave API:

    1. Seleziona AGGIUNGI FILTRO.

    2. Seleziona l'etichetta credential_id.

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

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

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

  5. Ripeti l'operazione per le chiavi rimanenti.

  6. Limita le chiavi API solo alle API in uso.

  7. Se rilevi un utilizzo non autorizzato, consulta Gestisci l'utilizzo non autorizzato di una chiave API.

Scegli il tipo corretto di restrizione delle applicazioni utilizzando Esplora metriche

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

Se la tua chiave API ha restrizioni consigliate, applicale. Per saperne di più, consulta Applica le restrizioni delle chiavi API consigliate.

Se la tua chiave API non ha suggerimenti sulle restrizioni, determina il tipo di restrizione dell'applicazione da applicare in base al platform_type segnalato utilizzando Esplora metriche:

  1. Vai a Esplora metriche della console Google Cloud

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

  3. Vai alla pagina Esplora metriche: Esplora metriche.

  4. Esamina ogni chiave API:

    1. Seleziona AGGIUNGI FILTRO.

    2. Seleziona l'etichetta credential_id.

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

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

  5. Ripeti l'operazione per le chiavi rimanenti.

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

    PLATFORM_TYPE_JS : applica le restrizioni dei siti web alla chiave.

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

    PLATFORM_TYPE_IOS : applica alla chiave le restrizioni per le applicazioni per iOS.

    PLATFORM_TYPE_WEBSERVICE: potresti dover fare affidamento sulle restrizioni degli indirizzi IP sulla chiave per limitarla correttamente.

    Per i suggerimenti relativi all'API Maps Static e all'API Street View Static, consulta Proteggi l'utilizzo dell'API Web statica.

    Per i suggerimenti sull'API Maps Embed, consulta Siti web con l'API Maps Embed.

    La mia chiave API utilizza più tipi di piattaforme: il tuo traffico non può essere protetto adeguatamente con una sola chiave API. Devi eseguire la migrazione a più chiavi API. Per saperne di più, consulta Esegui la migrazione a più chiavi API.

Utilizza chiavi API separate per ogni app

Questa pratica limita l'ambito di ogni chiave. Se una chiave API viene compromessa, puoi eliminarla o ruotarla senza dover aggiornare le altre chiavi API. Puoi creare fino a 300 chiavi API per progetto. Per saperne di più, consulta Limiti per le chiavi API.

Sebbene una chiave API per applicazione sia l'ideale per motivi di sicurezza, puoi utilizzare chiavi con restrizioni su più app, purché utilizzino lo stesso tipo di restrizione delle applicazioni.

Applica le limitazioni relative alle chiavi API consigliate

Per alcuni Project Owner, editor e amministratori delle chiavi API, 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 suggerimenti vengono visualizzati come opzioni precompilate nella pagina Credenziali di Google Maps Platform.

API e SDK Google Maps Platform supportati dai suggerimenti automatici

  • API Maps JavaScript, tra cui Servizio Directions (legacy), Servizio Distance Matrix (legacy), Servizio Elevation, Servizio Geocoding, Classe Place, Widget Place Autocomplete (nuovo), API di dati Place Autocomplete, Libreria Places, Servizio Places, Widget Place Autocomplete e Places UI Kit

  • API Maps Static e API Street View Static

  • API Maps Embed

  • Maps SDK for Android, SDK Navigation per 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 vedi un utilizzo su altri servizi, non applicare il suggerimento senza prima procedere come segue:

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

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

    3. Aggiungi manualmente eventuali limitazioni delle applicazioni mancanti per i servizi aggiunti all'elenco delle API. Se l'altra chiave aggiunta richiede un tipo diverso di limitazioni delle applicazioni, consulta Esegui la migrazione a più chiavi API.

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

  • Utilizzi la chiave API in un'app o un sito web a basso volume che non ha registrato alcun utilizzo negli ultimi 60 giorni.

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

  • 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, consulta Esegui la migrazione a più chiavi API.

Motivi per cui viene visualizzato un suggerimento incompleto

  • Utilizzi la chiave API in un'app o un sito web a basso volume che non ha registrato alcun utilizzo negli ultimi 60 giorni.

  • Hai iniziato a utilizzare molto di recente 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 potrebbe richiedere alcuni giorni.

    Se vedi un utilizzo su altri servizi, non applicare il suggerimento senza prima procedere come segue:

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

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

    3. Aggiungi manualmente eventuali limitazioni delle applicazioni mancanti per i servizi aggiunti all'elenco delle API. Se l'altra chiave aggiunta richiede un tipo diverso di limitazioni delle applicazioni, consulta Esegui la migrazione a più chiavi API.

    4. A meno che tu non debba limitare urgentemente una chiave, ad esempio a causa di un utilizzo non autorizzato, potresti anche attendere un giorno o due per l'aggiornamento dei suggerimenti.

Motivi per cui potresti visualizzare suggerimenti non visibili nei grafici

  • La tua app o il tuo sito web ha inviato solo picchi di traffico molto brevi. In questo caso, passa da una visualizzazione GRAFICO per visualizzare una TABELLA o ENTRAMBI, poiché l'utilizzo è ancora visibile nella legenda. Per saperne di più, consulta Attivazione/disattivazione delle legende complete del grafico.

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

  • Il traffico proveniente 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 dei suggerimenti riportati sopra. Consulta i passaggi per la risoluzione dei problemi all'inizio della sezione Applica le restrizioni delle chiavi API consigliate.

  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 restrizioni relative ad applicazioni o API non affiliate ai tuoi servizi. Se qualcosa non funziona a causa di una dipendenza imprevista, puoi aggiungere nuovamente le app o le API richieste.

    • Se ti accorgi che un'app, un sito web o un'API non è presente nel suggerimento, aggiungilo manualmente o attendi un paio di giorni per consentire l'aggiornamento del suggerimento.

    • Se hai bisogno di ulteriore assistenza con il suggerimento, contatta l'assistenza.

  5. Seleziona Applica.

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

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

SDK e API lato client

App basate su browser e webview

Per motivi di privacy, i browser moderni in genere oscurano l'intestazione Referer nella richiesta multiorigine, spesso riducendola a Origin. Tuttavia, il comportamento esatto dipende dalla referrer-policy applicata del 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 caricare i contenuti in genere fanno sì che il browser o la webview di rendering oscurino completamente l'intestazione Referer da tutte le chiamate in uscita, il che potrebbe causare l'errore delle richieste che utilizzano chiavi API con restrizioni dei siti web.

Per ulteriori indicazioni, consulta Ospita le app basate su browser su un server.

Istruzioni per la risoluzione dei problemi relativi alle app basate su browser e webview:

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

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

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

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

    Gli schemi URI esotici non sono supportati.

App Android

Utilizza 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 l'API REST HTTPS o gli endpoint gRPC di Maps Platform senza un SDK Google Maps Platform lato client, consulta quanto segue:

App per Android e iOS

Se la tua applicazione Android o iOS chiama direttamente i servizi di Maps Platform senza utilizzare nessuno degli SDK client di Google Maps Platform disponibili, consulta App per Android e App per iOS per ulteriori suggerimenti sulla risoluzione dei problemi e Proteggi le chiamate 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 Maps Platform, le istruzioni riportate sopra per gli SDK lato client potrebbero essere utili anche per la risoluzione dei problemi di autenticazione.

App lato server

Le applicazioni lato server che si basano su chiavi API sono protette al meglio tramite le restrizioni degli indirizzi IP. Se hai applicato limitazioni degli indirizzi IP alla tua chiave e il tuo servizio registra 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

Anche se l'API Maps Static e l'API Street View Static, oltre alle API di Google Maps Platform più recenti, supporteranno anche le limitazioni dei referrer, tieni presente che i browser web o le visualizzazioni web probabilmente limiteranno l'intestazione Referer a Origin per le richieste multiorigine e probabilmente ometteranno del tutto l'invio, ad esempio per le risorse accessibili localmente o per le risorse pubblicate tramite protocolli diversi da HTTP o HTTPS.

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

Suggerimenti per controllare le restrizioni delle API

Per controllare le restrizioni API richieste, consulta Determina 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 Controlla 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 sia utilizzata in produzione. Se non è presente traffico riuscito, è probabile che la chiave possa essere eliminata in sicurezza. Per saperne di più, consulta Controlla 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.

    La propagazione dell'eliminazione di una chiave API richiede alcuni minuti. 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 con tutte le limitazioni della chiave precedente. Durante questo periodo di tempo, 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 Limita le chiavi API.

  • Se non è possibile limitare la chiave API a causa di tipi di limitazioni delle applicazioni in conflitto, esegui la migrazione a più nuove chiavi (limitate) come descritto in Esegui la migrazione a più chiavi API. La migrazione ti consente di controllare la migrazione e la sequenza temporale di implementazione alle nuove chiavi API.

Se i suggerimenti precedenti non sono applicabili 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. Facoltativamente, 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 per utilizzare la nuova chiave, elimina la chiave precedente facendo clic sul pulsante Elimina la chiave precedente nella sezione Chiave precedente della pagina della nuova chiave API.

Esegui 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, segui questi passaggi:

  1. Identifica le app che richiedono nuove chiavi:

    • Le app web sono le più facili da aggiornare, poiché hai il controllo di 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 clienti devono aggiornare le proprie app prima di poter utilizzare le nuove chiavi.

  2. Crea e limita le nuove chiavi: aggiungi sia una limitazione delle applicazioni sia almeno una limitazione delle API. Per ulteriori informazioni, 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 eseguano l'aggiornamento all'ultima app con la nuova chiave API.

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

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

Questo approccio ti consente di applicare limiti di quota appropriati per minuto e per utente alla maggior parte dei servizi Google Maps Platform nel tuo progetto lato client, contribuendo a garantire che tutti gli utenti finali ricevano la loro quota di progetto complessiva senza interferire tra loro.

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

Disattiva i servizi inutilizzati

Non lasciare abilitati i servizi inutilizzati in un progetto, poiché questa pratica è vulnerabile ad abusi, soprattutto se non hai limitato tutte le chiavi API pubbliche. Come best practice, attiva un servizio in un progetto solo quando è necessario per le tue applicazioni.

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

Utilizza 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 di SDK lato client ti consentirà anche di adottare un meccanismo di sicurezza più avanzato, come Firebase App Check sulle superfici API di Maps Platform che lo supportano. Per maggiori dettagli, consulta Utilizza App Check per proteggere la chiave API.

Se gli SDK lato client non sono disponibili per la tua piattaforma, consulta Proteggi 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.

Proteggi l'utilizzo dell'API Web statica

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

Entrambe vengono chiamate utilizzando un'API REST HTTPS e, in genere, l'URL della richiesta API viene generato sul server. Tuttavia, anziché restituire una risposta JSON, le API Static Web 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.

Utilizza una firma digitale

Come best practice, utilizza sempre le firme digitali oltre a una chiave API. Inoltre, controlla quante richieste non firmate 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.

Proteggi il secret di firma

Per proteggere le API web statiche, non incorporare i secret di firma dell'API direttamente nel codice o nell'albero di origine e non esporli nelle applicazioni lato client. Segui queste best practice per proteggere i tuoi secret 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 della 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 di firma delle richieste URL disponibili.

  • Archivia i secret di firma al di fuori del codice sorgente e dell'albero di origine 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 in file, tieni i file al di fuori dell'albero di origine dell'applicazione per mantenere i secret di firma al di fuori del sistema di controllo del codice sorgente. Questa precauzione è particolarmente importante se utilizzi un sistema di gestione del codice sorgente pubblico, come GitHub.

Proteggi le chiavi API dei servizi web

Per un utilizzo sicuro delle API e dei servizi di Google Maps Platform dalle app lato client, consulta Utilizza gli SDK lato client e Proteggi le chiamate ai servizi web lato client.

Archivia le chiavi API al di fuori del codice sorgente o dell'albero di origine dell'applicazione. Se inserisci le chiavi API o qualsiasi altra informazione nelle variabili di ambiente o includi file archiviati separatamente e poi condividi il codice, le chiavi API non vengono incluse nei file condivisi. Questo è particolarmente importante se utilizzi un sistema di gestione del codice sorgente pubblico, come GitHub.

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

Utilizza OAuth per le app lato server

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

Sebbene il protocollo OAuth 2.0 supporti i 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 service account del proprio progetto Google Cloud con le autorizzazioni del service account.

Poiché un service account potrebbe avere 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 consigli di seguito.

Utilizza un server proxy

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

Punti chiave:

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

  • Esegui la post-elaborazione delle risposte di Google Maps Platform sul tuo server proxy. Filtra i dati di cui il client 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 dirette sicure ai servizi web mobile

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 valutare la possibilità di inviare chiamate direttamente dalla tua applicazione mobile a un servizio web dell'API REST di Google Maps Platform, verifica che le richieste con identificatori di applicazioni 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 di Google Maps Platform.

Suggerimenti per le app per Android:

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

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

  • Per passare 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 l'applicazione Android utilizzando la console Google Cloud, tieni presente che l'interfaccia utente 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 delle chiavi API 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 pacchetto sia formattato correttamente.

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

Per ulteriori informazioni, consulta gli articoli Gestisci le chiavi API e Utilizza le chiavi API per accedere alle API.

Ospita le tue app basate su browser su un server

I framework, come Apache Cordova, ti consentono di creare facilmente app ibride multipiattaforma eseguite all'interno di una WebView. Tuttavia, non è garantito che le restrizioni dei siti web per le chiavi API funzionino correttamente, a meno che la tua app web non venga caricata utilizzando HTTP o HTTPS da un sito web che controlli e che hai autorizzato.

Le risorse in bundle, caricate localmente dall'interno di un'applicazione ibrida o accessibili utilizzando un URL di file locale, in molti casi impediscono il funzionamento dell'autorizzazione basata su referrer, poiché il motore del browser che alimenta la tua webview ometterà 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 di Google Maps Platform per Android e iOS disponibili, anziché un SDK basato sul web.

Utilizza App Check per proteggere la chiave API

Alcuni SDK e API di Maps consentono 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. A questo scopo, verifica la presenza di un token di un provider di attestazione. L'integrazione delle tue app con App Check aiuta a proteggerti da richieste dannose, in modo che non ti vengano addebitati costi per chiamate API non autorizzate.

Istruzioni per l'integrazione di App Check:

Gestisci l'utilizzo non autorizzato di una chiave API

Se rilevi un utilizzo non autorizzato della tua chiave API, segui questi passaggi 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 l'SDK Places o l'API Maps JavaScript, puoi anche utilizzare App Check per proteggere la tua chiave API.

  3. Sostituisci o ruota le chiavi solo se:

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

    • Vuoi agire più rapidamente per proteggere la 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.

Restrizioni consigliate per applicazioni e API

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

Restrizioni delle API Recommender

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

  • Limita la 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 l'API Places (nuova) o l'API Places, 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
      Directions Service (legacy) API Directions (legacy)
      Servizio Distance Matrix (legacy) API Distance Matrix (legacy)
      Servizio Elevation API Elevation
      Servizio di geocodifica API Geocoding
      Classe Place, widget Place Autocomplete (nuovo) e API di dati Place Autocomplete 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 Places SDK for iOS.

2 Se non sai con certezza se devi autorizzare l'API Places (nuova) o l'API Places (legacy), 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 l'API Places (nuova) come restrizioni API.

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

    • API Maps JavaScript
    • API Elevation
    • API Maps Static

Limitazione delle applicazioni consigliata

Siti web

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

1 Per le applicazioni mobile, valuta la possibilità di utilizzare l'SDK Maps nativo per Android e l'SDK Maps per iOS.

2 Per le applicazioni mobile, valuta la possibilità di utilizzare i nativi Places SDK for Android e Places SDK for iOS.

3 Consulta anche Proteggi l'utilizzo dell'API Static Web.

Siti web con l'API Maps Embed

Sebbene l'utilizzo dell'API Maps Embed sia senza costi, devi comunque limitare l'utilizzo di qualsiasi chiave API 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 il controllo completo su dove può essere utilizzata la tua chiave API Maps Embed, Google consiglia di applicare anche le restrizioni 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 delle applicazioni 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 delle applicazioni IP addresses.

Utilizza per app e server che utilizzano queste API:

4 Per le app mobile, valuta la possibilità di utilizzare l'SDK Navigation.

5 Per un utilizzo sicuro dei dispositivi mobili, 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 Places SDK for Android e Places SDK for 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. Utilizza per le app che utilizzano questi SDK:

Inoltre, evita di inserire accidentalmente le 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 di Android.

App per iOS

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

Per approfondire