Autenticazione degli utenti con PHP

---

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

Obiettivi

• Richiedi agli utenti della tua app App Engine di autenticarsi mediante 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:

• App Engine
• IAP

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

Una volta completate le attività descritte in questo documento, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per ulteriori informazioni, consulta la pagina 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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Install the Google Cloud CLI.

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

   gcloud init

Premesse

Questo tutorial utilizza IAP per autenticare gli utenti. Questo è solo uno dei vari 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 utilizzata per questo tutorial è un'app Hello World App Engine minima, con una funzionalità diversa da "Hello world": invece di "Hello world" visualizza "Ciao 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. Vengono aggiunte tre nuove intestazioni di richiesta a ogni richiesta web che raggiunge la tua app. Le prime due intestazioni sono stringhe di testo normale che puoi utilizzare per identificare l'utente. La terza intestazione è un oggetto firmato tramite crittografia con le stesse informazioni.

• X-Goog-Authenticated-User-Email: l'indirizzo email di un utente lo identifica. Non archiviare informazioni personali se la tua app può evitarle. Questa app non memorizza alcun dato, ma li riporta 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 già visualizzato in precedenza.

• X-Goog-Iap-Jwt-Assertion: puoi configurare le app Google Cloud in modo che accettino richieste web da altre app cloud, ignorando IAP, oltre alle richieste web su internet. Se un'app è configurata in questo modo, è possibile che queste richieste abbiano intestazioni falsificate. Anziché utilizzare una delle intestazioni di testo normale menzionate in precedenza, puoi utilizzare e verificare questa intestazione con firma crittografica per controllare che le informazioni siano state fornite da Google. Sia l'indirizzo email dell'utente sia un ID utente permanente sono disponibili come parte di questa intestazione firmata.

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

$userId = getallheaders()['X-Goog-Authenticated-User-Id'] ?? null;

Nota: la funzione getallheaders è disponibile solo per NGINX in PHP 7.3 o versioni successive.

Tuttavia, un'app resiliente dovrebbe aspettarsi che si verifichino problemi, inclusi problemi di configurazione imprevista o ambientali, quindi consigliamo invece di creare una funzione che utilizzi e verifichi l'intestazione firmata crittograficamente. La firma di questa intestazione non può essere contraffatta e, una volta verificata, può essere utilizzata per restituire l'identificazione.

Crea il codice sorgente

1. Utilizza un editor di testo per creare un file denominato index.php e incolla al suo interno il seguente codice:

   auth-users/index.php

   Visualizza su GitHub

   require_once __DIR__ . '/vendor/autoload.php';
   
   /**
    * Checks that the JWT assertion is valid (properly signed, for the
    * correct audience) and if so, returns strings for the requesting user's
    * email and a persistent user ID. If not valid, returns null for each field.
    *
    * @param string $idToken The JWT string to assert.
    * @param string $audience The audience of the JWT.
    *
    * @return string[] array containing [$email, $id]
    * @throws Exception on failed validation
    */
   function validate_assertion(string $idToken, string $audience) : array
   {
       $auth = new Google\Auth\AccessToken();
       $info = $auth->verify($idToken, [
         'certsLocation' => Google\Auth\AccessToken::IAP_CERT_URL,
         'throwException' => true,
       ]);
   
       if ($audience != $info['aud'] ?? '') {
           throw new Exception(sprintf(
               'Audience %s did not match expected %s', $info['aud'], $audience
           ));
       }
   
       return [$info['email'], $info['sub']];
   }
   
   /**
    * This is an example of a front controller for a flat file PHP site. Using a
    * static list provides security against URL injection by default.
    */
   switch (@parse_url($_SERVER['REQUEST_URI'])['path']) {
       case '/':
           if (!Google\Auth\Credentials\GCECredentials::onGce()) {
               throw new Exception('You must deploy to appengine to run this sample');
           }
           $metadata = new Google\Cloud\Core\Compute\Metadata();
           $audience = sprintf(
               '/projects/%s/apps/%s',
               $metadata->getNumericProjectId(),
               $metadata->getProjectId()
           );
           $idToken = getallheaders()['X-Goog-Iap-Jwt-Assertion'] ?? '';
           try {
               list($email, $id) = validate_assertion($idToken, $audience);
               printf("<h1>Hello %s</h1>", $email);
           } catch (Exception $e) {
               printf('Failed to validate assertion: %s', $e->getMessage());
           }
           break;
       case '': break; // Nothing to do, we're running our tests
       default:
           http_response_code(404);
           exit('Not Found');
   }

   Questo file index.php è spiegato in dettaglio nella sezione Introduzione al codice più avanti in questo tutorial.

