In questa pagina viene descritto come fornire le credenziali alle applicazioni predefinite (ADC) per l'utilizzo da parte delle librerie client di Cloud, delle librerie client delle API di Google e delle API REST e RPC in una varietà di ambienti.
ADC è una strategia utilizzata dalle librerie di autenticazione di Google per trovare automaticamente le credenziali in base all'ambiente dell'applicazione. Le librerie di autenticazione rendono quindi disponibili queste credenziali per le librerie client Cloud e le librerie client delle API di Google. Le librerie client utilizzano le credenziali per autenticarsi nelle API Google Cloud. Quando configuri l'ADC e utilizzi una libreria client, il codice può essere eseguito in un ambiente di sviluppo o di produzione senza modificare la modalità di autenticazione dell'applicazione ai servizi e alle API di Google Cloud.
Per informazioni su dove ADC cerca le credenziali e in quale ordine, consulta Come funzionano le credenziali predefinite dell'applicazione.
Se utilizzi chiavi API, non è necessario fornire le credenziali tramite ADC. Per saperne di più, consulta la sezione Utilizzo di chiavi API.
Come fornire le credenziali a ADC
Il modo in cui fornisci le credenziali a ADC dipende da dove viene eseguito il tuo codice:
- Ambiente di sviluppo locale
- Cloud Shell o altri ambienti di sviluppo basati su cloud di Google Cloud
- Compute Engine o altri servizi Google Cloud che supportano il collegamento di un account di servizio
- Google Kubernetes Engine o altro ambiente containerizzato di Google Cloud
- On-premise o da un altro cloud provider
Ambiente di sviluppo locale
Credenziali utente
Quando il codice è in esecuzione in un ambiente di sviluppo locale, ad esempio una workstation di sviluppo, la soluzione migliore è utilizzare le credenziali associate all'Account Google, dette anche credenziali utente.
Per fornire le tue credenziali utente ad ADC, devi utilizzare Google Cloud CLI:
Installa e inizializza l'interfaccia a riga di comando gcloud, se non lo hai già fatto.
Crea il file delle credenziali:
gcloud auth application-default login
Viene visualizzata una schermata di accesso. Una volta eseguito l'accesso, le credenziali verranno archiviate nel file delle credenziali locale utilizzato da ADC.
L'utilizzo dell'interfaccia a riga di comando gcloud per fornire le credenziali ad ADC ha le seguenti limitazioni:
Le credenziali utente potrebbero non funzionare per alcuni metodi e API, come l'API Cloud Translation o l'API Cloud Vision, senza parametri o configurazioni aggiuntivi. Se viene visualizzato un messaggio di errore relativo all'API non abilitata nel progetto o se non è disponibile alcun progetto di quota, consulta la sezione Risoluzione dei problemi relativi alla configurazione dell'ADC.
Questo metodo archivia le tue credenziali in un file nel tuo file system. Qualsiasi utente con accesso al tuo file system può utilizzare queste credenziali. Quando non hai più bisogno di queste credenziali, devi revocarle:
gcloud auth application-default revoke
Se il tuo Account Google non dispone dei ruoli di Identity and Access Management (IAM) richiesti nel tuo progetto, il codice potrebbe non essere in grado di accedere ad alcune risorse. In questo caso, chiedi all'amministratore della sicurezza di concederti i ruoli necessari.
Tipi di credenziali gcloud
Il comando gcloud auth application-default login
fornisce un modo per archiviare le credenziali per il tuo Account Google nella nota località utilizzata da ADC, ma queste vengono utilizzate solo dalle librerie client e da ADC. Quando esegui i comandi nell'interfaccia a riga di comando gcloud, stai utilizzando le credenziali che hai fornito quando hai eseguito l'accesso all'interfaccia a riga di comando gcloud tramite il comando gcloud auth login
.
In genere, utilizzerai lo stesso account per accedere all'interfaccia a riga di comando gcloud e per fornire le credenziali utente ad ADC, ma puoi utilizzare account diversi, se necessario.
Per informazioni sull'accesso all'interfaccia a riga di comando gcloud CLI, consulta Inizializzazione dell'interfaccia a riga di comando gcloud.
Chiavi account di servizio
Se non puoi usare le credenziali utente per lo sviluppo locale, puoi usare una chiave dell'account di servizio. Le chiavi degli account di servizio creano rischi inutili e devono essere evitate quando possibile.
Se il criterio dell'organizzazione ha un vincolo che impedisce la creazione di una chiave dell'account di servizio, questo metodo non è disponibile.
Per creare una chiave dell'account di servizio e renderla disponibile per ADC:
Crea un account di servizio con i ruoli necessari all'applicazione e una chiave per l'account di servizio seguendo le istruzioni riportate in Creazione di una chiave dell'account di servizio.
-
Imposta la variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALS
sul percorso del file JSON che contiene la chiave dell'account di servizio. Questa variabile si applica solo alla sessione shell corrente, quindi se apri una nuova sessione, impostala di nuovo.
Ambiente di sviluppo basato su cloud di Google Cloud
Quando utilizzi un ambiente di sviluppo basato sul cloud Google Cloud, come Cloud Shell o Cloud Code, lo strumento utilizza le credenziali che hai fornito al momento dell'accesso e gestisce le eventuali autorizzazioni richieste.
Servizi Google Cloud che supportano il collegamento di un account di servizio
Alcuni servizi Google Cloud, come Compute Engine, App Engine e Cloud Functions, supportano il collegamento di un account di servizio gestito dall'utente ad alcuni tipi di risorse. In genere, il collegamento di un account di servizio è supportato quando le risorse di quel servizio possono essere eseguite o includere il codice dell'applicazione. Quando colleghi un account di servizio a una risorsa, il codice in esecuzione sulla risorsa può utilizzare tale account di servizio come identità.
Collegare un account di servizio gestito dall'utente è il modo migliore per fornire le credenziali ad ADC per il codice di produzione in esecuzione su Google Cloud.
Per assistenza sulla creazione di un account di servizio, consulta Creazione e gestione degli account di servizio. Per informazioni sui ruoli da fornire all'account di servizio, consulta Scegliere i ruoli predefiniti.
Per informazioni sulle risorse a cui puoi collegare un account di servizio e aiuto per collegare l'account di servizio alla risorsa, consulta la documentazione di IAM sull'associazione di un account di servizio.
Se il criterio dell'organizzazione ha un vincolo che limita la creazione degli account di servizio, non puoi utilizzare questo metodo per configurare le credenziali per ADC.
Ambiente containerizzato con Google Cloud
L'autenticazione per gli ambienti containerizzati viene gestita in modo diverso tra gli ambienti di sviluppo e produzione.
Sviluppo per ambienti containerizzati
Se prevedi di containerizzare la tua applicazione utilizzando Google Kubernetes Engine o Anthos, puoi utilizzare ADC per lo sviluppo locale con l'interfaccia a riga di comando gcloud o utilizzare un container locale.
Quando utilizzi un container locale come ambiente di sviluppo, devi rendere disponibile il file delle credenziali personali nel container. Il componente aggiuntivo minikube di autenticazione GCP è un modo per farlo.
Ambienti di produzione containerizzati
La modalità di configurazione dell'autenticazione per gli ambienti containerizzati di Google Cloud dipende dall'ambiente in uso.
- Per Anthos, consulta la panoramica sull'autenticazione e Utilizzare il Workload Identity di parco risorse.
- Per Google Kubernetes Engine, vedi Utilizzare Workload Identity per GKE.
- Per Cloud Run for Anthos, vedi Utilizzo di Workload Identity per Cloud Run for Anthos.
On-premise o da un altro cloud provider
Se stai eseguendo la tua applicazione al di fuori di Google Cloud, devi fornire le credenziali riconosciute da Google Cloud per utilizzare i servizi Google Cloud.
Federazione delle identità per i carichi di lavoro
Il modo migliore per eseguire l'autenticazione con Google Cloud utilizzando le credenziali di un provider di identità diverso è utilizzare la federazione delle identità per i carichi di lavoro, creare un file di configurazione delle credenziali e impostare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS
in modo che rimandi all'autenticazione. Questo approccio è più sicuro della creazione di una chiave dell'account di servizio.
Per assistenza sulla configurazione della federazione delle identità per i carichi di lavoro per ADC, consulta Configurazione della federazione delle identità per i carichi di lavoro e Ottenere le credenziali di breve durata con la federazione delle identità.
Chiave account di servizio
Se non puoi configurare la federazione delle identità per i carichi di lavoro, devi creare un account di servizio, concedere i ruoli IAM richiesti dalla tua applicazione e creare una chiave per l'account di servizio.
Se il criterio dell'organizzazione ha un vincolo che impedisce la creazione di una chiave dell'account di servizio, questo metodo non è disponibile.
Per creare una chiave dell'account di servizio e renderla disponibile per ADC:
Crea un account di servizio con i ruoli necessari all'applicazione e una chiave per l'account di servizio seguendo le istruzioni riportate in Creazione di una chiave dell'account di servizio.
-
Imposta la variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALS
sul percorso del file JSON che contiene la chiave dell'account di servizio. Questa variabile si applica solo alla sessione shell corrente, quindi se apri una nuova sessione, impostala di nuovo.
Risoluzione dei problemi di configurazione dell'ADC
Alcuni problemi comuni che potresti riscontrare quando utilizzi l'ADC includono le seguenti situazioni:
Le credenziali utente non funzionano
Se la richiesta API restituisce un messaggio di errore relativo a credenziali dell'utente finale non supportate da questa API, API non abilitata o progetto di quota non impostato, esamina le seguenti informazioni.
Esistono due tipi di API Google Cloud:
API basate su risorse, che utilizzano il progetto associato alle risorse a cui si accede per la fatturazione e la quota.
API basate su client, che utilizzano il progetto associato all'account per accedere alle risorse per la fatturazione e la quota.
Quando utilizzi le credenziali dell'Account Google con un'API basata su client, il progetto predefinito associato all'account non può essere utilizzato per la fatturazione.
Per risolvere questo problema, esegui una delle seguenti operazioni:
Aggiorna l'ADC per utilizzare un progetto diverso come progetto di fatturazione:
gcloud auth application-default set-quota-project YOUR_PROJECT
Se chiami direttamente l'API REST o RPC, utilizza l'intestazione HTTP
x-goog-user-project
per specificare un progetto di fatturazione in ogni richiesta. Per i dettagli, consulta Impostare il progetto della quota con una richiesta REST.
Devi avere l'autorizzazione IAM serviceusage.services.use
affinché
un progetto possa essere impostato come progetto di fatturazione. L'autorizzazione serviceusage.services.use
è inclusa nel ruolo IAM consumer di servizi. Se non hai l'autorizzazione serviceusage.services.use
per qualsiasi progetto, contatta l'amministratore della sicurezza o il proprietario del progetto in grado di concederti il ruolo Consumatore di utilizzo del progetto.
Credenziali non corrette
Se le credenziali non sembrano fornire l'accesso previsto o non sono trovate, controlla le credenziali disponibili per ADC, nell'ordine in cui queste sono cercate, per identificare la causa. Ecco alcuni aspetti da controllare:
Assicurati che la variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALS
sia impostata solo se utilizzi una chiave dell'account di servizio o un altro file JSON per ADC. Le credenziali a cui rimanda la variabile di ambiente hanno la precedenza su altre credenziali, anche per Workload Identity.Conferma che l'entità che effettua la richiesta disponga dei ruoli IAM richiesti. Se utilizzi le credenziali utente, i ruoli devono essere concessi all'indirizzo email associato all'Account Google. Se utilizzi un account di servizio, quest'ultimo deve avere i ruoli richiesti.
Se fornisci una chiave API con la richiesta API, la chiave API ha la precedenza su ADC in qualsiasi località. Se hai impostato la variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALS
e utilizzi una chiave API, l'API potrebbe restituire un avviso che ti informa che le credenziali che hai fornito all'ADC vengono ignorate. Per interrompere l'avviso, annulla l'impostazione della variabile di ambienteGOOGLE_APPLICATION_CREDENTIALS
.
Tipo di credenziale non riconosciuto
Se la richiesta API restituisce un errore che include "Errore durante la creazione delle credenziali da JSON. Tipo di credenziale non riconosciuto", assicurati di utilizzare una credenziale valida. I file ID client non sono supportati per fornire le credenziali per ADC.
Passaggi successivi
- Scopri di più su come ADC trova le credenziali.
- Autentica utilizzando le librerie client di Cloud.
- Scopri l'autenticazione in Google.