Autenticazione degli utenti con Go

Le app in esecuzione su piattaforme gestite di Google Cloud, come App Engine, possono evitare di gestire l'autenticazione utente e la gestione delle sessioni utilizzando Identity-Aware Proxy (IAP) per controllarne l'accesso. L'IAP non solo può controllare l'accesso all'app, ma fornisce anche informazioni sugli utenti autenticati, tra cui l'indirizzo email e un identificatore persistente per l'app sotto forma di nuove intestazioni HTTP.

Obiettivi

  • Richiedi agli utenti della tua app App Engine di autenticarsi utilizzando IAP.

  • Accedi alle identità degli utenti nell'app per visualizzare l'indirizzo email autenticato dell'utente corrente.

Costi

In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud potrebbero essere idonei per una prova gratuita.

Al termine delle attività descritte in questo documento, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per ulteriori informazioni, consulta la sezione Pulizia.

Prima di iniziare

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Install the Google Cloud CLI.

  4. To initialize the gcloud CLI, run the following command: 

    gcloud init

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Install the Google Cloud CLI.

  7. To initialize the gcloud CLI, run the following command: 

    gcloud init
  8. Prepara l'ambiente di sviluppo.

Configurazione del progetto

  1. Nella finestra del terminale, clona il repository dell'app di esempio sulla tua macchina locale:

    git clone https://github.com/GoogleCloudPlatform/golang-samples.git

  2. Passa alla directory che contiene il codice di esempio:

    cd golang-samples/getting-started/authenticating-users

Sfondo

Questo tutorial utilizza IAP per autenticare gli utenti. Questo è solo uno dei diversi approcci possibili. Per scoprire di più sui vari metodi di autenticazione degli utenti, consulta la sezione Concetti di autenticazione.

L'app Hello user-email-address

L'app per questo tutorial è un'app App Engine Hello World minima, con una funzionalità non tipica: anziché "Hello World", viene visualizzato "Un saluto da user-email-address", dove user-email-address è l'indirizzo email dell'utente autenticato.

Questa funzionalità è possibile esaminando le informazioni autenticate che IAP aggiunge a ogni richiesta web che passa alla tua app. A ogni richiesta web che raggiunge la tua app vengono aggiunte tre nuove intestazioni di richiesta. Le prime due intestazioni sono stringhe di testo normale che puoi utilizzare per identificare l'utente. La terza intestazione è un oggetto firmato in modo crittografico con le stesse informazioni.

  • X-Goog-Authenticated-User-Email: l'indirizzo email di un utente lo identifica. Non memorizzare informazioni personali se la tua app può evitarlo. Questa app non immagazzina dati, ma li restituisce all'utente.

  • X-Goog-Authenticated-User-Id: questo ID utente assegnato da Google non mostra informazioni sull'utente, ma consente a un'app di sapere che un utente che ha eseguito l'accesso è lo stesso che è stato visto in precedenza.

  • X-Goog-Iap-Jwt-Assertion: puoi configurare le app Google Cloud per accettare richieste web da altre app cloud, bypassando IAP, oltre alle richieste web di internet. Se un'app è così configurata, è possibile che queste richieste abbiano intestazioni contraffatte. Anziché utilizzare una delle intestazioni in testo normale menzionate in precedenza, puoi utilizzare e verificare questa intestazione firmata criptograficamente per verificare che le informazioni siano state fornite da Google. Nell'ambito di questo intestazione firmata sono disponibili sia l'indirizzo email dell'utente sia un ID utente permanente.

Se hai la certezza che l'app sia configurata in modo che solo le richieste web di internet possano raggiungerla e che nessuno possa disattivare il servizio IAP per l'app, il recupero di un ID utente univoco richiede solo una riga di codice:

userID := r.Header.Get("X-Goog-Authenticated-User-ID")

Tuttavia, un'app resiliente deve aspettarsi che qualcosa vada storto, inclusi problemi di configurazione o ambientali imprevisti, pertanto consigliamo di creare una funzione che utilizzi e verifichi l'intestazione firmata con crittografia. La firma dell'intestazione non può essere contraffatta e, una volta verificata, può essere utilizzata per recuperare l'identificazione.

Nozioni di base sul codice

