Fornisci le credenziali per le Credenziali predefinite dell'applicazione

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

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

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:

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

  2. 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:

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

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

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:

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

  2. 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:

  1. Aggiorna l'ADC per utilizzare un progetto diverso come progetto di fatturazione:

    gcloud auth application-default set-quota-project YOUR_PROJECT

  2. 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 ambiente GOOGLE_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