2. Crea un altro file denominato composer.json e incolla quanto segue:

   auth-users/composer.json

   Visualizza su GitHub

   {
     "require": {
       "php": ">=7.1",
       "google/auth": "^1.9",
       "google/cloud-core": "^1.32",
       "kelvinmo/simplejwt": "^0.4.0"
     }
   }
   

   Il file composer.json elenca tutte le librerie PHP necessarie all'applicazione App Engine per caricarle:

   • firebase/php-jwt fornisce la funzione di controllo e decodifica JWT.

   • guzzle/http è un client HTTP per il recupero dei dati dai siti web.

3. Crea un file denominato app.yaml e inserisci il seguente testo:

   auth-users/app.yaml

   Visualizza su GitHub

   runtime: php73
   

   Il file app.yaml indica ad App Engine quale ambiente di linguaggio richiede il codice.

Nozioni di base sul codice

Questa sezione spiega come funziona il codice in index.php. Se vuoi solo eseguire l'app, puoi passare direttamente alla sezione Deployment dell'app.

Il codice seguente è nel file index.php. Quando l'app riceve una richiesta HTTP GET alla home page, viene richiamata la richiesta di passaggio per /:

auth-users/index.php

Visualizza su GitHub

/**
 * This is an example of a front controller for a flat file PHP site. Using a
 * static list provides security against URL injection by default.
 */
switch (@parse_url($_SERVER['REQUEST_URI'])['path']) {
    case '/':
        if (!Google\Auth\Credentials\GCECredentials::onGce()) {
            throw new Exception('You must deploy to appengine to run this sample');
        }
        $metadata = new Google\Cloud\Core\Compute\Metadata();
        $audience = sprintf(
            '/projects/%s/apps/%s',
            $metadata->getNumericProjectId(),
            $metadata->getProjectId()
        );
        $idToken = getallheaders()['X-Goog-Iap-Jwt-Assertion'] ?? '';
        try {
            list($email, $id) = validate_assertion($idToken, $audience);
            printf("<h1>Hello %s</h1>", $email);
        } catch (Exception $e) {
            printf('Failed to validate assertion: %s', $e->getMessage());
        }
        break;
    case '': break; // Nothing to do, we're running our tests
    default:
        http_response_code(404);
        exit('Not Found');
}

L'istruzione switch ottiene il valore dell'intestazione dell'asserzione JWT che IAP ha aggiunto dalla richiesta in entrata e chiama una funzione per convalidare il valore firmato crittograficamente. Il primo valore restituito (email) viene quindi utilizzato in una pagina web minima che crea e restituisce.

auth-users/index.php

Visualizza su GitHub

/**
 * Checks that the JWT assertion is valid (properly signed, for the
 * correct audience) and if so, returns strings for the requesting user's
 * email and a persistent user ID. If not valid, returns null for each field.
 *
 * @param string $idToken The JWT string to assert.
 * @param string $audience The audience of the JWT.
 *
 * @return string[] array containing [$email, $id]
 * @throws Exception on failed validation
 */