Questa sezione spiega come funziona il codice. Se vuoi eseguire l'app, puoi saltare alla sezione Eseguire il deployment dell'app.

  • Il file go.mod definisce un modulo Go e i moduli di cui dipende.

    module github.com/GoogleCloudPlatform/golang-samples/getting-started/authenticating-users

go 1.21

require (
	cloud.google.com/go/compute/metadata v0.5.0
	github.com/golang-jwt/jwt v3.2.2+incompatible
)

require golang.org/x/sys v0.22.0 // indirect

  • Il file app.yaml indica ad App Engine l'ambiente di linguaggio richiesto dal codice.

    runtime: go112

  • L'app inizia importando i pacchetti e definendo una funzione main. La funzione main registra un gestore dell'indice e avvia un server HTTP.

    
// The authenticating-users program is a sample web server application that
// extracts and verifies user identity data passed to it via Identity-Aware
// Proxy.
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"time"

	"cloud.google.com/go/compute/metadata"
	"github.com/golang-jwt/jwt"
)

// app holds the Cloud IAP certificates and audience field for this app, which
// are needed to verify authentication headers set by Cloud IAP.
type app struct {
	certs map[string]string
	aud   string
}

func main() {
	a, err := newApp()
	if err != nil {
		log.Fatal(err)
	}

	http.HandleFunc("/", a.index)

	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
		log.Printf("Defaulting to port %s", port)
	}

	log.Printf("Listening on port %s", port)
	if err := http.ListenAndServe(":"+port, nil); err != nil {
		log.Fatal(err)
	}
}

// newApp creates a new app, returning an error if either the Cloud IAP
// certificates or the app's audience field cannot be obtained.
func newApp() (*app, error) {
	certs, err := certificates()
	if err != nil {
		return nil, err
	}

	aud, err := audience()
	if err != nil {
		return nil, err
	}

	a := &app{
		certs: certs,
		aud:   aud,
	}
	return a, nil
}

  • La funzione index recupera il valore dell'intestazione dell'affermazione JWT che IAP ha aggiunto dalla richiesta in arrivo e chiama la funzione validateAssertion per convalidare il valore firmato con crittografia. L'indirizzo email viene poi utilizzato in una risposta web minima.

    
// index responds to requests with our greeting.
func (a *app) index(w http.ResponseWriter, r *http.Request) {
	if r.URL.Path != "/" {
		http.NotFound(w, r)
		return
	}

	assertion := r.Header.Get("X-Goog-IAP-JWT-Assertion")
	if assertion == "" {
		fmt.Fprintln(w, "No Cloud IAP header found.")
		return
	}
	email, _, err := validateAssertion(assertion, a.certs, a.aud)
	if err != nil {
		log.Println(err)
		fmt.Fprintln(w, "Could not validate assertion. Check app logs.")
		return
	}

	fmt.Fprintf(w, "Hello %s\n", email)
}

  • La funzione validateAssertion convalida la firma corretta dell'affermazione e restituisce l'indirizzo email e l'ID utente associati.

    La convalida di un'affermazione JWT richiede la conoscenza dei certificati delle chiavi pubbliche della persona giuridica che ha firmato l'affermazione (in questo caso Google) e del pubblico a cui è destinata l'affermazione. Per un'app App Engine, il segmento di pubblico è una stringa contenente informazioni di identificazione del progetto Google Cloud. La funzione validateAssertion recupera questi certificati dalla funzione certs e la stringa del segmento di pubblico dalla funzione audience.

    
