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 autenticarsi.

Queste best practice mostrano come proteggere il tuo 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 Utilizzare OAuth per le app lato server.

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

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

Per ulteriori 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 di ricevere fatture per un utilizzo non autorizzato, segui queste best practice per la sicurezza delle API per tutte le API, gli SDK o i servizi Google Maps Platform:

Limita le chiavi API

Utilizza chiavi API separate per ogni app

Eliminare le chiavi API inutilizzate

Controllare l'utilizzo della chiave API

Fai attenzione quando ruoti le chiavi API

Suddividere l'utilizzo lato client e lato server in progetti distinti

Disattivare i servizi inutilizzati

Altri consigli per le app lato client

Utilizzare gli SDK lato client

Chiamate sicure dei servizi web lato client

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

Proteggere l'utilizzo delle API web statiche

Altri consigli per le app lato server che utilizzano i servizi web

Proteggere le chiavi API dei servizi 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 aggiungi limitazioni per una chiave già in uso in un'applicazione di produzione.

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

  • Se la tua chiave API non è stata compromessa e non è oggetto di attività illecite, puoi eseguire la migrazione delle tue app a più nuove chiavi API in base alle tue esigenze, lasciando inalterata la chiave API originale finché non osservi un solo tipo di traffico. Inoltre, la chiave API può essere limitata in sicurezza con un singolo tipo di limitazioni per le applicazioni senza causare interruzioni del servizio indesiderate.

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

    Monitora l'utilizzo nel tempo e scopri quando API, tipi di piattaforme e domini specifici sono stati migrati dalla vecchia chiave API prima di scegliere di limitarla o eliminarla. Per ulteriori informazioni, consulta Report e monitoraggio e Metriche.

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

Ulteriori informazioni

Limitazioni consigliate per le applicazioni e le API

Limita le chiavi API

La best practice è limitare sempre le chiavi API con un tipo di limitazioni delle applicazioni 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 oppure siti web specifici per applicazioni lato client oppure indirizzi IP o sottoreti CIDR specifici per app lato server che emettono chiamate all'API REST del servizio 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.

  • Restrizioni 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 richieste alle API e agli SDK specificati. Per una determinata chiave API, puoi specificare tutte le restrizioni 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 della piattaforma Google Maps nella console Google Cloud.

  2. Seleziona la chiave API che vuoi limitare.

  3. Nella pagina Modifica chiave API, in Restrizioni chiave, seleziona Imposta una restrizione delle applicazioni.

    Pagina di modifica della chiave API

  4. Seleziona uno dei tipi di limitazioni e fornisci le informazioni richieste in base all'elenco delle limitazioni.

    Tipo di restrizione Descrizione
    Siti web Specifica uno o più siti web di referrer.
    • Gli schemi URI referrer universalmente supportati sono https e http. Non è garantito che gli altri schemi funzionino correttamente, poiché i browser web moderni, per motivi di privacy, non inviano un'intestazione "Referer" nelle richieste in uscita.
    • Fornisci sempre la 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, per motivi di privacy, rimuoverà il percorso dalle richieste cross-origin.
    Indirizzi IP Specifica uno o più indirizzi IPv4 o IPv6 o subnet utilizzando la notazione CIDR. Gli indirizzi IP devono corrispondere all'indirizzo di origine rilevato 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. Se utilizzi la firma dell'app di Google Play, per recuperare la fingerprint del certificato di firma, consulta Lavorare con i fornitori di API. Se gestisci la tua chiave di firma, consulta Firma autonomo dell'applicazione o fai riferimento alle istruzioni per il tuo ambiente di compilazione.
    App per iOS Aggiungi l'identificatore del pacchetto di ogni applicazione per iOS che vuoi autorizzare.

    Per consigli su una limitazione delle applicazioni, vedi Limitazione delle applicazioni consigliata.

  5. Seleziona Salva.

Impostare le restrizioni delle API per una chiave API

  1. Apri la pagina Credenziali della piattaforma Google Maps della console Google Cloud.

  2. Seleziona la chiave API che vuoi limitare.

  3. Nella pagina Modifica chiave API, in Restrizioni 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, consulta la sezione Attivare una o più API o SDK.

    Limitare un'API nella pagina Modifica chiave API

  4. Seleziona Salva.

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

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

