Configura Credenziali predefinite dell'applicazione

Questa pagina descrive come configurare le credenziali predefinite dell'applicazione (ADC) per l'utilizzo da parte delle librerie client di Cloud, delle librerie client dell'API di Google e delle API REST e RPC in diversi ambienti. Puoi configurare ADC fornendo le credenziali ad ADC nell'ambiente in cui è in esecuzione il tuo codice.

Application Default Credentials (ADC) è una strategia utilizzata dalle librerie di autenticazione per trovare automaticamente le credenziali in base all'ambiente dell'applicazione. Le librerie di autenticazione rendono disponibili queste credenziali per le librerie client di Cloud e le librerie client delle API di Google. Quando utilizzi ADC, il tuo codice può essere eseguito in un ambiente di sviluppo o di produzione senza modificare il modo in cui l'applicazione esegue l'autenticazione ai servizi e alle API Google Cloud.

Per informazioni su dove ADC cerca le credenziali e in quale ordine, vedi Come funzionano le credenziali predefinite dell'applicazione.

Se utilizzi chiavi API, non è necessario configurare ADC. Per ulteriori informazioni, consulta la sezione Utilizzo delle chiavi API.

Come fornire le credenziali ad ADC

Scegli l'ambiente in cui viene eseguito il codice:

Ambiente di sviluppo locale

Puoi fornire ad ADC le credenziali utente o dell'account di servizio in un 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 utente.

Quando configuri ADC con il tuo account utente, tieni presente quanto segue:

  • La configurazione di ADC con un account utente potrebbe non funzionare per alcuni metodi e API, ad esempio l'API Cloud Translation o l'API Cloud Vision, senza ulteriori parametri o configurazioni. Se viene visualizzato un messaggio di errore che indica che l'API non è abilitata nel progetto o che non è disponibile alcun progetto di quota, consulta Risolvere i problemi di configurazione di ADC.

  • Il file ADC locale contiene il token di aggiornamento. Qualsiasi utente con accesso al tuo file system può utilizzarlo per ottenere un token di accesso valido. Se non hai più bisogno di queste credenziali locali, puoi revocarle utilizzando il comando gcloud auth application-default revoke.

  • Il file ADC locale è associato al tuo account utente, non alla configurazione di gcloud CLI. Il passaggio a una configurazione di gcloud CLI diversa potrebbe modificare l'identità utilizzata da gcloud CLI, ma questo non influisce sul file ADC locale o sulla configurazione ADC.

  • Per impostazione predefinita, i token di accesso generati da un file ADC locale creato con le credenziali utente includono l' ambito a livello di cloud https://www.googleapis.com/auth/cloud-platform. Per specificare gli ambiti in modo esplicito, utilizza il flag –-scopes con il comando gcloud auth application-default login.

    Per aggiungere ambiti per servizi esterni a Google Cloud, ad esempio Google Drive, crea un ID client OAuth e forniscilo al comando gcloud auth application-default login utilizzando il flag –-client-id-file, specificando i tuoi ambiti con il flag -–scopes.

Il modo in cui configuri ADC con il tuo account utente dipende dal fatto che il tuo account utente sia gestito da Google (in altre parole, un Account Google) o da un altro provider di identità (IdP) ed è federato utilizzando la Federazione delle identità per la forza lavoro.

Configura ADC con l'Account Google

Per configurare ADC con un Account Google, utilizza Google Cloud CLI:

  1. Installa e inizializza gcloud CLI.

    Quando inizializza gcloud CLI, assicurati di specificare un progetto Google Cloud in cui disponi dell'autorizzazione per accedere alle risorse necessarie alla tua applicazione.

  2. Configura ADC:

    gcloud auth application-default login

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

Configura ADC con un account gestito da un IdP esterno

Per configurare ADC per un account utente gestito da un IdP esterno e federato con Workforce Identity Federation:

  1. Configura la federazione delle identità per la forza lavoro.

    Per maggiori informazioni, consulta Configurare la federazione delle identità per la forza lavoro.

  2. Configura gcloud CLI per utilizzare la federazione delle identità per la forza lavoro.

    Per ulteriori informazioni, consulta Scambiare credenziali esterne per un token di accesso Google Cloud.

  3. Configura ADC:

    gcloud auth application-default login

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

Credenziali dell'account di servizio

Puoi configurare ADC con le credenziali di un account di servizio utilizzando la rappresentazione dell'account di servizio o una chiave dell'account di servizio.

Simulazione dell'identità degli account di servizio

