Eseguire l'autenticazione per l'utilizzo di REST

Questa pagina descrive come eseguire l'autenticazione quando effettui una richiesta REST a un'API Google.

Per informazioni su come eseguire l'autenticazione quando utilizzi le librerie client di Google, consulta Eseguire l'autenticazione mediante le librerie client.

Prima di iniziare

Per eseguire i sample in questa pagina, completa i seguenti passaggi:

1. Install the Google Cloud CLI.

2. To initialize the gcloud CLI, run the following command:

   gcloud init

3. Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs:

   gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

Se non vuoi utilizzare gcloud CLI, puoi saltare questi passaggi e utilizzare l'appropriazione di identità dell'account di servizio o il server di metadati per generare un token.

Tipi di credenziali

Per autenticare una chiamata REST, puoi utilizzare i seguenti tipi di credenziali:

• Le tue credenziali gcloud CLI.

  Questo approccio è il modo più semplice e sicuro per fornire le credenziali a un metodo REST in un ambiente di sviluppo locale. Se il tuo account utente dispone delle autorizzazioni IAM (Identity and Access Management) necessarie per il metodo che vuoi chiamare, questo è l'approccio preferito.

  Le credenziali gcloud non sono le stesse fornite ad ADC utilizzando gcloud CLI. Per ulteriori informazioni, consulta la pagina sulla configurazione dell'autenticazione e della configurazione dell'ADC dell'interfaccia a riga di comando gcloud.

• Le credenziali fornite alle Credenziali predefinite dell'applicazione (ADC).

  Questo metodo è l'opzione preferita per autenticare una chiamata REST in un ambiente di produzione, perché l'ADC trova le credenziali dalla risorsa in cui viene eseguito il codice (ad esempio una macchina virtuale Compute Engine). Puoi anche utilizzare l'ADC per l'autenticazione in un ambiente di sviluppo locale. In questo scenario, gcloud CLI crea un file contenente le tue credenziali nel file system locale.

• Le credenziali fornite dalla simulazione dell'identità di un account di servizio.

  Questo metodo richiede una configurazione più complessa. Se vuoi utilizzare le tue credenziali esistenti per ottenere credenziali di breve durata per un altro account di servizio, ad esempio per eseguire test con un account di servizio localmente o richiedere privilegi elevati temporanei, utilizza questo approccio.

• Le credenziali restituite dal server di metadati.

  Questo metodo funziona solo in ambienti con accesso a un server dei metadati. Le credenziali restituite dal server di metadati sono le stesse che verrebbero trovate dalle credenziali predefinite dell'applicazione utilizzando l'account di servizio collegato, ma richiedi esplicitamente il token di accesso dal server di metadati e poi forniscilo con la richiesta REST. La query al server di metadati per le credenziali richiede una richiesta HTTP GET. Questo metodo non si basa su Google Cloud CLI.

Credenziali gcloud CLI

Per eseguire l'esempio riportato di seguito, devi disporre dell'autorizzazione resourcemanager.projects.get sul progetto. L'autorizzazione resourcemanager.projects.get è inclusa in diversi ruoli, ad esempio il ruolo Browser (roles/browser).

1. Utilizza il comando gcloud auth print-access-token per inserire un token di accesso generato dalle tue credenziali utente.

   L'esempio seguente recupera i dettagli del progetto specificato. Puoi utilizzare lo stesso schema per qualsiasi richiesta REST.

   Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

   • PROJECT_ID: l'ID o il nome del tuo progetto Google Cloud.

   Per inviare la richiesta, scegli una delle seguenti opzioni:

   curl

   Esegui questo comando:

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

   PowerShell

   Esegui questo comando:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

   Vengono restituiti i dettagli del progetto.

Per le API che richiedono un progetto quota, devi impostarne uno esplicitamente per la richiesta. Per saperne di più, consulta la sezione Impostare il progetto quota con una richiesta REST in questa pagina.

Credenziali predefinite dell'applicazione

Per eseguire l'esempio riportato di seguito, il principale associato alle credenziali fornite ad ADC deve disporre dell'autorizzazione resourcemanager.projects.get per il progetto. L'autorizzazione resourcemanager.projects.get è inclusa in diversi ruoli, ad esempio il ruolo Browser (roles/browser).

1. Fornisci le credenziali all'ADC.

   Se esegui l'operazione su una risorsa di calcolo Google Cloud, non devi fornire le tue credenziali utente ad ADC. Utilizza invece l'account di servizio collegato per fornire le credenziali. Per ulteriori informazioni, consulta Configurare l'accesso diretto alla rete per una risorsa con un account di servizio collegato.

2. Utilizza il comando gcloud auth application-default print-access-token per inserire il token di accesso restituito dall'ADC nella richiesta REST.

   L'esempio seguente recupera i dettagli del progetto specificato. Puoi utilizzare lo stesso schema per qualsiasi richiesta REST.

   Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

   • PROJECT_ID: l'ID o il nome del tuo progetto Google Cloud.

   Per inviare la richiesta, scegli una delle seguenti opzioni:

   curl

   Esegui questo comando:

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
        "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

   PowerShell

   Esegui questo comando:

   $cred = gcloud auth application-default print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

   Vengono restituiti i dettagli del progetto.

   Se la richiesta restituisce un messaggio di errore relativo al fatto che le credenziali utente finale non sono supportate da questa API, consulta Impostare il progetto quota con una richiesta REST in questa pagina.

Account di servizio con identità simulata

Il modo più semplice per rubare l'identità di un account di servizio per generare un token di accesso è utilizzare la gcloud CLI. Tuttavia, se devi generare il token programmaticamente o non vuoi utilizzare l'interfaccia alla gcloud CLI, puoi utilizzare l'usurpazione di identità per generare un token di breve durata.