Controllare l'utilizzo della chiave API

Se stai limitando 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 oltre i servizi di Google Maps Platform, indaga per determinare se devi aggiungere altre limitazioni per evitare un utilizzo indesiderato. Puoi utilizzare lo strumento di esplorazione delle metriche della console Cloud di Google Maps Platform per determinare quali restrizioni delle API e delle 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
  • Individuare un utilizzo imprevisto
  • Aiuta a verificare se è possibile eliminare una chiave inutilizzata. Per informazioni sull'eliminazione di una chiave API, consulta 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 consigli per le restrizioni delle chiavi API generati automaticamente. Per ulteriori informazioni sulle restrizioni consigliate, vedi Applicare le restrizioni consigliate. Per ulteriori informazioni sull'utilizzo di Esplora metriche, consulta 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 di Metrics Explorer 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 Metrici Explorer.

  4. Controlla 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 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 le eventuali chiavi rimanenti.

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

  7. Se rilevi 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 in uso, assicurati inoltre che la chiave API abbia le limitazioni di applicazione corrette.

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

Se la tua chiave API non ha suggerimenti sulle restrizioni, determina il tipo di limitazione dell'applicazione da applicare in base al valore platform_type registrato utilizzando lo strumento di esplorazione delle metriche:

  1. Vai a Esplora metriche nella console Google Cloud

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

  3. Vai a questa pagina di 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 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 eventuali chiavi rimanenti.

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

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

    PLATFORM_TYPE_ANDROID : applica le limitazioni delle applicazioni Android alla chiave.

    PLATFORM_TYPE_IOS : applica le limitazioni delle applicazioni iOS alla chiave.

    PLATFORM_TYPE_WEBSERVICE : potrebbe essere necessario fare affidamento sulle limitazioni degli indirizzi IP della chiave per limitarla correttamente.

    Per i consigli sull'API Maps Static e sull'API Street View Static, consulta Proteggere l'utilizzo delle API web statiche.

    Per i consigli 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 correttamente con una sola chiave API. Devi eseguire la migrazione a più chiavi API. Per ulteriori informazioni, consulta la pagina Eseguire 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 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 per le 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 di progetti, editor e amministratori delle chiavi API, la console Google Cloud suggerisce restrizioni specifiche per le chiavi API senza restrizioni in base al loro utilizzo e alle loro attività su Google Maps Platform.

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

API e SDK Google Maps Platform supportati dai consigli automatici

  • API Maps JavaScript, tra cui Directions Service (legacy), Distance Matrix Service (legacy), Elevation Service, Geocoding Service Place class, Place Autocomplete Widget (new), Place Autocomplete Data API, Places Library, Places Service & Place Autocomplete Widget

  • API Maps Static e API Street View Static

  • API Maps Embed

  • Maps SDK for Android, Places SDK for Android e Navigation SDK for Android

  • Maps SDK for iOS, Places SDK for iOS, Places Swift SDK for iOS e Navigation SDK for iOS

Motivi per cui potresti non vedere un consiglio o un consiglio incompleto

Motivi per cui non viene visualizzato alcun consiglio

  • Utilizzi (anche) la chiave API su servizi diversi da quelli di Google Maps Platform o su servizi di Maps Platform non ancora supportati dai consigli automatici.

    Se noti un utilizzo su altri servizi, non applicare il suggerimento senza prima eseguire 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 eventuali restrizioni delle applicazioni mancanti per i servizi aggiunti all'elenco di API. Se l'altra chiave aggiunta richiede un tipo diverso di limitazioni per le applicazioni, consulta Eseguire la 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 di recente implementato una chiave esistente in una nuova app. In questo caso, attendi qualche giorno in più per consentire l'aggiornamento dei consigli.

  • Utilizzi la chiave API in più applicazioni che richiedono tipi di limitazioni delle applicazioni in conflitto o utilizzi la stessa chiave API in troppe app o su troppi siti web diversi. In entrambi i casi, come best practice, devi eseguire la migrazione a più chiavi. Per maggiori dettagli, consulta Eseguire la migrazione a più chiavi API.

