Eseguire l'autenticazione per l'utilizzo di REST

In questa pagina viene descritto come eseguire l'autenticazione quando inviare una richiesta REST a un'API di 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 il server dei metadati per restituire un token.

Tipi di credenziali

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

• Le tue credenziali dell'interfaccia a riga di comando gcloud.

  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 tue credenziali gcloud non corrispondono a quelle che fornisci ad ADC utilizzando con gcloud CLI. Per ulteriori informazioni, vedi configurazione dell'autenticazione gcloud CLI e configurazione ADC.

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

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

• Le credenziali fornite dall'identità di un account di servizio.

  Questo metodo richiede una configurazione maggiore. Se vuoi utilizzare il tuo modello di attribuzione esistente per ottenere credenziali di breve durata per un altro account di servizio, ad esempio test con un account di servizio localmente o richiedendo tempo a privilegi elevati, utilizza questo approccio.

• Le credenziali restituite dal server dei 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. L'esecuzione di query il 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 la 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 lo stesso pattern per qualsiasi richiesta REST.

   Prima di utilizzare i dati della richiesta, effettua 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 di quota, devi impostare uno 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, l'entità associata alle credenziali che fornire ad ADC richiede l'autorizzazione resourcemanager.projects.get nella 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 i servizi che supportano l'attacco di un account di servizio.

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 lo stesso pattern per qualsiasi richiesta REST.

   Prima di utilizzare i dati della richiesta, effettua 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 tua richiesta restituisce un messaggio di errore che indica che le credenziali dell'utente finale non sono supportate da questo documento per l'API, consulta Impostare il progetto di quota con una richiesta REST su questo .

Account di servizio con identità

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

1. Esamina le autorizzazioni richieste.

   • Il tuo account utente deve disporre dell'autorizzazione iam.serviceAccounts.getAccessToken per l'account di servizio simulato (chiamato anche account di servizio con privilegi). L'autorizzazione iam.serviceAccounts.getAccessToken è inclusa nel ruolo Creatore token account di servizio (roles/iam.serviceAccountTokenCreator). Questa autorizzazione è necessaria anche se disponi del ruolo Proprietario (roles/owner) nel progetto. Per ulteriori informazioni, consulta Impostare le autorizzazioni richieste.

   • Nell'esempio riportato di seguito, l'account di servizio che stai impersonando deve dispongono dell'autorizzazione resourcemanager.projects.get per il progetto. L'autorizzazione resourcemanager.projects.get è inclusa in diversi ruoli, ad esempio il ruolo Browser (roles/browser).

2. Identifica o crea l'account di servizio con privilegi: l'account di servizio. che impersonerai.

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

3. 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 restituisce i dettagli del progetto specificato. Puoi utilizzare lo stesso schema per qualsiasi richiesta REST.

   Per eseguire questo esempio, l'account di servizio che impersoni deve avere la Autorizzazione resourcemanager.projects.get. resourcemanager.projects.get è inclusa in vari ruoli, ad esempio Ruolo browser (roles/browser).

   Effettua le seguenti sostituzioni:

   • PRIV_SA: l'indirizzo email dell'amministratore del privilegio l'account di servizio. 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"
   

Server dei metadati

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

• Compute Engine
• Ambiente standard di App Engine
• Ambiente flessibile di App Engine
• Funzioni di 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 recuperare 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 all'esempio seguente:

   {
         "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 che addebitati per l'utilizzo e utilizzati per tenere traccia della 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 di quota, includi l'intestazione x-goog-user-project con la tua richiesta.

Per ulteriori informazioni su quando potresti riscontrare questo problema, vedi Le credenziali utente non funzionano.

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 hai serviceusage.services.use l'autorizzazione per qualsiasi progetto, contatta l'amministratore della sicurezza o che può concederti il ruolo consumer di Service Usage 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 l'esempio, crea un file denominato request.json con i contenuti del corpo della richiesta.

Prima di utilizzare i dati della richiesta, effettua 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. ed esegui questo comando:

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 è andata a buon fine. Puoi provare il comando senza l'x-goog-user-project 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 di più sulla configurazione dell'autenticazione dell'interfaccia a riga di comando gcloud e della configurazione ADC .