Autenticazione con 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, vedi Autenticazione mediante librerie client.

Prima di iniziare

Per eseguire gli esempi in questa pagina, completa i seguenti passaggi:

  1. Installa Google Cloud CLI.

  2. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  3. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

  4. Abilita le API Cloud Resource Manager e Identity and Access Management (IAM):

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l' serviceusage.services.enable autorizzazione. Scopri come concedere i ruoli. 

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

Se non vuoi utilizzare gcloud CLI, puoi saltare questi passaggi e utilizzare la simulazione dell'identità dei service account o il server di metadati per generare un token.

Tipi di credenziali

Puoi utilizzare i seguenti tipi di credenziali per autenticare una chiamata REST:

  • Le 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 che fornisci ad ADC utilizzando gcloud CLI. Per saperne di più, consulta Configurazione dell'autenticazione con gcloud CLI e configurazione ADC.

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

    Questo metodo è l'opzione preferita per l'autenticazione di una chiamata REST in un ambiente di produzione, perché ADC trova le credenziali dalla risorsa in 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 contenente le tue credenziali nel file system locale.

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

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

  • Le credenziali restituite dal server di metadati.

    Questo metodo funziona solo negli ambienti con accesso a un server di metadati. Le credenziali restituite dal server di metadati sono le stesse che verrebbero trovate da Credenziali predefinite dell'applicazione utilizzando il account di servizio collegato, ma richiedi esplicitamente il token di accesso dal server di metadati e poi lo fornisci con la richiesta REST. L'esecuzione di query sul server di metadati per le credenziali richiede una richiesta GET HTTP; questo metodo non si basa su Google Cloud CLI.

  • Chiavi API

    Puoi utilizzare una chiave API con una richiesta REST solo per le API che accettano chiavi API. Inoltre, la chiave API non deve essere limitata per impedirne l'utilizzo con l'API.

Credenziali gcloud CLI

Per eseguire l'esempio seguente, 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 Visualizzatore (roles/browser).

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

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

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

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

    Per inviare la richiesta, scegli una di queste 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 impostarne uno in modo esplicito per la richiesta. Per saperne di più, vedi 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 una serie di ruoli, ad esempio il ruolo Visualizzatore (roles/browser).

  1. Fornisci le credenziali ad ADC.

    Se esegui l'applicazione su una risorsa di computing Google Cloud , non devi fornire le tue credenziali utente ad ADC. Utilizza invece il service account collegato per fornire le credenziali. Per saperne di più, vedi Configurare ADC per una risorsa con un service account collegato.

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

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

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

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

    Per inviare la richiesta, scegli una di queste 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 che indica che le credenziali dell'utente finale non sono supportate da questa API, vedi Impostare il progetto di quota con una richiesta REST in questa pagina.

Account di servizio con identità simulata

Il modo più semplice per simulare l'identità di un account di servizio per generare un token di accesso è utilizzare gcloud CLI. Tuttavia, se devi generare il token a livello di programmazione o non vuoi utilizzare gcloud CLI, puoi utilizzare la simulazione dell'identità per generare un token di breve durata.

Per saperne di più sulla simulazione dell'identità di un account di servizio, vedi Utilizzare account di servizio account.

  1. Esamina le autorizzazioni richieste.

    • L'entità che vuoi utilizzare per eseguire la simulazione dell'identità deve disporre dell'autorizzazione iam.serviceAccounts.getAccessToken sul account di servizio con identità simulata (chiamato anche service account con privilegi). L'autorizzazione iam.serviceAccounts.getAccessToken è inclusa nel ruolo Creatore token account di servizio (roles/iam.serviceAccountTokenCreator). Se utilizzi il tuo account utente, devi aggiungere questa autorizzazione anche se disponi del ruolo Proprietario (roles/owner) nel progetto. Per saperne di più, vedi Impostare le autorizzazioni richieste.

  2. Identifica o crea il account di servizio con privilegi, ovvero il account di servizio di cui simulerai l'identità.

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

gcloud

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

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

Per eseguire questo esempio, il account di servizio di cui simuli l'identità deve disporre dell'autorizzazione resourcemanager.projects.get. L'resourcemanager.projects.get autorizzazione è inclusa in una serie di ruoli, ad esempio il ruolo Visualizzatore (roles/browser).

Apporta le seguenti sostituzioni:

  • PRIV_SA: l'indirizzo email del account di servizio con privilegi. Ad esempio, my-sa@my-project.iam.gserviceaccount.com.

  • PROJECT_ID: l'ID progetto o il nome del 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 la simulazione dell'identità dei account di servizio, segui le istruzioni riportate in Creare un token di accesso di breve durata.

Server di metadati

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

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 di metadati per 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 sostituzioni:

    • ACCESS_TOKEN: il token di accesso restituito nel passaggio precedente.
    • PROJECT_ID: l'ID progetto o il nome del progetto. Google Cloud 
    curl -X GET \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

Chiavi API

Per includere una chiave API in una chiamata API REST, utilizza l'intestazione HTTP x-goog-api-key, come mostrato nell'esempio seguente:

curl -X POST \
    -H "X-goog-api-key: API_KEY" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://translation.googleapis.com/language/translate/v2"

Se non puoi utilizzare l'intestazione HTTP, puoi utilizzare il parametro di query key. Tuttavia, questo metodo include la chiave API nell'URL, esponendola al furto tramite le scansioni degli URL.

L'esempio seguente mostra come utilizzare il parametro di query key con una richiesta dell'API Cloud Natural Language per documents.analyzeEntities. Sostituisci API_KEY con la stringa della chiave API.

POST https://language.googleapis.com/v1/documents:analyzeEntities?key=API_KEY

Impostare il progetto di quota con una richiesta REST

Per chiamare alcune API con le credenziali utente, devi anche impostare il progetto a cui viene addebitato 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 in modo esplicito il progetto di quota per la richiesta. Per impostare il progetto di quota, includi l'intestazione x-goog-user-project nella richiesta.

Per saperne di più su quando potresti riscontrare questo problema, vedi Le credenziali utente non funzionano.

Devi disporre dell'autorizzazione IAM serviceusage.services.use per un progetto per poterlo designare come progetto di fatturazione. L'autorizzazione serviceusage.services.use è inclusa nel ruolo IAM Consumer utilizzo servizi. Se non disponi dell'autorizzazione serviceusage.services.use per alcun progetto, contatta l'amministratore della sicurezza o un Project Owner che può assegnarti il ruolo Consumer 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, apporta le sostituzioni seguenti:

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, e 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, e 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 HTTP x-goog-user-project per vedere cosa succede quando non specifichi il progetto di fatturazione.

Passaggi successivi