Scopri come richiamare le funzioni Cloud Functions autenticate

1. Introduzione

Panoramica

Cloud Functions è una soluzione di calcolo leggera che consente agli sviluppatori di creare funzioni autonome a uso specifico che possono essere attivate utilizzando HTTPS o rispondere a CloudEvents senza la necessità di gestire un server o un ambiente di runtime.

Esistono due approcci principali per controllare le chiamate a Cloud Functions: proteggere l'accesso in base all'identità e proteggere l'accesso utilizzando i controlli dell'accesso basati sulla rete. Questo codelab si concentra sul primo approccio e ti guida attraverso tre scenari per proteggere l'accesso in base all'identità per richiamare una funzione:

1. Utilizza il token di identità gcloud per richiamare una funzione a scopo di sviluppo e test locali
2. Simulare l'identità di un service account durante lo sviluppo e il test in locale per utilizzare le stesse credenziali della produzione
3. Utilizza le librerie client di Google per gestire l'autenticazione alle API Google Cloud, ad esempio quando un servizio deve richiamare una funzione

Cosa imparerai a fare

• Come configurare l'autenticazione su una funzione Cloud Functions e verificare che sia stata configurata correttamente
• Richiamare una funzione autenticata da un ambiente di sviluppo locale fornendo il token per la tua identità gcloud
• Come creare un service account e concedergli il ruolo appropriato per richiamare una funzione
• Come simulare l'identità di un servizio da un ambiente di sviluppo locale che dispone dei ruoli appropriati per richiamare una funzione

2. Configurazione e requisiti

Prerequisiti

• Hai eseguito l'accesso a Cloud Console
• Hai già eseguito il deployment di una funzione Cloud Functions di 2ª gen. attivata da HTTP
• (Facoltativo) Per il terzo scenario, questo codelab utilizza Node.js e npm come esempio, ma puoi utilizzare qualsiasi runtime supportato dalle librerie client Google Auth.

Attiva Cloud Shell

1. Nella console Cloud, fai clic su Attiva Cloud Shell .

Se è la prima volta che avvii Cloud Shell, viene visualizzata una schermata intermedia che ne descrive le funzionalità. Se è stata visualizzata una schermata intermedia, fai clic su Continua.

Bastano pochi istanti per eseguire il provisioning e connettersi a Cloud Shell.

Questa macchina virtuale è caricata con tutti gli strumenti di sviluppo necessari. Offre una home directory permanente da 5 GB e viene eseguita in Google Cloud, migliorando notevolmente le prestazioni e l'autenticazione della rete. Gran parte del lavoro per questo codelab, se non tutto, può essere svolto con un browser.

Una volta eseguita la connessione a Cloud Shell, dovresti vedere che il tuo account è autenticato e il progetto è impostato sul tuo ID progetto.

2. Esegui questo comando in Cloud Shell per verificare che l'account sia autenticato:

gcloud auth list

Output comando

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Nota:lo strumento a riga di comando gcloud è il potente strumento a riga di comando unificato di Google Cloud. È già installato in Cloud Shell. Noterai il supporto del completamento automatico. Per saperne di più, consulta la panoramica dello strumento a riga di comando gcloud.

3. Esegui questo comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto:

gcloud config list project

Output comando

[core]
project = <PROJECT_ID>

In caso contrario, puoi impostarlo con questo comando:

gcloud config set project <PROJECT_ID>

Output comando

Updated property [core/project].

Nota:se completi questo tutorial al di fuori di Cloud Shell, segui la procedura per configurare le credenziali predefinite dell'applicazione.

3. Crea e testa una funzione Cloud Functions autenticata

Questo codelab segue le stesse istruzioni della guida rapida della console per Cloud Functions con una notevole eccezione: la tua funzione richiederà l'autenticazione.

