Esegui l'autenticazione per gcloud CLI

Questo documento riguarda solo l'autenticazione per Google Cloud CLI per accedere alle risorseGoogle Cloud . Se devi autenticare i workload utilizzando le librerie client Cloud o le librerie client delle API di Google, consulta Come funzionano le credenziali predefinite dell'applicazione.

Prima di iniziare

Se non hai mai utilizzato Google Cloud e vuoi solo iniziare a utilizzare i comandi gcloud CLI nel tuo ambiente di sviluppo locale, puoi inizializzare gcloud CLI con il seguente comando:

gcloud init

L'inizializzazione ti guida attraverso un flusso di autenticazione, configura una configurazione gcloud CLI e autorizza gcloud CLI ad agire per tuo conto. Non è necessario eseguire un passaggio di autenticazione separato.

Il resto di questo documento tratta scenari più complessi, come l'utilizzo di gcloud CLI con diversi tipi di principal, metodi di autenticazione appropriati per ambienti diversi, cambio di principal e gestione delle credenziali memorizzate.

Metodi di autenticazione

Tutti i comandi gcloud CLI devono autenticarsi alle Google Cloud API. Puoi autenticarti nei seguenti modi:

• Autorizza e memorizza le credenziali: adatto per l'utilizzo da parte di persone in un ambiente di sviluppo locale. Puoi autorizzare gcloud CLI ad agire per conto di un principal utilizzando il comando gcloud auth login. Dopo l'autenticazione iniziale, questo comando memorizza le credenziali nella directory di configurazione di gcloud CLI. gcloud CLI utilizza queste credenziali archiviate per l'autenticazione automatica per i comandi successivi fino alla scadenza della sessione o alla revoca dell'autorizzazione.

• Autenticati con un file delle credenziali: adatto ai workload in esecuzione al di fuori di Google Cloud. Puoi utilizzare le variabili di ambiente o le proprietà di configurazione di gcloud CLI per specificare un file di credenziali per l'autenticazione automatica. Questo file può essere uno dei seguenti:

  • Un file di configurazione delle credenziali della federazione delle identità per i workload.

  • Una chiave del account di servizio.

• Fornisci un token di accesso: adatto per workflow automatizzati altamente isolati o sessioni stateless su macchine condivise. Puoi ignorare l'archivio credenziali fornendo un token di accesso direttamente a gcloud CLI. Puoi farlo impostando una variabile di ambiente specifica sulla stringa del token di accesso non elaborato o indirizzando gcloud CLI a un file contenente il token di accesso.

Dopo l'autenticazione, puoi facoltativamente consentire a gcloud CLI di simulare l'identità di un service account fornendo l'indirizzo email del service account.

Puoi utilizzare più metodi di autenticazione in un unico ambiente. Tuttavia, per qualsiasi comando gcloud viene utilizzato un solo principal. Per determinare quale principal utilizzare, gcloud CLI segue un ordine di priorità.

Quando non è necessario autenticarsi

Non è necessario eseguire l'autenticazione per gcloud CLI nelle seguenti situazioni:

• Subito dopo aver inizializzato gcloud CLI. L'autenticazione e l'autorizzazione di gcloud CLI ad agire per tuo conto sono incluse nel processo di inizializzazione. Potresti comunque dover eseguire di nuovo l'autenticazione se devi accedere a risorse diverse utilizzando un principal diverso o se devi eseguire di nuovo l'autenticazione del principal.
• Quando utilizzi gcloud CLI da una risorsa che espone un server di metadati di Compute Engine. Sono incluse risorse come le istanze VM di Compute Engine, i servizi Cloud Run e le build Cloud Build. gcloud CLI esegue l'autenticazione utilizzando il account di servizio collegato alla VM e può accedere alle stesse risorse del account di servizio entro i limiti di eventuali ambiti di accesso applicati.
• Quando utilizzi Cloud Shell. gcloud CLI esegue automaticamente l'autenticazione utilizzando l'entità con cui hai eseguito l'accesso alla console Google Cloud . Quando esegui un comando dell'interfaccia a riga di comando gcloud per la prima volta in una nuova sessione di Cloud Shell, ti viene chiesto di autorizzare Cloud Shell utilizzando questa entità.

Scegliere l'entità giusta per l'attività

Esistono diversi tipi di principal per l'utilizzo umano e i carichi di lavoro automatizzati. Il tipo di entità di servizio da utilizzare influisce sul modo in cui esegui l'autenticazione.

• Account utente: si tratta di Account Google destinati a persone che svolgono attività interattive, come attività amministrative incidentali, configurazione non programmatica di servizi, test, sperimentazione e osservabilità. Google Cloud

  L'autenticazione avviene come account utente con credenziali utente, ad esempio una password e un codice monouso.

• Service account: si tratta di account specifici per Google Cloud che i workload possono utilizzare per accedere a servizi o risorse. In genere non esegui l'autenticazione direttamente come account di servizio. In alternativa, puoi collegare un account di servizio a una risorsa come una VM Compute Engine o utilizzare la simulazione dell'identità dei account di servizio.