function validate_assertion(string $idToken, string $audience) : array
{
    $auth = new Google\Auth\AccessToken();
    $info = $auth->verify($idToken, [
      'certsLocation' => Google\Auth\AccessToken::IAP_CERT_URL,
      'throwException' => true,
    ]);

    if ($audience != $info['aud'] ?? '') {
        throw new Exception(sprintf(
            'Audience %s did not match expected %s', $info['aud'], $audience
        ));
    }

    return [$info['email'], $info['sub']];
}

La funzione validate_assertion utilizza la libreria google/auth per verificare che l'asserzione sia firmata correttamente ed estrarre le informazioni del payload dall'asserzione. Se l'asserzione non può essere decodificata, la funzione genera un'eccezione. Se ha esito positivo, la funzione restituisce l'indirizzo email dell'utente autenticato e un ID univoco permanente per l'utente.

La convalida di un'asserzione JWT richiede la conoscenza dei certificati di chiave pubblica dell'entità che l'ha firmata (Google in questo caso) e il pubblico a cui è destinata l'asserzione. Per un'app App Engine, il segmento di pubblico è una stringa contenente informazioni di identificazione del progetto Google Cloud. Questa funzione ottiene i certificati e la stringa di pubblico dalle funzioni che la precedono.

auth-users/index.php

Visualizza su GitHub

$metadata = new Google\Cloud\Core\Compute\Metadata();
$audience = sprintf(
    '/projects/%s/apps/%s',
    $metadata->getNumericProjectId(),
    $metadata->getProjectId()
);

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 per ogni app App Engine.

Il servizio di metadati App Engine (e servizi di metadati simili per altri servizi di computing di Google Cloud) sembra un sito web ed è oggetto di query tramite query web standard. Tuttavia, non si tratta di un sito esterno, ma di una funzionalità interna che restituisce le informazioni richieste sull'app in esecuzione, perciò è sicuro utilizzare le richieste http anziché https. Viene utilizzato per ottenere gli identificatori Google Cloud attuali necessari per definire il pubblico previsto dell'asserzione JWT.

Deployment dell'app

Ora puoi eseguire il deployment dell'app e abilitare IAP per richiedere agli utenti di eseguire l'autenticazione prima di poter accedere.

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

   gcloud app deploy
   

2. Quando richiesto, seleziona una regione vicina.

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

   In pochi minuti l'app sarà disponibile su Internet.

4. Visualizza l'app:

   gcloud app browse
   

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

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

   Non viene visualizzata alcuna email perché non stai ancora utilizzando IAP, quindi le informazioni sugli utenti non vengono inviate all'app.

Abilita 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 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 IAP.

   Fai clic su Configura schermata consenso.

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

   • Se il tuo account fa parte di un'organizzazione Google Workspace, seleziona Esterno e fai clic su Crea. Per iniziare, l'app sarà disponibile soltanto per gli utenti esplicitamente consentiti.

   • Nel campo Nome applicazione, inserisci IAP Example.

   • Nel campo Email dell'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 della 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 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 IAP per l'app.

8. Nel browser, visita di nuovo la pagina web-site-url.

9. Al posto della pagina web, è disponibile una schermata di accesso per autenticarti. Quando esegui l'accesso, ti viene negato l'accesso perché IAP non dispone di un elenco di utenti ai quali consentire di accedere all'app.

Aggiungi utenti autorizzati all'app

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

   Vai alla pagina Identity-Aware Proxy

2. Seleziona la casella di controllo per l'app App Engine, quindi fai clic su Aggiungi entità.

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 entità:

• Qualsiasi indirizzo email Gmail o Google Workspace

• L'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.

   La pagina visualizza una pagina "Ciao user-email-address" con il tuo indirizzo email.

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

Concetti di autenticazione

Un'app può autenticare i suoi utenti e limitare l'accesso solo agli utenti autorizzati in diversi modi. Nelle sezioni seguenti sono elencati i metodi di autenticazione comuni, con un livello di impegno decrescente per l'app.