Motivi per cui viene visualizzato 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 molto di recente a utilizzare una chiave esistente in una nuova API o un nuovo servizio e la pipeline automatica di consigli per le limitazioni 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 eseguire 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 eventuali restrizioni delle applicazioni mancanti per i servizi aggiunti all'elenco di API. Se l'altra chiave aggiunta richiede un tipo diverso di limitazioni per le applicazioni, consulta Eseguire la migrazione a più chiavi API.

    4. A meno che tu non debba urgentemente limitare una chiave, ad esempio a causa di un uso non autorizzato, potresti anche attendere un giorno o due per aggiornare i consigli.

Motivi per cui potresti vedere 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 da una visualizzazione GRAFICO a una TABELLA o ENTRAMBI, poiché l'utilizzo è ancora visibile nella legenda. Per ulteriori informazioni, consulta la sezione Attivare/disattivare le legende complete del grafico.

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

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

  1. Apri la pagina Credenziali della piattaforma Google Maps nella 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 altri servizi oltre a quelli di Google Maps Platform, metti in pausa per esaminare manualmente i passaggi del consiglio riportati sopra. Consulta la procedura di risoluzione dei problemi all'inizio della sezione Applicare le restrizioni consigliate per le chiavi API.

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

    Best practice: documenta e rimuovi eventuali restrizioni relative ad applicazioni o API che non sono affiliate ai tuoi servizi. Se si verifica un problema a causa di una dipendenza imprevista, puoi aggiungere nuovamente le app o le API richieste.

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

    • Se hai bisogno di ulteriore assistenza per il consiglio suggerito, contatta l'assistenza.

  5. Seleziona Applica.

Cosa fare se la tua richiesta viene rifiutata dopo l'applicazione di un consiglio

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

API e SDK lato client

App basate su browser e webview

I browser moderni in genere oscurano l'intestazione Referer nella richiesta cross-origin per motivi di privacy, spesso rimuovendo tutto tranne il valore Origin. Tuttavia, il comportamento esatto dipende dal referrer-policy applicato del sito ospitante 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 solitamente hanno il browser di rendering o la visualizzazione web che oscura completamente l'intestazione Referer da qualsiasi chiamata in uscita, il che potrebbe causare l'errore delle richieste con le chiavi API con limitazioni del sito web.

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

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

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

    Gli schemi URI insoliti sono supportati parzialmente. Se 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 per schemi URI insoliti, contatta l'assistenza.

  • In genere, le altre API di Maps Platform restituiscono il referrer che devi autorizzare nella risposta all'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 di Maps Platform o gli endpoint gRPC senza un SDK lato client di Google Maps Platform, consulta quanto segue:

App per Android e iOS

Se la tua applicazione per 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 per la risoluzione dei problemi e Chiamate sicure ai servizi web lato client per le best practice di sicurezza attuali 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 possono essere utili anche per la risoluzione dei problemi di autenticazione.

App lato server

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

App basate su browser o webview

Sebbene le API Maps Static e Street View Static e le API di Google Maps Platform più recenti supportino 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 cross-origin e probabilmente ne ometteranno l'invio del tutto, ad esempio per le risorse a cui si accede localmente o per le risorse pubblicate tramite protocolli diversi da HTTP o HTTPS.

Se non riesci a utilizzare l'API Maps JavaScript nella tua applicazione e le limitazioni del sito web non funzionano, consulta la sezione Chiamate di servizi web lato client sicure per scoprire come emettere chiamate di servizi web di Maps Platform in modo sicuro dall'applicazione lato client basata su browser.

Controllo delle limitazioni dell'API

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

Se non riesci a determinare quali restrizioni applicare:

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

Eliminare le chiavi API inutilizzate