• Entità federate: si tratta di identità che fanno riferimento a utenti o service account in un provider di identità esterno. Esistono due tipi di entità federate supportate da Google Cloud, che hanno nomi simili:

  • Federazione delle identità per la forza lavoro: consente agli utenti umani di accedere a Google Cloud con identità gestite da un provider di identità esterno. Se la tua organizzazione ha già configurato il Single Sign-On (SSO), potresti utilizzare questo tipo di identità per l'autenticazione su Google Cloud.

    Per utilizzare la federazione delle identità per la forza lavoro, il provider di identità deve supportare OpenID Connect (OIDC) o SAML 2.0.

  • Federazione delle identità per i workload: consente ai workload in esecuzione al di fuori di Google Cloud di operare su risorse Google Cloud .

    Puoi utilizzare la federazione delle identità per i workload con i carichi di lavoro che eseguono l'autenticazione utilizzando certificati client X.509; che vengono eseguiti su Amazon Web Services (AWS) o Azure; Active Directory on-premise; servizi di deployment, come GitHub e GitLab; e con qualsiasi provider di identità che supporti OpenID Connect (OIDC) o Security Assertion Markup Language (SAML) V2.0.

Utilizzare gcloud CLI come utente

Per le attività interattive, in genere l'autenticazione avviene con uno dei seguenti metodi:

• Un account utente

• Un'identità utente federata, che utilizza la federazione delle identità per la forza lavoro

Account utente

La modalità di autenticazione con un account utente per gcloud CLI dipende dall'installazione o meno di un browser web sul tuo dispositivo.

Identità utente federate

Puoi utilizzare gcloud CLI con un'identità utente federata gestita in un provider di identità (IdP) esterno. Puoi farlo con la federazione delle identità per la forza lavoro.

Le seguenti istruzioni presuppongono che tu abbia già configurato un pool e un provider di federazione delle identità per la forza lavoro per funzionare con il tuo IdP.

Per utilizzare gcloud CLI con un'identità utente federata, crea un file di configurazione di accesso, quindi accedi utilizzando un flusso basato sul browser:

1. Esegui questo comando per creare un file di configurazione di accesso:

   Linux e macOS

   gcloud iam workforce-pools create-login-config \
       locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
       --output-file=LOGIN_CONFIG_PATH

   Windows (PowerShell)

   gcloud iam workforce-pools create-login-config `
       locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID `
       --output-file=LOGIN_CONFIG_PATH

   Sostituisci quanto segue:

   • WORKFORCE_POOL_ID: l'ID del pool di Federazione delle identità della forza lavoro.
   • WORKFORCE_PROVIDER_ID: l'ID del provider di Federazione delle identità della forza lavoro.
   • LOGIN_CONFIG_PATH: il percorso in cui scrivere il file di configurazione di accesso. Ad esempio, login-config.json.

   Il file di configurazione dell'accesso contiene gli endpoint utilizzati da gcloud CLI per attivare il flusso di autenticazione basato su browser e impostare il pubblico sull'IdP configurato nel provider del pool di identità per la forza lavoro. Il file non contiene informazioni riservate.

   Il contenuto del file di configurazione di accesso è simile al seguente:

   {
     "universe_domain": "googleapis.com",
     "universe_cloud_web_domain": "cloud.google",
     "type": "external_account_authorized_user_login_config",
     "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
     "auth_url": "https://auth.cloud.google/authorize",
     "token_url": "https://sts.googleapis.com/v1/oauthtoken",
     "token_info_url": "https://sts.googleapis.com/v1/introspect"
   }

