Esegui l'autenticazione per le chiamate (1ª gen.)

Per richiamare una funzione Cloud Run autenticata, l'entità sottostante deve soddisfare i seguenti requisiti:

• Disporre dell'autorizzazione per richiamare la funzione.
• Fornire un token ID quando richiama la funzione.

Che cos'è un'entità? Come descritto in Proteggi la funzione Cloud Run, Cloud Run Functions supporta due diversi tipi di identità, dette anche entità:

• Service account: si tratta di account speciali che fungono da identità non corrispondenti a una persona, ad esempio una funzione, un'applicazione o una VM. Ti offrono un modo per autenticare questi tipi di identità.
• Account utente: questi account rappresentano persone, sia come proprietari di Account Google individuali sia come parte di un'entità controllata da Google, come un gruppo Google.

Consulta la panoramica di IAM per saperne di più sui concetti di base di IAM.

Per richiamare una funzione Cloud Run autenticata, l'entità deve disporre dell'autorizzazione IAM invoker:

• cloudfunctions.functions.invoke. In genere questa autorizzazione viene concessa tramite il ruolo Invoker.

Per concedere queste autorizzazioni, utilizza il comando add-invoker-policy-binding, come mostrato in Autenticazione delle chiamate da funzione a funzione.

Per disporre dell'autorizzazione per creare, aggiornare o eseguire altre azioni amministrative su una funzione, l'entità deve avere un ruolo appropriato. I ruoli includono autorizzazioni che definiscono le azioni che l'entità può eseguire. Per saperne di più, consulta Utilizzo di IAM per autorizzare l'accesso.

La chiamata di una funzione può presentare ulteriori complessità. Le funzioni basate su eventi possono essere richiamate solo dall'origine evento a cui sono iscritte, mentre le funzioni HTTP possono essere richiamate da diversi tipi di identità, provenienti da posizioni diverse. L'invoker potrebbe essere uno sviluppatore che sta testando la funzione oppure un'altra funzione o un servizio che vuole utilizzare la funzione. Per impostazione predefinita, queste identità devono fornire un token ID con la richiesta per autenticarsi. Inoltre, all'account in uso devono essere state concesse le autorizzazioni appropriate.

Scopri di più su come generare e utilizzare i token ID.

Nota: tutte le funzioni possono essere richiamate utilizzando l'API di chiamata. Questa API deve essere utilizzata solo a scopo di test. Non utilizzarla in produzione.

Esempi di autenticazione

Questa sezione mostra alcuni esempi diversi di autenticazione della chiamata.

Esempio 1: autenticazione dei test degli sviluppatori

In qualità di sviluppatore, devi disporre dell'accesso per creare, aggiornare ed eliminare funzioni e questo accesso viene concesso utilizzando la normale procedura IAM.

Tuttavia, come sviluppatore, potresti avere la necessità di richiamare le tue funzioni a scopo di test. Per richiamare una funzione utilizzando curl o strumenti simili, tieni presente quanto segue:

• Assegna al tuo account utente Cloud Run Functions un ruolo che contenga l'autorizzazione di chiamata.

  • cloudfunctions.functions.invoke. In genere questa autorizzazione viene concessa tramite il ruolo Invoker. Per impostazione predefinita, i ruoli Cloud Run functions Admin e Cloud Run functions Developer dispongono di questa autorizzazione. Consulta Ruoli IAM di Cloud Run Functions per l'elenco completo dei ruoli e delle relative autorizzazioni.

• Se lavori dalla tua macchina locale, configura l'accesso da riga di comando inizializzando Google Cloud CLI.

• Fornisci la richiesta con le credenziali di autenticazione in formato di token ID generato da Google memorizzato in un'intestazione Authorization. Ad esempio, recupera un token ID tramite gcloud eseguendo questo comando:

  curl  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
    https://FUNCTION_URL

  dove FUNCTION_URL è l'URL della funzione. Puoi recuperare questo URL dalla pagina Cloud Run Functions della consoleGoogle Cloud o eseguendo il comando gcloud functions describe come mostrato nel primo passaggio dell'esempio di comando deployment di Google Cloud CLI.

Puoi utilizzare i token creati da gcloud per richiamare le funzioni HTTP in qualsiasi progetto, a condizione che il tuo account disponga dell'autorizzazione cloudfunctions.functions.invoke per la funzione richiamata. In ambiente di sviluppo, utilizza token ID generati da gcloud. Tieni però presente che questi token non includono un'attestazione del pubblico, cosa che li rende vulnerabili agli attacchi di tipo relay. In ambiente di produzione, utilizza i token ID emessi per un service account con il pubblico appropriato specificato. Questo approccio rafforza la sicurezza limitando l'utilizzo dei token solo al servizio previsto.

Come sempre, ti consigliamo di allocare il set di autorizzazioni minimo necessario per sviluppare e utilizzare le tue funzioni. Assicurati che le policy IAM sulle tue funzioni siano limitate al numero minimo di utenti e service account.

Esempio 2: autenticazione delle chiamate da funzione a funzione