Prima di eliminare una chiave API, assicurati che non sia utilizzata in produzione. Se non viene registrato 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 della piattaforma Google Maps nella 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, qualsiasi 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 vecchia chiave. Durante questo periodo di tempo, vengono accettate sia la vecchia che la nuova chiave, dandoti 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 tue chiavi API come descritto in Limitare 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 (con limitazioni) come descritto in Eseguire la migrazione a più chiavi API. La migrazione consente di controllare la migrazione e le tempistiche di implementazione delle nuove chiavi API.

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

  1. Apri la pagina Credenziali della piattaforma Google Maps della console Google Cloud.

  2. Apri la chiave API che vuoi ruotare.

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

  4. Se vuoi, modifica il nome della chiave API.

  5. Seleziona Crea.

  6. Aggiorna le 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 nuova pagina della 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ù semplici da aggiornare, poiché controlli tutto il codice. Pianifica di aggiornare le chiavi di tutte le tue app web.
    • Le app mobile sono molto più difficili, poiché i clienti devono aggiornare le proprie app prima che le nuove chiavi possano essere utilizzate.

  2. Crea e limita le nuove chiavi: aggiungi sia una restrizione delle applicazioni sia almeno una restrizione delle API. Per saperne di più, consulta le best practice consigliate.

  3. Aggiungi le nuove chiavi alle tue app: per le app mobile, questa procedura può richiedere mesi finché tutti gli utenti non eseguiranno l'aggiornamento all'app più recente con la nuova chiave API.

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

Se devi chiamare i servizi di 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 in due progetti distinti.

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

Tuttavia, poiché le limitazioni delle quote per utente influiscono sia sulle applicazioni lato client sia su quelle 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 nullo.

Disattivare i servizi inutilizzati

Non lasciare servizi inutilizzati abilitati in un progetto, in quanto questa pratica è vulnerabile agli abusi, soprattutto se non hai limitato tutte le tue 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 per i 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 impedirne l'uso non autorizzato su qualsiasi chiave collegata al progetto.

Utilizzare gli SDK lato client

Quando utilizzi gli SDK lato client di Google Maps Platform 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à inoltre di adottare meccanismi di sicurezza più avanzati, come Firebase App Check sulle piattaforme API di Maps 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 al servizio web lato client.

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

Proteggere 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 del servizio web.

Chiamate entrambe 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 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 segreto di firma

Per proteggere le API web statiche, non incorporare i secret di firma dell'API direttamente nel codice o nella struttura di origine né 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 nella console Cloud.

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

  • Memorizza i segreti 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 nelle 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 Utilizzare gli SDK lato client e Proteggere le chiamate ai servizi web lato client.

Memorizza le chiavi API al di fuori del codice sorgente o dell'albero di origine dell'applicazione. Se inserisci le chiavi API o altre informazioni nelle variabili di ambiente o includi file archiviati separatamente e poi condividi il codice, le chiavi API non sono 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 limitazioni API a qualsiasi chiave utilizzata per Maps Platform. Inoltre, l'applicazione di limitazioni degli indirizzi IP alla chiave del servizio web la proteggerà dall'uso non autorizzato da parte di 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 autorizzi 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 progetto Google Cloud con le autorizzazioni del service account.

Poiché un account di servizio può 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 della piattaforma Maps di Google.

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, di seguito è riportato l'argomento OAuth per l'API Address Validation.

Chiamate sicure al servizio web lato client

Se gli SDK lato client non sono disponibili, consulta i consigli 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 l'account del servizio Google Cloud a utenti non autorizzati.

Punti chiave:

*   Construct your Google Maps Platform requests on the proxy server.
    **Don't** allow clients to relay arbitrary API calls using the proxy.

*   Post-process the Google Maps Platform responses on your proxy server.
Filter out data that the client doesn't need.

Per saperne di più sull'utilizzo di un server proxy, consulta Vivere per procura: utilizzo di server proxy con le librerie client dell'API Google Data.

Chiamate dirette sicure ai servizi web mobile

Se non riesci a configurare un server proxy sicuro per la tua app lato client, metti al sicuro 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 chiave per Android o iOS.

  3. Prima di considerare la possibilità di effettuare chiamate direttamente dalla tua applicazione mobile a un servizio web 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 per Android e iOS non sono supportate nell'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 Android con i servizi della piattaforma Google Maps, verifica che l'ID applicazione (chiamato anche nome del pacchetto) sia formattato correttamente. Per maggiori dettagli, consulta Configurare il modulo dell'app. nella documentazione di Android.

  • Per passare X-Android-Package direttamente dalla tua applicazione, cercalo programmaticamente 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 la tua applicazione Android utilizzando la console Google Cloud, tieni presente che l'interfaccia utente si aspetta 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 chiavi API si aspettano la stringa esadecimale senza delimitatori.