2. Indica il file di configurazione di accesso con una variabile di ambiente, una proprietà nella configurazione gcloud CLI attiva o utilizzalo direttamente con il comando gcloud auth login:

   Variabile di ambiente

   Per utilizzare il file di configurazione dell'accesso con una variabile di ambiente, completa le seguenti istruzioni:

   1. Imposta la variabile di ambiente CLOUDSDK_AUTH_LOGIN_CONFIG_FILE sul percorso del file di configurazione di accesso.

   2. Esegui questo comando:

      gcloud auth login

   3. gcloud CLI fa riferimento alla variabile di ambiente per trovare il file di configurazione di accesso, quindi avvia il processo di autenticazione. Segui il flusso basato sul browser per autenticare e autorizzare gcloud CLI ad accedere alle risorse per tuo conto per i comandi futuri.

   Per interrompere l'utilizzo del file di configurazione di accesso per i comandi gcloud auth login, cancella la variabile di ambiente CLOUDSDK_AUTH_LOGIN_CONFIG_FILE.

   Configurazione di gcloud CLI

   Per utilizzare il file di configurazione dell'accesso con una proprietà di configurazione gcloud CLI, completa le seguenti istruzioni:

   1. Imposta la proprietà auth/login_config_file della configurazione gcloud CLI attiva sul percorso del file di configurazione di accesso con il seguente comando:

      gcloud config set auth/login_config_file LOGIN_CONFIG_PATH

   2. Esegui questo comando:

      gcloud auth login

   3. gcloud CLI fa riferimento alla proprietà di configurazione per trovare il file di configurazione di accesso e poi avvia il processo di autenticazione. Segui il flusso basato sul browser per autenticare e autorizzare gcloud CLI ad accedere alle risorse per tuo conto per i comandi futuri.

   Per interrompere l'utilizzo del file di configurazione di accesso per i comandi gcloud auth login, annulla l'impostazione della proprietà con il seguente comando:

   gcloud config unset auth/login_config_file

   gcloud auth login

   Per utilizzare il file di configurazione di accesso direttamente con il comando gcloud auth login, segui queste istruzioni:

   • Se hai utilizzato il flag --activate durante la creazione del file di configurazione di accesso, esegui questo comando:

     gcloud auth login

   • Se non hai utilizzato il flag --activate quando hai creato il file di configurazione di accesso, esegui il seguente comando:

     Linux e macOS

     gcloud auth login \
         --login-config=LOGIN_CONFIG_PATH

     Windows (PowerShell)

     gcloud auth login `
         --login-config=LOGIN_CONFIG_PATH

     Sostituisci LOGIN_CONFIG_PATH con il percorso del file di configurazione di accesso.

   Il comando gcloud auth login memorizza le credenziali di accesso nella tua home directory. L'entità autenticata diventa l'entità attiva nella configurazione dell'interfaccia allagcloud CLId attiva. Se non vengono sostituite, gcloud CLI utilizza queste credenziali archiviate per accedere a Google Cloud.

Utilizzare gcloud CLI con i carichi di lavoro

Per i workload automatizzati, in genere l'autenticazione viene eseguita con uno dei seguenti metodi:

• Un'identità federata per i Workload Identity, che utilizza la federazione delle identità per i workload

• Un account di servizio, utilizzando la rappresentazione

Identità di workload federate

Puoi utilizzare gcloud CLI con un'identità federata per i carichi di lavoro. Puoi farlo con la federazione delle identità per i workload.

Un workload può accedere alle risorse Google Cloud direttamente agendo come un principal definito da un pool di identità del workload oppure assumere l'identità di un account di servizio collegato a un pool di identità del workload.

Ti consigliamo di utilizzare il metodo di accesso diretto per evitare account di servizio con autorizzazioni eccessive e per registrare l'accesso alle risorse utilizzando l'identificatore dell'entità federata. Utilizza la simulazione dell'identità del account di servizio solo quando le API Google Cloud non supportano la federazione delle identità per i workload.

Le seguenti istruzioni presuppongono che tu abbia già configurato un pool e un provider di federazione delle identità per i carichi di lavoro per funzionare con il tuo IdP.

1. Crea un file di configurazione delle credenziali per la federazione delle identità per i carichi di lavoro seguendo le istruzioni per il provider di identità supportato.

2. Definisci il percorso del file di configurazione delle credenziali in una variabile di ambiente, come proprietà nella configurazione di gcloud CLI attiva o con il comando gcloud auth login:

   Variabile di ambiente

   Imposta la variabile di ambiente CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE sul percorso del file di configurazione delle credenziali. La gcloud CLI fa riferimento al file ogni volta che esegue un comando e ottiene una credenziale dal tuo IdP. Questa credenziale viene scambiata con un token di accesso a Google Cloud.

   Per non utilizzare più il file di configurazione delle credenziali, cancella la variabile di ambiente CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE.

   Configurazione di gcloud CLI

   Imposta la proprietà auth/credential_file_override della configurazione dell'interfaccia a riga di comando gcloud attiva sul percorso del file di configurazione delle credenziali con il seguente comando:

   gcloud config set auth/credential_file_override CONFIGURATION_PATH
   

   Sostituisci CONFIGURATION_PATH con il percorso del file di configurazione delle credenziali.

   Per interrompere l'utilizzo del file di configurazione delle credenziali per impostazione predefinita per i comandi gcloud, annulla l'impostazione della proprietà con il seguente comando:

   gcloud config unset auth/credential_file_override
   

   gcloud auth login

   Esegui questo comando utilizzando il flag --cred-file:

   Linux e macOS

   gcloud auth login \
       --cred-file=CONFIGURATION_PATH
   

   Windows (PowerShell)

   gcloud auth login `
       --cred-file=CONFIGURATION_PATH
   

   Sostituisci CONFIGURATION_PATH con il percorso di un file di configurazione delle credenziali.

   Il comando gcloud auth login memorizza le credenziali di accesso nella tua home directory. L'entità autenticata diventa l'entità attiva nella configurazione dell'interfaccia allagcloud CLId attiva. Se non vengono sostituite, gcloud CLI utilizza queste credenziali archiviate per accedere a Google Cloud.

Service account

Puoi utilizzare gcloud CLI con un account di servizio nei seguenti modi:

• Su una risorsa che espone un server di metadati Compute Engine, ad esempio un'istanza VM Compute Engine o un servizio Cloud Run. gcloud CLI utilizza per impostazione predefinita il account di servizio collegato alla risorsa per l'autenticazione.

• Utilizzando un'altra entità per rappresentare un account di servizio.

• Utilizzando una chiave del account di servizio.