Puoi utilizzare la rappresentazione degli account di servizio per configurare un file ADC (Application Default Credentials) locale. Le librerie client che supportano la rappresentazione possono utilizzare queste credenziali automaticamente. I file ADC locali creati tramite la rappresentazione sono supportati nelle seguenti lingue:

  • C#
  • Go
  • Java
  • Node.js
  • Python

Devi disporre del ruolo IAM Creatore token account di servizio (roles/iam.serviceAccountTokenCreator) per l'account di servizio che stai impersonando. Per maggiori informazioni, consulta Ruoli obbligatori.

Utilizza la rappresentazione dell'account di servizio per creare un file ADC locale: 

gcloud auth application-default login --impersonate-service-account SERVICE_ACCT_EMAIL

Ora puoi utilizzare le librerie client utilizzando le lingue supportate, proprio come faresti dopo aver configurato un file ADC locale con credenziali utente. Le credenziali vengono trovate automaticamente dalle librerie di autenticazione. Per maggiori informazioni, consulta Eseguire l'autenticazione per l'utilizzo delle librerie client.

Chiavi account di servizio

Se non puoi utilizzare un account utente o la simulazione dell'identità degli account di servizio per lo sviluppo locale, puoi utilizzare una chiave dell'account di servizio.

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 le tue credenziali. Questa variabile si applica solo alla sessione di shell attuale. Pertanto, se apri una nuova sessione, imposta di nuovo la variabile.

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 al momento dell'accesso e gestisce le eventuali autorizzazioni richieste. Non puoi utilizzare gcloud CLI per configurare ADC in questi ambienti. Se hai bisogno di utilizzare un account utente diverso per configurare ADC o di configurare ADC con un account di servizio, utilizza un ambiente di sviluppo locale o una risorsa di computing Google Cloud come ambiente di sviluppo.

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 del servizio possono essere eseguite o includono il codice dell'applicazione. Quando colleghi un account di servizio a una risorsa, il codice in esecuzione sulla risorsa può utilizzare l'account di servizio come identità.

Collegare un account di servizio gestito dall'utente è il modo migliore per fornire credenziali ad ADC per il codice di produzione in esecuzione su Google Cloud.

Per determinare i ruoli da fornire all'account di servizio, vedi Scegliere i ruoli predefiniti.

Per informazioni sulle risorse a cui è possibile collegare un account di servizio e per informazioni su come collegare l'account di servizio alla risorsa, consulta la documentazione IAM sul collegamento di un account di servizio.

Set up authentication:

  1. Create the service account: 

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

    Replace SERVICE_ACCOUNT_NAME with a name for the service account.

  2. To provide access to your project and your resources, grant a role to the service account: 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

    Replace the following:

    • SERVICE_ACCOUNT_NAME: the name of the service account
    • PROJECT_ID: the project ID where you created the service account
    • ROLE: the role to grant
  3. To grant another role to the service account, run the command as you did in the previous step.

  4. Grant the required role to the principal that will attach the service account to other resources. 

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

    Replace the following:

    • SERVICE_ACCOUNT_NAME: the name of the service account
    • PROJECT_ID: the project ID where you created the service account
    • USER_EMAIL: the email address for a Google Account

GKE o GKE Enterprise

L'autenticazione per le applicazioni containerizzate in esecuzione su GKE o GKE Enterprise viene gestita in modo diverso tra gli ambienti di test locali e gli ambienti Google Cloud.

Testa le applicazioni containerizzate localmente

Per testare l'applicazione containerizzata sulla workstation locale, puoi configurare i container per l'autenticazione con il file delle credenziali locali. Per testare i container, utilizza un'implementazione Kubernetes locale come minikube e il componente aggiuntivo gcp-auth.

Esegui applicazioni containerizzate su Google Cloud

Puoi configurare l'autenticazione per gli ambienti containerizzati Google Cloud in modo diverso a seconda dell'ambiente:

On-premise o un altro cloud provider

Se esegui la tua applicazione all'esterno 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 IdP esterno è 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 questo file. Questo approccio è più sicuro rispetto alla creazione di una chiave dell'account di servizio.

Per assistenza sulla configurazione della federazione delle identità per i carichi di lavoro per ADC, consulta Federazione delle identità per i carichi di lavoro con altri cloud.

Chiave account di servizio

Se non riesci a configurare la federazione delle identità per i carichi di lavoro, devi creare un account di servizio, assegnargli i ruoli IAM richiesti dall'applicazione e creare una chiave per l'account di servizio.

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.

    Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON che contiene le tue credenziali. Questa variabile si applica solo alla sessione di shell attuale. Pertanto, se apri una nuova sessione, imposta di nuovo la variabile.

Passaggi successivi