Autorizza gcloud CLI

Per accedere a Google Cloud, in genere devi autorizzare Google Cloud CLI. Questa pagina mostra le opzioni di autorizzazione disponibili e spiega come gestire gli account che utilizzi per l'autorizzazione. Se utilizzi un'istanza Compute Engine o Cloud Shell, non è necessario autorizzare la gcloud CLI.

Tipi di account

Per concedere l'autorizzazione alla gcloud CLI per accedere a Google Cloud, puoi utilizzare un account utente o un account di servizio.

Un account utente è un account Google Cloud che consente agli utenti finali di autenticarsi nella tua applicazione. Per la maggior parte dei casi d'uso comuni, in particolare per l'utilizzo interattivo dell'interfaccia a riga di comando gcloud, è consigliabile utilizzare un account utente.

Un account di servizio è un account Google Cloud associato al tuo progetto Google Cloud e non a un utente specifico. Puoi utilizzare l'account di servizio integrato disponibile quando utilizzi funzioni Cloud Run, App Engine, Compute Engine o Google Kubernetes Engine. Ti consigliamo di utilizzare un account di servizio per eseguire script gcloud CLI su più macchine.

Scegli un tipo di autorizzazione

Devi autorizzare Google Cloud CLI a gestire le risorse di Google Cloud. Sia Google Cloud CLI sia Google Cloud utilizzano OAuth 2.0 per l'autenticazione e l'autorizzazione.

Scegli uno dei seguenti tipi di autorizzazione:

Tipo Descrizione
Account utente Consigliato se utilizzi l'interfaccia alla gcloud CLI dalla riga di comando o se scrivi script con l'interfaccia alla gcloud CLI da utilizzare su una singola macchina.
Service account Consigliato se stai installando e configurando la gcloud CLI nell'ambito di un processo di deployment delle macchine in produzione o per l'utilizzo su istanze di macchine virtuali Compute Engine in cui tutti gli utenti hanno accesso a root.

Per ulteriori informazioni sull'autenticazione e su Google Cloud, consulta la panoramica sull'autenticazione.

Autorizzazione con un account utente

Questa sezione descrive come eseguire l'autorizzazione con un account utente.

Autenticazione con un Account Google

Utilizza i seguenti comandi gcloud CLI per autorizzare l'accesso con un account utente:

Comando Descrizione
gcloud init Autorizza l'accesso ed esegue altri passaggi di configurazione comuni.
gcloud auth login Consente solo l'accesso.

Durante l'autorizzazione, questi comandi ottengono le credenziali dell'account da Google Cloud e le memorizzano nel sistema locale. L'account specificato diventa l'account attivo nella configurazione. Gcloud CLI utilizza le credenziali memorizzate per accedere a Google Cloud. Puoi avere un numero qualsiasi di account con credenziali memorizzate per una singola installazione gcloud CLI, ma solo un account è attivo alla volta.

Run gcloud init

gcloud init autorizza l'accesso ed esegue altri passaggi di configurazione comuni. gcloud init utilizza un flusso di autorizzazione basato sul web per autenticare l'account utente e concedere le autorizzazioni di accesso.

Per autorizzare l'accesso ed eseguire altri passaggi di configurazione comuni:

  1. Esegui gcloud init:

    gcloud init

    In alternativa, per impedire al comando di aprire automaticamente un browser web:

    gcloud init --console-only

    L'utilizzo del flag --console-only è utile se esegui il comando su un sistema remoto utilizzando ssh e non hai accesso a un browser su quel sistema. Per completare la procedura di autorizzazione, devi aprire manualmente l'URL fornito in un browser sul tuo sistema locale.

  2. Segui la procedura di autorizzazione basata sul browser per autenticare l'account e concedere le autorizzazioni di accesso.

Per ulteriori informazioni su gcloud init, consulta Inizializza la gcloud CLI.

Esegui gcloud auth login