Se crei servizi che connettono più funzioni, assicurati che ogni funzione possa inviare richieste solo a un sottoinsieme specifico delle altre funzioni. Ad esempio, una funzione login dovrebbe essere in grado di accedere alla funzione user profiles, ma probabilmente non dovrebbe essere in grado di accedere alla funzione search.

Per configurare la funzione ricevente in modo che accetti richieste da una funzione chiamante specifica, devi concedere il ruolo di invoker appropriato al service account della funzione chiamante sulla funzione ricevente. Il ruolo specifico è Cloud Run functions Invoker (roles/cloudfunctions.invoker):

Console

Utilizza il ruolo Cloud Run functions Invoker:

1. Vai alla console Google Cloud :

   Vai alla console Google Cloud

2. Fai clic sulla casella di controllo accanto alla funzione ricevente. Non fare clic sulla funzione stessa.

3. Fai clic su Autorizzazioni nella parte superiore della schermata. Si apre il riquadro Autorizzazioni.

4. Fai clic su Aggiungi entità.

5. Nel campo Nuove entità, inserisci l'identità della funzione chiamante. Deve essere un indirizzo email di un service account.

6. Seleziona il ruolo Cloud Functions > Cloud Functions Invoker dal menu a discesa Seleziona un ruolo.

7. Fai clic su Salva.

gcloud

Utilizza il comando gcloud functions add-invoker-policy-binding:

gcloud functions add-invoker-policy-binding RECEIVING_FUNCTION \
  --member='serviceAccount:CALLING_FUNCTION_IDENTITY'

Il comando add-invoker-policy-binding aggiunge un'associazione di policy IAM del ruolo invoker che consente al membro (entità) specificato di richiamare la funzione specificata. Google Cloud CLI rileva automaticamente la generazione della funzione e aggiunge il ruolo Invoker corretto (cloudfunctions.invoker per la 1ª gen.).

Sostituisci quanto segue:

• RECEIVING_FUNCTION: il nome della funzione ricevente.
• CALLING_FUNCTION_IDENTITY: l'identità della funzione chiamante, ossia l'indirizzo email di un service account.

Poiché richiamerà la funzione ricevente, la funzione chiamante deve fornire anche un token ID firmato da Google per l'autenticazione. È un processo in due fasi:

1. Crea un token ID firmato da Google con il campo per il pubblico (aud) impostato sull'URL della funzione ricevente.

2. Includi il token ID in un'intestazione Authorization: Bearer ID_TOKEN nella richiesta alla funzione.

Il modo di gran lunga più semplice e affidabile per gestire questo processo è utilizzare le librerie di autenticazione, come mostrato di seguito, per generare e utilizzare questo token.

Genera token ID

Questa sezione descrive i diversi modi in cui puoi generare il token ID di cui un'entità ha bisogno per richiamare una funzione.

L'accesso non autenticato senza un token ID è possibile, ma deve essere abilitato. Per saperne di più, consulta Utilizzo di IAM per autorizzare l'accesso.

Nota: i token ID contengono anche informazioni sull'identità che rappresentano. Per accedere a queste informazioni, puoi utilizzare librerie ampiamente disponibili.

Genera token in modo programmatico

Dopo che il codice riportato di seguito genera un token ID, chiama la tua funzione Cloud Run con quel token per tuo conto. Questo codice funziona in qualsiasi ambiente in cui le librerie possono ottenere le credenziali di autenticazione, inclusi gli ambienti che supportano le credenziali predefinite dell'applicazione locali.

Node.js

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */

// Cloud Functions uses your function's url as the `targetAudience` value
// const targetAudience = 'https://project-region-projectid.cloudfunctions.net/myFunction';
// For Cloud Functions, endpoint (`url`) and `targetAudience` should be equal
// const url = targetAudience;


const {GoogleAuth} = require('google-auth-library');
const auth = new GoogleAuth();

async function request() {
  console.info(`request ${url} with target audience ${targetAudience}`);
  const client = await auth.getIdTokenClient(targetAudience);

  // Alternatively, one can use `client.idTokenProvider.fetchIdToken`
  // to return the ID Token.
  const res = await client.fetch(url);
  console.info(res.data);
}

request().catch(err => {
  console.error(err.message);
  process.exitCode = 1;
});

Python

import urllib

import google.auth.transport.requests
import google.oauth2.id_token


def make_authorized_get_request(endpoint, audience):
    """
    make_authorized_get_request makes a GET request to the specified HTTP endpoint
    by authenticating with the ID token obtained from the google-auth client library
    using the specified audience value.
    """

    # Cloud Functions uses your function's URL as the `audience` value
    # audience = https://project-region-projectid.cloudfunctions.net/myFunction
    # For Cloud Functions, `endpoint` and `audience` should be equal

    req = urllib.request.Request(endpoint)

    auth_req = google.auth.transport.requests.Request()
    id_token = google.oauth2.id_token.fetch_id_token(auth_req, audience)

    req.add_header("Authorization", f"Bearer {id_token}")
    response = urllib.request.urlopen(req)

    return response.read()

Go

import (
	"context"
	"fmt"
	"io"

	"google.golang.org/api/idtoken"
)