Se l'autenticazione è obbligatoria, l'entità che richiama la funzione deve disporre dei ruoli Invoker di Cloud Functions (e Invoker di Cloud Run per la 2ª gen.); in caso contrario, la funzione restituirà un errore 403 - Vietato. Questo codelab mostrerà come concedere i ruoli Invoker appropriati a un principal.

Crea la funzione autenticata

Ecco i passaggi per utilizzare la console Cloud:

1. Vai alla pagina Panoramica di Cloud Functions e fai clic su Crea funzione.
2. Nell'opzione Ambiente, seleziona 2ª gen..
3. Assegna alla funzione il nome my-authenticated-function
4. Nel campo Autenticazione, lascia il valore predefinito Richiedi autenticazione.

5. Fai clic su Avanti.
6. Per questo codelab, puoi scegliere qualsiasi lingua
7. Quindi premi Esegui il deployment.

Il deployment della funzione richiede circa un minuto.

Configura le variabili di ambiente locali per semplificare i comandi gcloud

Innanzitutto, crea alcune variabili di ambiente per migliorare la leggibilità dei comandi gcloud utilizzati in questo codelab.

Dovrai specificare la regione per la tua funzione. Questo esempio utilizza us-central1.

REGION="us-central1"

e poi puoi salvare l'URL della funzione come variabile di ambiente da utilizzare in un secondo momento.

PROJECT_ID=$(gcloud config get-value project)
FUNCTION_URL="$(gcloud functions describe my-authenticated-function --gen2 --region us-central1 --format='get(serviceConfig.uri)')"

Verifica che la funzione richieda l'autenticazione tentando di richiamarla come chiamante anonimo

Richiamerai la funzione senza autenticazione per verificare di ricevere l'errore 403 previsto.

Da una riga di comando, esegui questo comando curl:

curl $FUNCTION_URL

Verrà visualizzato il seguente risultato:

<html><head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>403 Forbidden</title>
</head>
<body text=#000000 bgcolor=#ffffff>
<h1>Error: Forbidden</h1>
<h2>Your client does not have permission to get URL <code>/</code> from this server.</h2>
<h2></h2>
</body></html>

Ora puoi esaminare tre scenari in cui puoi richiamare la funzione fornendo l'autenticazione.

4. Scenario 1: utilizza il token di identità gcloud

Come sviluppatore, vorrai un modo per testare la tua funzione mentre la sviluppi localmente. In questa sezione, eseguirai un rapido test per verificare che la funzione sia autenticata correttamente utilizzando la tua identità.

Verifica di essere autenticato utilizzando gcloud eseguendo questo comando:

gcloud auth list

Dovresti vedere un asterisco accanto alla tua identità attiva, ad esempio:

Credentialed Accounts
ACTIVE  ACCOUNT

*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Una volta verificato di utilizzare l'identità corretta, salverai l'email dell'account in una variabile di ambiente.

ACCOUNT_EMAIL=$(gcloud auth list --filter=status:ACTIVE --format="value(account)")

Puoi trovare maggiori informazioni su come configurare gcloud init e gcloud auth login nella documentazione.

Successivamente, richiama la funzione e trasmetti il token di identità.

curl $FUNCTION_URL -H "Authorization: bearer $(gcloud auth print-identity-token)"

Ora vedrai il risultato:

Hello World!

Risoluzione dei problemi

Se ricevi un errore 403 Forbidden, assicurati che la tua identità disponga del ruolo Invoker di Cloud Functions o del ruolo Invoker di Cloud Run per le funzioni di 2ª gen. Puoi utilizzare la console IAM per verificare i ruoli assegnati a un'entità.

Sebbene l'utilizzo del tuo token di identità sia un modo rapido per testare la funzione durante lo sviluppo, il chiamante della funzione autenticata avrà bisogno dei ruoli appropriati; in caso contrario, riceverà un errore 403 Forbidden.

Ti consigliamo di seguire il principio del privilegio minimo limitando il numero di identità e service account che dispongono di ruoli per richiamare la funzione.