L'esecuzione di gcloud auth login autorizza solo l'account utente. Per autorizzare l'accesso senza eseguire altri passaggi di configurazione, utilizza una delle seguenti opzioni.

  • Se vuoi autorizzare gcloud CLI su una macchina con un browser, segui questi passaggi.

    1. Autorizza gcloud CLI:

      gcloud auth login

    2. Segui la procedura di autorizzazione basata sul browser per autenticare l'account e concedere le autorizzazioni di accesso.

  • Se vuoi autorizzare l'interfaccia a riga di comando gcloud su una macchina che non ha un browser e puoi installarla su un'altra macchina con un browser, utilizza il flag --no-browser.

    1. Autorizza gcloud CLI:

      gcloud auth login --no-browser

    2. Copia il comando lungo che inizia con gcloud auth login --remote-bootstrap=".

    3. Incolla ed esegui questo comando nella riga di comando di un'altra macchina attendibile su cui sono installati sia un browser web sia lo strumento gcloud CLI nella versione 372.0 o successive.

    4. Copia l'URL lungo in uscita dalla macchina con il browser web.

    5. Incolla l'URL lungo nella prima macchina sotto il prompt "Inserisci l'output del comando precedente" e premi Invio per completare l'autorizzazione.

  • Se vuoi autorizzare gcloud CLI su una macchina che non ha un browser e non puoi installare gcloud CLI su un'altra macchina con un browser, utilizza il flag --no-launch-browser. Il --no-launch-browser impedisce al comando di aprire automaticamente un browser web.

    1. Autorizza gcloud CLI:

      gcloud auth login --no-launch-browser

    2. Copia l'URL lungo che inizia con https://accounts.google.com/o/oauth2/auth...

    3. Incolla questo URL nel browser di un'altra macchina attendibile con un browser web.

    4. Copia il codice di autorizzazione dalla macchina con il browser web.

    5. Incolla il codice di autorizzazione nella prima macchina quando richiesto, "Inserisci il codice di verifica", e premi Invio per completare l'autorizzazione.

  • Se hai già un token di accesso, utilizza uno dei seguenti metodi per trasmetterlo all'interfaccia a riga di comando gcloud:

    • Memorizza il token di accesso in un file e imposta il relativo percorso tramite il flag --access-token-file.
    • Memorizza il token di accesso in un file e imposta il relativo percorso nella proprietà auth/access_token_file.
    • Imposta la variabile di ambiente CLOUDSDK_AUTH_ACCESS_TOKEN sul valore del token di accesso.

Autenticazione con la federazione delle identità della forza lavoro

Questa sezione descrive come accedere alla gcloud CLI utilizzando la federazione delle identità della forza lavoro.

Accesso basato su browser all'interfaccia a riga di comando gcloud

Per accedere a gcloud CLI utilizzando un flusso di accesso basato su browser, segui questi passaggi:

  1. Crea un file di configurazione di accesso.

    Per creare il file di configurazione di accesso, esegui il seguente comando. Facoltativamente, puoi attivare il file come predefinito per gcloud CLI utilizzando il flag --activate. 

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

    Sostituisci quanto segue:

    • WORKFORCE_POOL_ID: l'ID del pool di identità della forza lavoro
    • PROVIDER_ID: l'ID del provider del pool di identità della forza lavoro
    • LOGIN_CONFIG_FILE: un percorso al file di configurazione di accesso specificato, ad esempio login.json

    Il file contiene gli endpoint utilizzati dalla gcloud CLI per attivare il flusso di autenticazione basato sul browser e impostare il segmento di pubblico sull'IdP configurato nel provider del pool di identità della forza lavoro. Il file non contiene informazioni riservate.

    L'output è simile al seguente:

    {
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/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. Accedi utilizzando l'autenticazione basata sul browser.

    Per eseguire l'autenticazione utilizzando l'autenticazione di accesso basata sul browser, puoi utilizzare uno dei seguenti metodi:

    • Se hai utilizzato il flag --activate quando hai creato il file di configurazione o se lo hai attivato con gcloud config set auth/LOGIN_CONFIG_FILE, la gcloud CLI lo utilizza automaticamente: 

      gcloud auth login

    • Per accedere specificando la posizione del file di configurazione, esegui il seguente comando: 

      gcloud auth login --login-config=LOGIN_CONFIG_FILE
    • Per utilizzare una variabile di ambiente per specificare la posizione del file di configurazione, imposta CLOUDSDK_AUTH_LOGIN_CONFIG_FILE sul percorso di configurazione.

Per interrompere l'utilizzo del file di configurazione dell'accesso:

  • Se hai utilizzato il flag --activate quando hai creato il file di configurazione o se lo hai attivato con gcloud config set auth/LOGIN_CONFIG_FILE, devi eseguire il seguente comando per annullarne l'impostazione: 

    gcloud config unset auth/login_config_file
  • Cancella la variabile di ambiente CLOUDSDK_AUTH_LOGIN_CONFIG_FILE, se impostata.

Accesso headless all'interfaccia a riga di comando gcloud CLI

Per accedere a gcloud CLI utilizzando un flusso headless:

OIDC

  1. Fai accedere un utente all'app del tuo provider di identità e ottieni il token OIDC.

    Per informazioni su come ottenere il token, consulta la documentazione OIDC dell'IdP.

  2. Salva il token OIDC restituito dall'IdP in un luogo sicuro sul tuo computer locale.

  3. Genera un file di configurazione eseguendo il seguente comando:

    gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type="urn:ietf:params:oauth:token-type:id_token" \
    --credential-source-file="PATH_TO_OIDC_ID_TOKEN" \
    --workforce-pool-user-project="WORKFORCE_POOL_USER_PROJECT" \
    --output-file="config.json"

Sostituisci quanto segue:

  • WORKFORCE_POOL_ID: l'ID del pool di forza lavoro
  • PROVIDER_ID: l'ID provider
  • PATH_TO_OIDC_TOKEN: il percorso del file delle credenziali dell'identità OIDC
  • WORKFORCE_POOL_USER_PROJECT: il numero del progetto associato al progetto utente dei pool di forze lavoro

L'entità deve disporre dell'autorizzazione serviceusage.services.use per questo progetto.

Quando esegui il comando, viene generato un file di configurazione dell'IdP OIDC con un formato simile al seguente:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS_FILE"
  }
}