Opzione	Vantaggi	Svantaggi
Autenticazione app	L'app può essere eseguita su qualsiasi piattaforma, con o senza connessione a internet Gli utenti non devono utilizzare nessun altro servizio per gestire l'autenticazione	L'app deve gestire le credenziali utente in modo sicuro e prevenire la divulgazione L'app deve conservare i dati delle sessioni degli 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 dell'utente, la modifica della password o le funzioni di recupero della password. Il rischio di divulgazione di informazioni sugli utenti è delegato a un altro servizio Nuove misure di sicurezza per l'accesso gestite al di fuori dell'app	Gli utenti devono registrarsi al servizio di identità L'app deve conservare i dati delle sessioni degli utenti che hanno eseguito l'accesso
IAP	L'app non richiede alcun codice per gestire gli utenti, l'autenticazione o lo stato della sessione L'app non ha credenziali utente che potrebbero essere state violate	L'app può essere eseguita solo su piattaforme supportate dal servizio. In particolare, 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 utente. L'app deve mantenere il proprio database di credenziali utente e gestire le sessioni utente e deve fornire funzioni per la gestione di account utente e password, per il controllo delle credenziali degli utenti, nonché per l'esecuzione di problemi, il controllo e l'aggiornamento delle sessioni utente con ogni accesso autenticato. Il seguente diagramma illustra il metodo di autenticazione gestito dall'app.

Come mostrato nel diagramma, dopo che l'utente ha eseguito l'accesso, l'app crea e conserva le informazioni sulla sessione dell'utente. Quando l'utente invia una richiesta all'app, questa deve includere informazioni sulla sessione che l'app deve verificare.

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 è responsabile di fornire tutte le funzionalità di gestione degli account e di proteggere tutti i dati sensibili delle credenziali.

Autenticazione esterna con OAuth2

Una buona alternativa alla gestione di tutto all'interno dell'app è utilizzare un servizio di identità esterno, come Google, che gestisce tutte le informazioni e le funzionalità degli 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 fornendo le informazioni di autenticazione necessarie. Per ulteriori informazioni, consulta l'articolo sull'utilizzo di OAuth 2.0 per applicazioni server web.

Il seguente diagramma illustra l'autenticazione esterna con il metodo 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. Una volta eseguito 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. L'app ora risponde all'utente.

Questo metodo presenta numerosi vantaggi per l'app. Delega al servizio esterno tutte le funzionalità e i rischi della gestione degli account, in modo da migliorare la sicurezza dell'accesso e dell'account senza dover cambiare l'app. Tuttavia, come mostrato nel diagramma precedente, l'app deve avere accesso a internet per utilizzare questo metodo. L'app è anche responsabile della gestione delle sessioni dopo l'autenticazione dell'utente.

Identity-Aware Proxy

Il terzo approccio, illustrato in questo tutorial, consiste nell'utilizzare IAP per gestire tutta l'autenticazione e la gestione delle sessioni con qualsiasi modifica all'app. IAP intercetta tutte le richieste web alla tua app, blocca quelle non autenticate e trasmette gli altri dati sull'identità dell'utente a ogni richiesta.

La gestione delle richieste è mostrata nel diagramma seguente.

Le richieste degli utenti vengono intercettate da 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 alcun account utente o informazioni sulle sessioni. Qualsiasi operazione che richieda un identificatore univoco per l'utente può ottenerlo direttamente da ogni richiesta web in entrata. Tuttavia, può essere utilizzato solo per i servizi di computing 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.

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività descritte in questo documento, quando lo elimini elimini anche tutto il lavoro svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un appspot.com URL, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, il riuso dei progetti può aiutarti a non superare i limiti di quota.

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.

Passaggi successivi

• Scopri di più su IAP.
• Gestione delle sessioni con Firestore.
• Aggiungi l'elaborazione in background con Pub/Sub e Cloud Run.
• Esegui il deployment di un'app in Compute Engine.
• Esegui il deployment di un'app in Google Kubernetes Engine.