// validateAssertion validates assertion was signed by Google and returns the
// associated email and userID.
func validateAssertion(assertion string, certs map[string]string, aud string) (email string, userID string, err error) {
	token, err := jwt.Parse(assertion, func(token *jwt.Token) (interface{}, error) {
		keyID := token.Header["kid"].(string)

		_, ok := token.Method.(*jwt.SigningMethodECDSA)
		if !ok {
			return nil, fmt.Errorf("unexpected signing method: %q", token.Header["alg"])
		}

		cert := certs[keyID]
		return jwt.ParseECPublicKeyFromPEM([]byte(cert))
	})

	if err != nil {
		return "", "", err
	}

	claims, ok := token.Claims.(jwt.MapClaims)
	if !ok {
		return "", "", fmt.Errorf("could not extract claims (%T): %+v", token.Claims, token.Claims)
	}

	if claims["aud"].(string) != aud {
		return "", "", fmt.Errorf("mismatched audience. aud field %q does not match %q", claims["aud"], aud)
	}
	return claims["email"].(string), claims["sub"].(string), nil
}

  • Puoi cercare l'ID numerico e il nome del progetto Google Cloud e inserirli personalmente nel codice sorgente, ma la funzione audience lo fa per te eseguendo una query sul servizio di metadati standard reso disponibile a ogni app App Engine. Poiché il servizio di metadati è esterno al codice dell'app, il risultato viene salvato in una variabile globale restituita senza dover cercare i metadati nelle chiamate successive.

    Il servizio di metadati di App Engine (e servizi di metadati simili per altri servizi di cloud computing di Google) ha l'aspetto di un sito web e viene sottoposto a query tramite query web standard. Tuttavia, il servizio di metadati non è un sito esterno, ma una funzionalità interna che restituisce le informazioni richieste sull'app in esecuzione, pertanto è possibile utilizzare le richieste http anziché https in tutta sicurezza. Il servizio di metadati viene utilizzato per recuperare gli attuali identificatori di Google Cloud necessari per definire il pubblico di destinazione dell'affermazione JWT.

    
// audience returns the expected audience value for this service.
func audience() (string, error) {
	projectNumber, err := metadata.NumericProjectID()
	if err != nil {
		return "", fmt.Errorf("metadata.NumericProjectID: %w", err)
	}

	projectID, err := metadata.ProjectID()
	if err != nil {
		return "", fmt.Errorf("metadata.ProjectID: %w", err)
	}

	return "/projects/" + projectNumber + "/apps/" + projectID, nil
}

  • La verifica di una firma digitale richiede il certificato di chiave pubblica del firmatario. Google fornisce un sito web che restituisce tutti i certificati delle chiavi pubbliche attualmente in uso. Questi risultati vengono memorizzati nella cache nel caso in cui siano di nuovo necessari nella stessa istanza dell'app.

    
// certificates returns Cloud IAP's cryptographic public keys.
func certificates() (map[string]string, error) {
	const url = "https://www.gstatic.com/iap/verify/public_key"
	client := http.Client{
		Timeout: 5 * time.Second,
	}
	resp, err := client.Get(url)
	if err != nil {
		return nil, fmt.Errorf("Get: %w", err)
	}

	var certs map[string]string
	dec := json.NewDecoder(resp.Body)
	if err := dec.Decode(&certs); err != nil {
		return nil, fmt.Errorf("Decode: %w", err)
	}

	return certs, nil
}

Esegui il deployment dell'app

Ora puoi implementare l'app e attivare l'IAP per richiedere agli utenti di autenticarsi prima di poter accedere all'app.

  1. Nella finestra del terminale, vai alla directory contenente il file app.yaml esegui il deployment dell'app in App Engine:

    gcloud app deploy

  2. Quando richiesto, seleziona una regione nelle vicinanze.

  3. Quando ti viene chiesto se vuoi continuare con l'operazione di deployment, inserisci Y.

    Entro pochi minuti, la tua app sarà disponibile su internet.

  4. Visualizza l'app:

    gcloud app browse

    Nell'output, copia web-site-url, l'indirizzo web per l'app.

  5. In una finestra del browser, incolla web-site-url per aprire l'app.

    Non viene visualizzata alcuna email perché non utilizzi ancora IAP, pertanto non vengono inviati all'app informazioni sull'utente.

Attivare IAP

