Specificare le credenziali per le credenziali predefinite dell'applicazione

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Questa pagina descrive come fornire credenziali alle credenziali predefinite dell'applicazione (ADC) per l'utilizzo da parte delle librerie client di Cloud e delle librerie client delle API di Google in diversi ambienti.

ADC è una strategia utilizzata dalle librerie client Cloud e dalle librerie client delle API di Google per trovare automaticamente le credenziali in base all'ambiente dell'applicazione e utilizzarle per l'autenticazione nelle API Google Cloud. Quando configuri ADC e utilizzi una libreria client, il codice può essere eseguito in un ambiente di sviluppo o di produzione senza modificare l'autenticazione dell'applicazione nei servizi e nelle API Google Cloud.

Per saperne di più su dove ADC cerca le credenziali e in quale ordine, consulta la sezione Come funzionano le credenziali predefinite dell'applicazione.

Se utilizzi chiavi API, non è necessario fornire le credenziali tramite ADC. Per scoprire se un'API accetta le chiavi API, consulta la pagina relativa all'utilizzo delle chiavi API.

Come fornire credenziali ad ADC

Il modo in cui fornisci le credenziali ad ADC dipende da dove viene eseguito il tuo codice:

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 al tuo Account Google, chiamate anche credenziali utente.

Per fornire le tue credenziali utente ad ADC, devi utilizzare Google Cloud CLI:

  1. Installa e inizializza l'interfaccia a riga di comando gcloud, se non l'hai ancora fatto.

  2. Crea il file delle credenziali:

    gcloud auth application-default login

    Viene visualizzata una schermata di accesso. Dopo l'accesso, le tue credenziali vengono archiviate nel file delle credenziali locali utilizzato da ADC.

L'utilizzo dell'interfaccia a riga di comando gcloud per fornire le credenziali ad ADC presenta le seguenti limitazioni:

  • Le credenziali utente non funzionano per alcuni metodi e API, come l'API Cloud Translation o l'API Cloud Vision. Se viene visualizzato un messaggio di errore relativo all'API non abilitata nel progetto o se non è disponibile un progetto di quota, consulta la sezione Risolvere i problemi di configurazione dell'ADC.

  • Questo metodo memorizza le tue credenziali in un file sul 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 ha i ruoli di gestione di Identity and Access Management (IAM) richiesti nel tuo progetto, il codice potrebbe non essere in grado di accedere ad alcune risorse. In questi casi, chiedi all'amministratore della sicurezza di concederti i ruoli richiesti.

Tipi di credenziali gcloud

Il comando gcloud auth application-default login fornisce un modo per archiviare le credenziali per il tuo Account Google nella posizione nota per l'utilizzo da parte di ADC, ma queste credenziali vengono utilizzate solo dalle librerie client e da ADC. Quando esegui comandi nell'interfaccia a riga di comando gcloud, utilizzi le credenziali che hai fornito quando hai eseguito l'accesso a gcloud CLI utilizzando il comando gcloud auth login.

Di solito, 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, consulta Inizializzazione dell'interfaccia a riga di comando gcloud.

Chiavi account di servizio

Se non puoi utilizzare le credenziali utente per lo sviluppo locale, puoi utilizzare una chiave dell'account di servizio. Le chiavi degli account di servizio creano rischi inutili e devono essere evitate, se 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:

  1. Crea un account di servizio con i ruoli necessari per la tua applicazione e una chiave per quell'account di servizio, seguendo le istruzioni riportate nella sezione Creazione di una chiave dell'account di servizio.

  2. Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso della chiave.

Ambiente di sviluppo basato su cloud di Google Cloud

Quando utilizzi un ambiente di sviluppo basato su cloud di Google Cloud, come Cloud Shell o Cloud Code, lo strumento utilizza le credenziali che hai fornito quando hai effettuato l'accesso e gestisce le eventuali autorizzazioni richieste.

Ambiente di sviluppo containerizzato