creando un nuovo service account e concedendogli i ruoli necessari,

5. Scenario 2: rappresentare un service account

In questo scenario, simulerai l'identità (ovvero assumerai le autorizzazioni di) un service account per richiamare una funzione durante lo sviluppo e il test in locale. Se impersoni un service account, puoi testare la funzione con le stesse credenziali della produzione.

In questo modo, non solo verificherai i ruoli, ma seguirai anche il principio del privilegio minimo non dovendo concedere il ruolo Invoker di Cloud Functions ad altre identità solo a scopo di test locale.

Ai fini di questo codelab, creerai un nuovo service account che dispone solo dei ruoli per richiamare la funzione che hai creato in questo codelab.

Crea un nuovo service account

Innanzitutto, creerai un paio di variabili di ambiente aggiuntive per rappresentare i service account utilizzati nei comandi gcloud.

SERVICE_ACCOUNT_NAME="invoke-functions-codelab"
SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com

A questo punto, crea il service account.

gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME \
  --display-name="Cloud Function Authentication codelab"

e concedi al service account il ruolo Invoker di Cloud Functions.

gcloud functions add-iam-policy-binding my-authenticated-function \
  --region=us-central1 --gen2 \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role='roles/cloudfunctions.invoker'

Ti verrà chiesto se concedere al service account un ruolo aggiuntivo per Cloud Run Invoker. Premi "y" o Invio per aggiungere il ruolo Cloud Run Invoker.

Richiamare la funzione rappresentando il service account

Per farlo, simulerai l'identità del service account appena creato ottenendo il relativo token ID.

Aggiungi i ruoli richiesti per la simulazione dell'identità

Per rappresentare un service account, il tuo account utente deve disporre del ruolo Creatore token service account (roles/iam.serviceAccountTokenCreator) per generare un token ID per il service account.

gcloud iam service-accounts add-iam-policy-binding $SERVICE_ACCOUNT_ADDRESS  \
  --member user:$ACCOUNT_EMAIL \
  --role='roles/iam.serviceAccountTokenCreator'

Utilizzare il token ID del service account

Ora puoi richiamare la funzione passando il token ID del service account.

curl $FUNCTION_URL -H "Authorization: bearer $(gcloud auth print-identity-token --impersonate-service-account $SERVICE_ACCOUNT_ADDRESS)" 

Verrà visualizzato quanto segue:

WARNING: This command is using service account impersonation. All API calls will be executed as [invoke-functions-codelab@<project-id>.iam.gserviceaccount.com].
Hello World!

6. Scenario 3: utilizza le librerie client Google

Per quest'ultima parte del codelab, eseguirai un piccolo servizio in locale per generare un token ID per un service account e poi chiamerai la funzione in modo programmatico utilizzando le librerie client Google Auth e le credenziali predefinite dell'applicazione (ADC). Puoi scoprire di più sulle librerie client di Google nella sezione dedicata della documentazione.

L'utilizzo di ADC è particolarmente importante quando vuoi scrivere e testare la tua funzione localmente (ad es. sul laptop, in Cloud Shell e così via) mentre interagisci con altre risorse Google Cloud (ad es. Cloud Storage, API Vision e così via). In questo esempio, vedrai come un servizio richiama un'altra funzione che richiede l'autenticazione. Per ulteriori informazioni su ADC e sviluppo locale, consulta il post del blog How to develop and test your Cloud Functions locally | Google Cloud Blog.

Esegui il comando gcloud per rappresentare un service account

ADC trova automaticamente le credenziali in base all'ambiente dell'applicazione e le utilizza per l'autenticazione alle API Cloud di Google. Il flag –impersonate-service-account consente di simulare l'identità di un service account utilizzando la sua identità per l'autenticazione rispetto alle API Cloud.

Per simulare l'identità di un service account, puoi eseguire questo comando:

gcloud auth application-default login --impersonate-service-account=$SERVICE_ACCOUNT_ADDRESS

Ora esegui i comandi gcloud come service account, anziché con la tua identità.

Crea ed esegui un servizio per richiamare una funzione autenticata

Ogni runtime ha la propria libreria client Google Auth che puoi installare. Questo codelab ti guida nella creazione e nell'esecuzione di un'app Node.js in locale.

Ecco i passaggi per Node.js:

1. Crea una nuova app Node.js

npm init

2. Installa la libreria client Google Auth

npm install google-auth-library

3. Creare un file index.js
4. Recupera l'URL della tua funzione Cloud Functions, che aggiungerai al codice nel passaggio successivo.

echo $FUNCTION_URL

5. Aggiungi il seguente codice a index.js. Assicurati di modificare la variabile targetAudience con l'URL della tua funzione Cloud Functions.

index.js

// Cloud Functions uses your function's url as the `targetAudience` value

const targetAudience = '<YOUR-CLOUD-FUNCTION-URL>';

// 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}`);

    // this call retrieves the ID token for the impersonated service account
    const client = await auth.getIdTokenClient(targetAudience);

    const res = await client.request({ url });
    console.info(res.data);
}

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

6. Esegui l'app

node index.js

e dovresti vedere il risultato "Hello World!".

Risoluzione dei problemi

Se visualizzi l'errore Autorizzazione "iam.serviceAccounts.getOpenIdToken" negata per la risorsa (o potrebbe non esistere), attendi alcuni minuti affinché il ruolo Creatore token service account venga propagato.

Se hai ricevuto l'errore Impossibile recuperare il token ID in questo ambiente, utilizza GCE o imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS su un file JSON delle credenziali dell'account di servizio. Potresti aver dimenticato di eseguire il comando

gcloud auth application-default login --impersonate-service-account=$SERVICE_ACCOUNT_ADDRESS

7. Complimenti!

Congratulazioni per aver completato il codelab.

Ti consigliamo di consultare la documentazione su come proteggere Cloud Functions.

Ti consigliamo anche questo post del blog sullo sviluppo locale con Cloud Functions per scoprire come sviluppare e testare la tua funzione Cloud Functions nel tuo ambiente di sviluppo locale.

Argomenti trattati

• Come configurare l'autenticazione su una funzione Cloud Functions e verificare che sia stata configurata correttamente
• Richiamare una funzione autenticata da un ambiente di sviluppo locale fornendo il token per la tua identità gcloud
• Come creare un service account e concedergli il ruolo appropriato per richiamare una funzione
• Come simulare l'identità di un servizio da un ambiente di sviluppo locale che dispone dei ruoli appropriati per richiamare una funzione

8. Esegui la pulizia

Per evitare addebiti involontari (ad esempio, questa funzione Cloud Functions viene richiamata inavvertitamente più volte rispetto all'allocazione mensile di chiamate di Cloud Functions nel livello senza costi), puoi eliminare la funzione Cloud Functions o il progetto che hai creato nel passaggio 2.

Per interrompere la simulazione dell'identità dell'account di servizio, puoi accedere di nuovo utilizzando la tua identità:

gcloud auth application-default login

Per eliminare la funzione Cloud, vai alla console Cloud di Cloud Functions all'indirizzo https://console.cloud.google.com/functions/. Assicurati che il progetto che hai creato nel passaggio 2 sia il progetto attualmente selezionato.

Seleziona my-authenticated-function di cui hai eseguito il deployment in precedenza. Quindi, premi Elimina.

Se scegli di eliminare l'intero progetto, puoi andare alla pagina https://console.cloud.google.com/cloud-resource-manager, selezionare il progetto che hai creato nel passaggio 2 e scegliere Elimina. Se elimini il progetto, dovrai cambiare progetto in Cloud SDK. Puoi visualizzare l'elenco di tutti i progetti disponibili eseguendo gcloud projects list.