Ora che esiste un'istanza App Engine, puoi proteggerla con IAP:

  1. Nella console Google Cloud, vai alla pagina Identity-Aware Proxy.

    Vai alla pagina di Identity-Aware Proxy

  2. Poiché è la prima volta che attivi un'opzione di autenticazione per questo progetto, viene visualizzato un messaggio che ti informa che devi configurare la schermata per il consenso OAuth prima di poter utilizzare l'IAP.

    Fai clic su Configura schermata di consenso.

  3. Nella scheda Schermata per il consenso OAuth della pagina Credenziali, compila i seguenti campi:

    • Se il tuo account si trova in un'organizzazione Google Workspace, seleziona Esterno e fai clic su Crea. Per iniziare, l'app sarà disponibile solo per gli utenti che autorizzi esplicitamente.

    • Nel campo Nome applicazione, inserisci IAP Example.

    • Nel campo Email per l'assistenza, inserisci il tuo indirizzo email.

    • Nel campo Dominio autorizzato, inserisci la parte del nome host dell'URL dell'app, ad esempio iap-example-999999.uc.r.appspot.com. Premi il tasto Enter dopo aver inserito il nome host nel campo.

    • Nel campo Link alla home page dell'applicazione, inserisci l'URL della tua app, ad esempio https://iap-example-999999.uc.r.appspot.com/.

    • Nel campo Riga delle norme sulla privacy dell'applicazione, utilizza lo stesso URL del link alla home page a scopo di test.

  4. Fai clic su Salva. Quando ti viene chiesto di creare le credenziali, puoi chiudere la finestra.

  5. Nella console Google Cloud, vai alla pagina Identity-Aware Proxy.

    Vai alla pagina di Identity-Aware Proxy

  6. Per aggiornare la pagina, fai clic su Aggiorna . La pagina mostra un elenco di risorse che puoi proteggere.

  7. Nella colonna IAP, fai clic per attivare l'IAP per l'app.

  8. Nel browser, vai di nuovo a web-site-url.

  9. Anziché la pagina web, viene visualizzata una schermata di accesso per l'autenticazione. Quando accedi, ti viene negato l'accesso perché l'IAP non ha un elenco di utenti da consentire nell'app.

Aggiungere utenti autorizzati all'app

  1. Nella console Google Cloud, vai alla pagina Identity-Aware Proxy.

    Vai alla pagina di Identity-Aware Proxy

  2. Seleziona la casella di controllo per l'app App Engine e poi fai clic su Aggiungi amministratore.

  3. Inserisci allAuthenticatedUsers, quindi seleziona il ruolo Cloud IAP/Utente applicazione web con protezione IAP.

  4. Fai clic su Salva.

Ora qualsiasi utente che Google può autenticare può accedere all'app. Se vuoi, puoi limitare ulteriormente l'accesso aggiungendo solo una o più persone o gruppi come principali:

  • Qualsiasi indirizzo email Gmail o Google Workspace

  • Un indirizzo email di un gruppo Google

  • Un nome di dominio Google Workspace

Accedere all'app

  1. Nel browser, vai a web-site-url.

  2. Per aggiornare la pagina, fai clic su Aggiorna .

  3. Nella schermata di accesso, accedi con le tue credenziali Google.

    Viene visualizzata la pagina "Un saluto da user-email-address" con il tuo indirizzo email.

    Se continui a vedere la stessa pagina di prima, potrebbe esserci un problema con il browser che non aggiorna completamente le nuove richieste ora che hai attivato l'IAP. Chiudi tutte le finestre del browser, riaprile e riprova.

Concetti di autenticazione

Esistono diversi modi in cui un'app può autenticare i propri utenti e limitare l'accesso solo agli utenti autorizzati. I metodi di autenticazione comuni, in ordine decrescente di complessità per l'app, sono elencati nelle sezioni seguenti.

Opzione Vantaggi Svantaggi
Autenticazione dell'app
  • L'app può essere eseguita su qualsiasi piattaforma, con o senza connessione a internet
  • Gli utenti non devono utilizzare altri servizi per gestire l'autenticazione
  • L'app deve gestire le credenziali utente in modo sicuro e proteggerle dalla divulgazione
  • L'app deve mantenere i dati della sessione per gli utenti che hanno eseguito l'accesso
  • L'app deve fornire registrazione utente, modifiche della password e recupero della password
OAuth2
  • L'app può essere eseguita su qualsiasi piattaforma connessa a internet, inclusa una workstation per sviluppatori
  • L'app non richiede la registrazione degli utenti, la modifica delle password o le funzioni di recupero della password.
  • Il rischio di divulgazione delle informazioni dell'utente è delegato a un altro servizio
  • Nuove misure di sicurezza per gli accessi gestite al di fuori dell'app
  • Gli utenti devono registrarsi al servizio di identità
  • L'app deve mantenere i dati della sessione per gli utenti che hanno eseguito l'accesso