// `makeGetRequest` makes a request to the provided `targetURL`
// with an authenticated client using audience `audience`.
func makeGetRequest(w io.Writer, targetURL string, audience string) error {
	// For Cloud Functions, endpoint (`serviceUrl`) and `audience` are the same.
	// Example `audience` value (Cloud Functions): https://<PROJECT>-<REGION>-<PROJECT_ID>.cloudfunctions.net/myFunction
	// (`targetURL` and `audience` will differ for GET parameters)
	ctx := context.Background()

	// client is a http.Client that automatically adds an "Authorization" header
	// to any requests made.
	client, err := idtoken.NewClient(ctx, audience)
	if err != nil {
		return fmt.Errorf("idtoken.NewClient: %w", err)
	}

	resp, err := client.Get(targetURL)
	if err != nil {
		return fmt.Errorf("client.Get: %w", err)
	}
	defer resp.Body.Close()
	if _, err := io.Copy(w, resp.Body); err != nil {
		return fmt.Errorf("io.Copy: %w", err)
	}

	return nil
}

Java

import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpResponse;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.auth.oauth2.IdTokenCredentials;
import com.google.auth.oauth2.IdTokenProvider;
import java.io.IOException;

public class Authentication {

  // makeGetRequest makes a GET request to the specified Cloud Run or
  // Cloud Functions endpoint `serviceUrl` (must be a complete URL), by
  // authenticating with an ID token retrieved from Application Default
  // Credentials using the specified `audience`.
  //
  // For Cloud Functions, endpoint (`serviceUrl`) and `audience` are the same.
  // Example `audience` value (Cloud Functions): https://project-region-projectid.cloudfunctions.net/myFunction
  public static HttpResponse makeGetRequest(String serviceUrl, String audience) throws IOException {
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
    if (!(credentials instanceof IdTokenProvider)) {
      throw new IllegalArgumentException("Credentials are not an instance of IdTokenProvider.");
    }
    IdTokenCredentials tokenCredential =
        IdTokenCredentials.newBuilder()
            .setIdTokenProvider((IdTokenProvider) credentials)
            .setTargetAudience(audience)
            .build();

    GenericUrl genericUrl = new GenericUrl(serviceUrl);
    HttpCredentialsAdapter adapter = new HttpCredentialsAdapter(tokenCredential);
    HttpTransport transport = new NetHttpTransport();
    HttpRequest request = transport.createRequestFactory(adapter).buildGetRequest(genericUrl);
    return request.execute();
  }
}

Genera token manualmente

Se devi richiamare una funzione ma per qualche motivo non puoi utilizzare le librerie di autenticazione, esistono due modi per ottenere manualmente il token ID: utilizzando il server dei metadati Compute o creando un JWT autofirmato e scambiandolo con un token ID firmato da Google.

Nota: per conoscere altri modi per ottenere questo token, consulta Metodi per ottenere un token ID.

Utilizza il server di metadati

Puoi utilizzare il server dei metadati Compute per recuperare i token ID con un pubblico specifico come segue:

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=AUDIENCE" \
     -H "Metadata-Flavor: Google"

Sostituisci AUDIENCE con l'URL della funzione che stai richiamando. Puoi recuperare questo URL come descritto nella sezione Autenticazione dei test degli sviluppatori riportata sopra.

Nota: questo metodo non funziona da una macchina locale.

Scambia un JWT autofirmato con un token ID firmato da Google

1. Concedi il ruolo Invoker (roles/cloudfunctions.invoker) al service account della funzione chiamante sulla funzione ricevente.

2. Crea un service account e una chiave e scarica il file con la chiave privata (in formato JSON) sull'host da cui la funzione o il servizio chiamante effettua le richieste.

3. Crea un JWT con l'intestazione impostata su {"alg":"RS256","typ":"JWT"}. Il payload deve includere un'attestazione target_audience impostata sull'URL della funzione ricevente e le attestazioni iss e sub impostate sull'indirizzo email del service account utilizzato sopra. Deve includere anche le attestazioni exp e iat. L'attestazione aud deve essere impostata su https://www.googleapis.com/oauth2/v4/token.

4. Utilizza la chiave privata scaricata in precedenza per firmare il JWT.

5. Utilizzando questo JWT, invia una richiesta POST a https://www.googleapis.com/oauth2/v4/token. I dati di autenticazione devono essere inclusi nell'intestazione e nel corpo della richiesta.

   Nell'intestazione:

   Authorization: Bearer $JWT - where $JWT is the JWT you just created
   Content-Type: application/x-www-form-urlencoded
   

   Nel corpo:

   grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=$JWT
   

   Sostituisci $JWT con il JWT appena creato.

   Viene restituito un altro JWT che include un id_token firmato da Google.

Invia la richiesta GET/POST alla funzione ricevente. Includi il token ID firmato da Google in un'intestazione Authorization: Bearer ID_TOKEN_JWT nella richiesta.

Nota: un token ID firmato da Google scade un'ora dopo la richiesta che lo genera inizialmente.

Passaggi successivi

• Scopri come gestire l'accesso alle funzioni.

• Ricevi assistenza in merito ad altri modi per generare token ID.