SAML

  1. Fai accedere un utente all'app IdP e ottieni l'asserzione SAML.

    Per informazioni su come ottenere l'asserzione SAML dal tuo IdP, consulta la documentazione SAML dell'IdP.

  2. Salva la risposta SAML restituita dall'IdP in una posizione sicura sul tuo computer locale, quindi memorizza il percorso come segue:

    SAML_ASSERTION_PATH=SAML_ASSERTION_PATH

  3. Per generare un file di configurazione, esegui il seguente comando:

    gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type="urn:ietf:params:oauth:token-type:saml2" \
    --credential-source-file="SAML_ASSERTION_PATH"  \
    --workforce-pool-user-project="PROJECT_ID"  \
    --output-file="config.json"

    Sostituisci quanto segue:

    • WORKFORCE_PROVIDER_ID: l'ID del fornitore della forza lavoro creato in precedenza in questa guida.
    • WORKFORCE_POOL_ID: l'ID pool di forza lavoro creato in precedenza in questa guida.
    • SAML_ASSERTION_PATH: il percorso del file di affermazione SAML.
    • PROJECT_ID: l'ID progetto

    Il file di configurazione generato è simile al seguente:

    {
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "credential_source": {
    "file": "SAML_ASSERTION_PATH"
  },
  "workforce_pool_user_project": "PROJECT_ID"
}

Per accedere a gcloud utilizzando lo scambio di token, esegui il seguente comando:

gcloud auth login --cred-file="config.json"

gcloud scambia quindi in modo trasparente le tue credenziali IdP con token di accesso temporanei di Google Cloud, consentendoti di effettuare altre chiamate gcloud a Google Cloud.

L'output è simile al seguente:

Authenticated with external account user credentials for:
[principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/USER_ID].

Per elencare gli account con credenziali e il tuo account attualmente attivo, esegui il seguente comando:

gcloud auth list

Autorizzazione con un account di servizio

Il comando gcloud auth login può autorizzare l'accesso con un account di servizio utilizzando un file delle credenziali memorizzato nel file system locale. Questa credenziale può essere una credenziale utente con autorizzazione per appropriarsi dell'identità del account di servizio, un file di configurazione delle credenziali per la federazione delle identità per i carichi di lavoro o una chiave del account di servizio.

Autorizza un account di servizio utilizzando l'impersonificazione dell'account di servizio

Per autorizzare gcloud CLI a utilizzare le credenziali dell'account di servizio sotto mentite spoglie, svolgi i seguenti passaggi:

  1. Nella console Google Cloud, vai alla pagina Account di servizio.

    Vai a Service account

  2. Scegli un account esistente o creane uno nuovo facendo clic su Crea account di servizio.

  3. Per assicurarti che il principale disponga dell'autorizzazione necessaria per rubare l'identità di un account di servizio, chiedi all'amministratore di concedere al principale il ruolo IAM Creatore token account di servizio (roles/iam.serviceAccountTokenCreator) nell'account di servizio. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

    Questo ruolo predefinito contiene l'autorizzazione iam.serviceAccounts.getAccessToken necessaria per impersonare un account di servizio.

    L'amministratore potrebbe anche assegnare all'entità questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

  4. Autorizza gcloud CLI con la tua identità utente eseguendo gcloud auth login.

  5. Per configurare gcloud CLI in modo che utilizzi per impostazione predefinita l'identità e l'accesso forniti da un account di servizio, utilizza il comando gcloud CLI config:

    gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL

  6. Per interrompere l'utilizzo delle credenziali dell'account di servizio impersonate con gcloud CLI per impostazione predefinita, annulla l'impostazione del flag con il comando gcloud CLI config:

    gcloud config unset auth/impersonate_service_account