IAP
  • L'app non deve avere codice per gestire utenti, autenticazione o stato della sessione
  • L'app non ha credenziali utente che potrebbero essere violate
  • L'app può essere eseguita solo sulle piattaforme supportate dal servizio. Nello specifico, alcuni servizi Google Cloud che supportano IAP, come App Engine.

Autenticazione gestita dall'app

Con questo metodo, l'app gestisce autonomamente ogni aspetto dell'autenticazione dell'utente. L'app deve gestire il proprio database di credenziali utente e le sessioni utente, nonché fornire funzioni per gestire account e password utente, controllare le credenziali utente, nonché emettere, controllare e aggiornare le sessioni utente con ogni accesso autenticato. Il seguente diagramma illustra il metodo di autenticazione gestito dall'app.

Flusso gestito dall'applicazione

Come mostrato nel diagramma, dopo che l'utente ha eseguito l'accesso, l'app crea e gestisce informazioni sulla sessione dell'utente. Quando l'utente invia una richiesta all'app, la richiesta deve includere le informazioni sulla sessione che sono di responsabilità dell'app.

Il vantaggio principale di questo approccio è che è autonomo e sotto il controllo dell'app. L'app non deve nemmeno essere disponibile su internet. Lo svantaggio principale è che ora è l'app a dover fornire tutte le funzionalità di gestione dell'account e a proteggere tutti i dati sensibili delle credenziali.

Autenticazione esterna con OAuth2

Una buona alternativa per gestire tutto all'interno dell'app è utilizzare un servizio di identità esterno, come Google, che gestisce tutte le funzionalità e le informazioni dell'account utente ed è responsabile della salvaguardia delle credenziali sensibili. Quando un utente tenta di accedere all'app, la richiesta viene reindirizzata al servizio di identità, che autentica l'utente e poi reindirizza la richiesta all'app con le informazioni di autenticazione necessarie. Per ulteriori informazioni, consulta Utilizzo di OAuth 2.0 per applicazioni server web.

Il seguente diagramma illustra l'autenticazione esterna con il metodo OAuth2.

Flusso OAuth2

Il flusso nel diagramma inizia quando l'utente invia una richiesta di accesso all'app. Anziché rispondere direttamente, l'app reindirizza il browser dell'utente alla piattaforma di identità di Google, che mostra una pagina per accedere a Google. Dopo aver eseguito correttamente l'accesso, il browser dell'utente viene reindirizzato all'app. Questa richiesta include informazioni che l'app può utilizzare per cercare informazioni sull'utente ora autenticato e l'app ora risponde all'utente.

Questo metodo presenta molti vantaggi per l'app. Delega tutte le funzionalità e i rischi di gestione dell'account al servizio esterno, che può migliorare la sicurezza di accesso e dell'account senza che l'app debba cambiare. Tuttavia, come mostrato nel diagramma precedente, l'app deve avere accesso a internet per utilizzare questo metodo. L'app è inoltre responsabile della gestione delle sessioni dopo l'autenticazione dell'utente.

Identity-Aware Proxy

Il terzo approccio, trattato in questo tutorial, consiste nell'utilizzare IAP per gestire tutta l'autenticazione e la gestione delle sessioni con eventuali modifiche all'app. IAP intercetta tutte le richieste web alla tua app, blocca quelle che non sono state autenticate e le altre le inoltra con i dati di identità utente aggiunti a ogni richiesta.

La gestione delle richieste è illustrata nel seguente diagramma.

Flusso IAP

Le richieste degli utenti vengono intercettate dall'IAP, che blocca le richieste non autenticate. Le richieste autenticate vengono trasmesse all'app, a condizione che l'utente autenticato sia nell'elenco degli utenti consentiti. Alle richieste passate tramite IAP vengono aggiunte intestazioni che identificano l'utente che ha effettuato la richiesta.

L'app non deve più gestire informazioni sull'account utente o sulla sessione. Qualsiasi operazione che debba conoscere un identificatore univoco per l'utente può ottenerlo direttamente da ogni richiesta web in arrivo. Tuttavia, può essere utilizzato solo per i servizi di calcolo che supportano IAP, come App Engine e i bilanciatori del carico. Non puoi utilizzare IAP su una macchina di sviluppo locale.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.