Se stai eseguendo lo sviluppo locale in un ambiente containerizzato, devi rendere disponibile il container file di credenziali personali. Il componente aggiuntivo minikube Auth di GCP è un modo per farlo.

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 tale servizio possono eseguire 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à.

Il collegamento di 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 assistenza sulla determinazione dei ruoli che devi fornire al tuo account di servizio, consulta Scegliere i ruoli predefiniti.

Per informazioni sulle risorse a cui puoi collegare un account di servizio e per assistenza per il collegamento dell'account di servizio alla risorsa, consulta la documentazione di IAM relativa al collegamento di un account di servizio.

Se il criterio della tua 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 da Google Cloud

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 è tutto pronto per passare all'ambiente containerizzato di Google Cloud, devi comprendere in che modo l'ambiente supporta gli account di autenticazione e di servizio.

On-premise o un altro cloud provider

Se esegui l'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 altro provider di identità è utilizzare la federazione delle identità per i carichi di lavoro. Crei un file di configurazione delle credenziali e imposti la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS in modo che punti a tale file. Questo approccio è più sicuro della creazione di una chiave dell'account di servizio.

Per assistenza nella 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 riesci a configurare la federazione delle identità per i carichi di lavoro, devi creare un account di servizio, concedergli i ruoli IAM richiesti dall'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:

  1. Crea un account di servizio con i ruoli necessari per la tua applicazione e una chiave per quell'account di servizio, seguendo le istruzioni riportate nella sezione Creazione di una chiave dell'account di servizio.

  2. Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso della chiave.

Risolvere i problemi di configurazione dell'ADC

Alcuni problemi comuni che potresti riscontrare quando utilizzi ADC sono le seguenti situazioni:

Credenziali utente non funzionanti

Se la richiesta API restituisce un messaggio di errore relativo a credenziali dell'utente finale non supportate da questa API, API non abilitata nel progetto o nessun progetto di quota impostato, esamina le seguenti informazioni.

Esistono due tipi di API Google Cloud:

  • API basate sulle risorse, che utilizzano il progetto associato alle risorse a cui si accede per fatturazione e quota.

  • API basate su client, che utilizzano il progetto associato all'account che accede 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, devi aggiornare ADC in modo che utilizzi un progetto diverso come progetto di fatturazione:

gcloud auth application-default set-quota-project YOUR_PROJECT

Devi avere l'autorizzazione IAM serviceusage.services.use affinché un progetto possa designarlo 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 un progetto, contatta l'amministratore della sicurezza o il proprietario di un progetto che può concederti il ruolo consumer di utilizzo del servizio.

Il progetto di fatturazione non è incluso nel token restituito da ADC per le richieste REST. Se utilizzi ADC con una richiesta REST, consulta Impostare il progetto della quota con una richiesta REST.

Credenziali non corrette

Se le tue credenziali non danno accesso come previsto, o non sono state trovate, controlla le credenziali disponibili per ADC, nell'ordine in cui ADC cerca le credenziali, per vedere cosa potrebbe non andare a buon fine. 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 punta la variabile di ambiente hanno la precedenza su altre credenziali, anche per Workload Identity.

  • Conferma che l'entità che esegue la richiesta disponga dei ruoli IAM richiesti. Se utilizzi le credenziali utente, devi concedere i ruoli all'indirizzo email associato all'Account Google. Se utilizzi un account di servizio, tale account deve avere i ruoli richiesti.

  • Se fornisci una chiave API con la richiesta API, questa 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 ad ADC vengono ignorate. Per interrompere l'avviso, annulla l'impostazione della variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.

Tipo di credenziali non riconosciuto

Se la richiesta API restituisce un errore che include "Errore durante la creazione della credenziale da JSON. Tipo di credenziale non riconosciuta", assicurati di utilizzare una credenziale valida. I file Client-ID non sono supportati per fornire le credenziali per ADC.

Passaggi successivi