Questa pagina descrive come eseguire l'autenticazione quando esegui una richiesta REST a un'API di Google.
Per informazioni su come eseguire l'autenticazione quando utilizzi le librerie client di Google, consulta Autenticazione tramite librerie client.
Prima di iniziare
Per eseguire gli esempi in questa pagina, completa i seguenti passaggi:
-
Installa Google Cloud CLI, quindi initialize eseguendo questo comando:
gcloud init
-
Abilita le API Cloud Resource Manager and Identity and Access Management (IAM).
gcloud services enable cloudresourcemanager.googleapis.com
iam.googleapis.com
Se non vuoi utilizzare gcloud CLI, puoi saltare questi passaggi e utilizzare il server di metadati per restituire 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 credenziali a un metodo REST in un ambiente di sviluppo locale. Se il tuo account utente dispone delle autorizzazioni di Identity and Access Management (IAM) necessarie per il metodo che vuoi chiamare, questo è l'approccio preferito.
Le tue credenziali gcloud non corrispondono a quelle che fornisci ad ADC utilizzando gcloud CLI. Per maggiori informazioni, consulta 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 ambiente di produzione, perché ADC trova le credenziali dalla risorsa su cui è in esecuzione il codice (ad esempio una macchina virtuale Compute Engine). Puoi anche utilizzare ADC per l'autenticazione in un ambiente di sviluppo locale. In questo scenario, gcloud CLI crea un file che contiene le tue credenziali nel tuo file system locale.
Le credenziali fornite dall'identità di un account di servizio.
Questo metodo richiede una configurazione maggiore. Utilizza questo approccio se vuoi utilizzare le credenziali esistenti per ottenere credenziali di breve durata per un altro account di servizio, ad esempio eseguire test in locale con un account di servizio o richiedere privilegi elevati temporanei.
Le credenziali restituite dal server dei metadati.
Questo metodo funziona solo in ambienti con accesso a un server di metadati. Le credenziali restituite dal server di metadati sono le stesse che si trovano in Credenziali predefinite dell'applicazione utilizzando l'account di servizio collegato, ma richiedi esplicitamente il token di accesso dal server dei metadati e quindi fornisci la richiesta REST. L'esecuzione di query sul server di metadati per verificare le credenziali richiede una richiesta HTTP GET; questo metodo non si basa su Google Cloud CLI.
Credenziali gcloud CLI
Per eseguire l'esempio in basso, devi disporre dell'autorizzazione resourcemanager.projects.get
per il progetto. L'autorizzazione resourcemanager.projects.get
è inclusa in una serie di ruoli, ad esempio il ruolo Browser (roles/browser
).
Utilizza il comando
gcloud auth print-access-token
per inserire un token di accesso generato dalle tue credenziali utente.L'esempio seguente restituisce i dettagli del progetto specificato. Puoi utilizzare 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 ContentVengono restituiti i dettagli del progetto.
Per le API che richiedono un progetto di quota, devi impostarne uno esplicitamente per la richiesta. Per maggiori informazioni, consulta Impostare il progetto di quota con una richiesta REST in questa pagina.
Credenziali predefinite dell'applicazione
Per eseguire l'esempio seguente, l'entità associata alle credenziali che fornisci 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
).
Fornisci le credenziali all'ADC.
Se esegui su una risorsa di computing Google Cloud, non devi fornire le credenziali utente ad ADC. Usa invece l'account di servizio collegato per fornire le credenziali. Per ulteriori informazioni, vedi Servizi che supportano il collegamento di un account di servizio.
Utilizza il comando
gcloud auth application-default print-access-token
per inserire il token di accesso restituito da ADC nella richiesta REST.L'esempio seguente restituisce i dettagli del progetto specificato. Puoi utilizzare 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 ContentVengono 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 questa API, consulta Impostare il progetto di quota con una richiesta REST in questa pagina.
Account di servizio con identità
Per ulteriori informazioni sull'identità di un account di servizio, consulta Utilizzare la simulazione dell'identità degli account di servizio.
Rivedi le autorizzazioni richieste.
Il tuo account utente 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 servizio (roles/iam.serviceAccountTokenCreator
). È necessaria anche se disponi del ruolo Proprietario (roles/owner
) per il progetto. Per maggiori informazioni, consulta la sezione Impostare le autorizzazioni richieste.Nell'esempio riportato di seguito, l'account di servizio di cui stai impersonando deve avere l'autorizzazione
resourcemanager.projects.get
per il progetto. L'autorizzazioneresourcemanager.projects.get
è inclusa in diversi ruoli, ad esempio il ruolo Browser (roles/browser
).
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 di metodo API.
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 pattern per qualsiasi richiesta REST.
Per eseguire questo esempio, l'account di servizio che impersoni deve avere l'autorizzazione
resourcemanager.projects.get
. L'autorizzazioneresourcemanager.projects.get
è inclusa in diversi ruoli, ad esempio nel ruolo Browser (roles/browser
).Effettua le seguenti sostituzioni:
PRIV_SA
: l'indirizzo email dell'account di servizio con privilegi. Ad esempio,my-sa@my-project.iam.gserviceaccount.com
.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 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
- Cloud Functions
- Cloud Run
- Google Kubernetes Engine
- Cloud Build
Puoi utilizzare uno strumento a riga di comando come curl
per ottenere un token di accesso, quindi inserirlo nella richiesta REST.
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" }
Inserisci il token di accesso nella richiesta REST, apportando le seguenti sostituzioni:
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"
Imposta il progetto di quota con una richiesta REST
Per chiamare alcune API con credenziali utente, devi anche impostare il progetto che ti viene
addebitato per l'utilizzo e utilizzato per monitorare la quota. Se la chiamata API restituisce un messaggio di errore che indica che le credenziali utente non sono supportate o che il progetto di quota non è impostato, devi impostare esplicitamente il progetto di quota per la richiesta.
Per impostare il progetto di quota, includi l'intestazione x-goog-user-project
nella tua richiesta.
Per ulteriori informazioni su quando potresti riscontrare questo problema, consulta Credenziali utente non funzionanti.
Devi disporre dell'autorizzazione IAM serviceusage.services.use
affinché un progetto possa designarlo come progetto di fatturazione. L'autorizzazione serviceusage.services.use
è inclusa nel ruolo IAM consumer di Service Usage. Se non hai l'autorizzazione serviceusage.services.use
per alcun progetto, contatta l'amministratore della sicurezza o un proprietario
del progetto che possa concederti il ruolo consumer di Service Usage nel progetto.
L'esempio seguente 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 di 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
ed esegui questo comando:
$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'intestazione x-goog-user-project
per vedere cosa succede se 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 .