Autorizza un account di servizio utilizzando la federazione delle identità per i carichi di lavoro

Per autorizzare gcloud CLI con un account di servizio che utilizza le credenziali esterne della federazione delle identità per i carichi di lavoro, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina Account di servizio.

    Vai a Service account

  2. Scegli un account esistente o creane uno nuovo facendo clic su Crea account di servizio.

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

  4. Per attivare l'account di servizio, esegui gcloud auth login con il --cred-file flag:

    gcloud auth login --cred-file=CONFIGURATION_FILE

    Sostituisci CONFIGURATION_FILE con il percorso di un file di configurazione delle credenziali per la federazione delle identità per i carichi di lavoro.

Autorizzare un account di servizio utilizzando una chiave dell'account di servizio

Per autorizzare gcloud CLI con un account di servizio utilizzando una chiave dell'account di servizio, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina Account di servizio.

    Vai a Service account

  2. Scegli un account esistente o creane uno nuovo facendo clic su Crea account di servizio.

  3. Per creare chiavi dell'account di servizio, consulta le istruzioni di IAM per creare una chiave dell'account di servizio.

  4. Per attivare l'account di servizio, esegui gcloud auth login con il --cred-file flag:

    gcloud auth login --cred-file=KEY_FILE

    Sostituisci KEY_FILE con il percorso di un file della chiave dell'account di servizio.

Elenco account

Per elencare gli account le cui credenziali sono archiviate nel sistema locale, esegui gcloud auth list:

gcloud auth list

L'interfaccia a riga di comando gcloud elenca gli account e mostra quale è attivo:

Credentialed accounts:
 - user-1@gmail.com (active)
 - user-2@gmail.com

Cambiare l'account attivo

Per cambiare l'account attivo, esegui gcloud config set:

gcloud config set account ACCOUNT

dove [ACCOUNT] è l'indirizzo email completo dell'account.

Puoi anche cambiare account creando una configurazione separata che specifichi l'account diverso e passando da una configurazione all'altra:

gcloud config configurations activate CONFIGURATION

Se vuoi cambiare l'account utilizzato da gcloud CLI su base singola chiamata, sostituisci l'account attivo utilizzando il flag --account.

Impostare la durata della sessione autorizzata

In qualità di amministratore, puoi specificare per quanto tempo diversi utenti possono accedere alla gcloud CLI senza dover ripetere l'autenticazione. Ad esempio, puoi obbligare gli utenti con privilegi elevati a eseguire nuovamente l'autenticazione più frequentemente rispetto agli utenti normali.

Per ulteriori informazioni, consulta Impostare la durata della sessione per i servizi Google Cloud.

Revocare le credenziali di un account

Puoi revocare le credenziali quando vuoi impedire l'accesso da parte della gcloud CLI da un determinato account. Non è necessario revocare le credenziali per passare da un account all'altro.

Per revocare le credenziali, esegui gcloud auth revoke:

gcloud auth revoke ACCOUNT

Per revocare tutto l'accesso per gcloud CLI per tutte le macchine, rimuovi gcloud CLI dall'elenco delle app che hanno accesso al tuo account.

Utilizzare i file delle credenziali

Trovare i file delle credenziali

Per trovare la posizione dei file delle credenziali, esegui gcloud info:

gcloud info

Gcloud CLI stampa le informazioni sull'installazione. I file delle credenziali sono archiviati nella directory di configurazione dell'utente:

User Config Directory: [/home/USERNAME/.config/gcloud]

Configurare le Credenziali predefinite dell'applicazione

Gcloud CLI fornisce il supporto per la gestione delle credenziali predefinite per le applicazioni (ADC) con il gruppo di comandi gcloud auth application-default. Per rendere disponibili le credenziali utente per l'ADC, esegui gcloud auth application-default login:

gcloud auth application-default login

Queste credenziali non vengono utilizzate dall'interfaccia a riga di comando gcloud. Per altri modi per configurare le credenziali predefinite dell'applicazione, consulta Configurare le credenziali predefinite dell'applicazione.

unset GOOGLE_APPLICATION_CREDENTIALS
gcloud config unset auth/impersonate_service_account
gcloud auth application-default login

Passaggi successivi