Suggerimenti per le applicazioni per iOS:

  • Prima di integrare la tua applicazione per iOS con i servizi della piattaforma Google Maps, verifica che l'ID pacchetto sia formattato correttamente.

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

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

Ospitare le app basate su browser su un server

I framework, come Apache Cordova, ti consentono di creare facilmente app ibride multipiattaforma in esecuzione all'interno di un webview. Tuttavia, non è garantito che le limitazioni dei siti web per le chiavi API funzionino correttamente, a meno che l'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 da un'applicazione ibrida o a cui si accede utilizzando un URL file locale, in molti casi impediscono il funzionamento dell'autorizzazione basata sul referrer, poiché il motore del browser che alimenta la tua visualizzazione web omette l'invio dell'intestazione Referer. Per evitare questo problema, ospita le tue applicazioni web lato server e non lato client.

In alternativa, per le applicazioni mobile, ti consigliamo di utilizzare gli SDK Android e iOS di Google Maps Platform nativi disponibili anziché un SDK basato sul web.

Utilizzare App Check per proteggere la chiave API

Alcuni SDK e API di Maps ti consentono di eseguire l'integrazione con Firebase App checked. 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, controlla la presenza di un token di un fornitore di attestazioni. L'integrazione delle tue app con App Check contribuisce a proteggerti dalle richieste dannose, in modo che non ti vengano addebitati costi per 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, svolgi i seguenti passaggi per risolvere il problema:

  1. Limita le chiavi: se hai utilizzato la stessa chiave in più app, migra 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. Solo sostituisci o ruota le chiavi se è vera la seguente condizione:

    • 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 Precauzioni da adottare quando si ruotano le chiavi API.

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

Restrizioni consigliate per le applicazioni e le API

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

Restrizioni API consigliate

Le seguenti linee guida per le restrizioni 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 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
      Servizio di indicazioni stradali (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 Place Autocomplete Data API Places (nuova)2
      Places Library, 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, 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 API Places (nuova) come limitazioni API.

  • Il tuo sito web utilizza il servizio di elevazione dell'API Maps JavaScript e l'API Maps Static, quindi aggiungi le restrizioni 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 dell'API Maps JavaScript, l'API Maps Static o l'API Street View Static o che chiamano i servizi recenti di Google Maps Platform direttamente tramite l'API REST HTTPS o gRPC, utilizza la restrizione delle applicazioni Siti web:

1 Per le applicazioni mobile, ti consigliamo di utilizzare Maps SDK for Android e Maps SDK for iOS nativi.

2 Per le applicazioni mobile, ti consigliamo di utilizzare Places SDK per Android e Places SDK per iOS nativi.

3 Consulta anche Proteggere l'utilizzo delle API web statiche.

Siti web con l'API Maps Embed

Sebbene l'utilizzo dell'API Maps Embed non sia a pagamento, devi comunque limitare qualsiasi chiave API utilizzata per impedire 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 un controllo completo su dove può essere utilizzata la chiave API Maps Embed, Google consiglia di applicare anche le restrizioni delle applicazioni per i siti web.

Se non riesci a separare l'utilizzo dell'API Maps Embed in una chiave API distinta, metti al sicuro 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 a chiavi API, utilizza la limitazione delle applicazioni IP addresses.

Da utilizzare per app e server che utilizzano queste API:

4 Per le applicazioni mobile, ti consigliamo di utilizzare l'SDK Navigation.

5 Per un utilizzo sicuro da dispositivo mobile, utilizza un server proxy sicuro.

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

7 Per le applicazioni mobile, ti consigliamo di utilizzare Places SDK per Android e Places SDK per iOS nativi.

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

App Android

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

Inoltre, evita di controllare accidentalmente le chiavi API nel controllo versione utilizzando il plug-in Gradle Secrets per iniettare i secret da un file locale anziché archiviarli nel file Android Manifest.

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