Per ulteriori informazioni sull'impersonificazione di un account di servizio, consulta Utilizzare l'impersonificazione dell'account di servizio.

1. Esamina le autorizzazioni richieste.

   • Il principale che vuoi utilizzare per eseguire la simulazione dell'identità deve disporre dell'autorizzazione iam.serviceAccounts.getAccessToken per l'account di servizio impersonato (chiamato anche account di servizio con privilegi). L'autorizzazioneiam.serviceAccounts.getAccessToken è inclusa nel ruolo Creatore token account di servizioroles/iam.serviceAccountTokenCreator. Se utilizzi il tuo account utente, devi aggiungere questa autorizzazione anche se disponi del ruolo Proprietarioroles/owner nel progetto. Per ulteriori informazioni, consulta Impostare le autorizzazioni richieste.

2. Identifica o crea l'account di servizio con privilegi, ovvero l'account di servizio che rappresenterai.

   L'account di servizio con privilegi deve disporre delle autorizzazioni necessarie per effettuare la chiamata al metodo dell'API.

gcloud

1. Utilizza il comando gcloud auth print-access-token con il flag --impersonate-service-account per inserire un token di accesso per l'account di servizio con privilegi nella richiesta REST.

L'esempio seguente recupera i dettagli del progetto specificato. Puoi utilizzare lo stesso schema per qualsiasi richiesta REST.

Per eseguire questo esempio, il account di servizio che impersoni deve disporre dell'autorizzazioneresourcemanager.projects.get. L'autorizzazione resourcemanager.projects.get è inclusa in una serie di ruoli, ad esempio il ruolo Browser (roles/browser).

Effettua le seguenti sostituzioni:

• PRIV_SA: l'indirizzo email dell'account di servizio con i privilegi. Ad esempio, [e-mail].

• PROJECT_ID: l'ID o il nome del tuo progetto Google Cloud.

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=PRIV_SA)" \
    "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

Token di breve durata

Per generare un token di breve durata utilizzando l'impersonificazione dell'account di servizio, segui le istruzioni riportate in Creare un token di accesso di breve durata.

Server dei metadati

Per ottenere un token di accesso dal server dei metadati, devi effettuare la chiamata REST utilizzando uno dei servizi che ha accesso a un server dei metadati:

• Compute Engine
• Ambiente standard di App Engine
• Ambiente flessibile di App Engine
• Funzioni Cloud Run
• Cloud Run
• Google Kubernetes Engine
• Cloud Build

Utilizza uno strumento a riga di comando come curl per ottenere un token di accesso, quindi inseriscilo nella richiesta REST.

1. Esegui una query sul server dei metadati per ottenere un token di accesso:

   curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
       -H "Metadata-Flavor: Google"
   

   La richiesta restituisce una risposta simile al seguente esempio:

   {
         "access_token":"ya29.AHES6ZRN3-HlhAPya30GnW_bHSb_QtAi85nHq39HE3C2LTrCARA",
         "expires_in":3599,
         "token_type":"Bearer"
    }
   

2. Inserisci il token di accesso nella richiesta REST, apportando le seguenti sostituzione:

   • ACCESS_TOKEN: il token di accesso restituito nel passaggio precedente.
   • PROJECT_ID: l'ID o il nome del tuo progetto Google Cloud.

   curl -X GET \
       -H "Authorization: Bearer ACCESS_TOKEN" \
       "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"
   

Impostare il progetto quota con una richiesta REST

Per chiamare alcune API con le credenziali utente, devi anche impostare il progetto per cui viene fatturata la quota di utilizzo e utilizzato per monitorare la quota. Se la chiamata all'API restituisce un messaggio di errore che indica che le credenziali utente non sono supportate o che il progetto quota non è impostato, devi impostare esplicitamente il progetto quota per la richiesta. Per impostare il progetto quota, includi l'intestazione x-goog-user-project nella richiesta.

Per ulteriori informazioni sui casi in cui potresti riscontrare questo problema, consulta Credenziali utente non funzionanti.

Per poter designare un progetto come progetto di fatturazione, devi disporre dell'autorizzazione IAM serviceusage.services.use per quel progetto. L'autorizzazione serviceusage.services.use è inclusa nel ruolo IAM Consumer di utilizzo dei servizi. Se non disponi dell'autorizzazione serviceusage.services.use per nessun progetto, contatta l'amministratore della sicurezza o un proprietario del progetto che possa assegnarti il ruolo Consumer di utilizzo del servizio nel progetto.

Il seguente esempio utilizza l'API Cloud Translation per tradurre la parola "hello" in spagnolo. L'API Cloud Translation è un'API che richiede la specifica di un progetto quota. Per eseguire il sample, crea un file denominato request.json con i contenuti del corpo della richiesta.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

• PROJECT_ID: l'ID o il nome del progetto Google Cloud da utilizzare come progetto di fatturazione.

Corpo JSON della richiesta:

{
  "q": "hello",
  "source": "en",
  "target": "es"
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://translation.googleapis.com/language/translate/v2"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://translation.googleapis.com/language/translate/v2" | Select-Object -Expand Content

La richiesta di traduzione va a buon fine. Puoi provare il comando senza l'intestazione x-goog-user-project per vedere cosa succede quando non specifichi il progetto di fatturazione.

Passaggi successivi

• Consulta una panoramica dell'autenticazione.
• Scopri come eseguire l'autenticazione con le librerie client.
• Scopri la configurazione dell'autenticazione e dell'ADC dell'interfaccia a riga di comando gcloud .