Codelab web di Controllo app

1. Introduzione

Ultimo aggiornamento: 23/02/2023

Come puoi impedire l'accesso non autorizzato alle tue risorse Firebase?

Puoi utilizzare Firebase App Check per impedire ai client non autorizzati di accedere alle tue risorse di backend, richiedendo che le richieste in arrivo siano accompagnate da un'attestazione che la richiesta proviene dalla tua app autentica e bloccando il traffico che non dispone di un'attestazione corretta. Firebase App Check si basa su provider di attestazioni specifici della piattaforma per verificare l'autenticità del client: per le app web, App Check supporta reCAPTCHA v3 e reCAPTCHA Enterprise come provider di attestazioni.

App Check può essere utilizzato per proteggere le richieste a Cloud Firestore, Realtime Database, Cloud Functions, Firebase Authentication con Identity Platform e sui backend che ospiti tu.

Cosa creerai

In questo codelab, proteggerai un'applicazione di chat aggiungendo e poi applicando App Check.

L'app di chat iniziale Friendly Chat creata da te.

Cosa imparerai a fare

  • Come monitorare il backend per rilevare accessi non autorizzati
  • Come applicare l'applicazione a Firestore e Cloud Storage
  • Come eseguire l'applicazione con un token di debug per lo sviluppo locale

Che cosa ti serve

  • L'IDE/editor di testo che preferisci
  • Il gestore di pacchetti npm, che in genere viene fornito con Node.js
  • L'interfaccia a riga di comando di Firebase installata e configurata per funzionare con il tuo account
  • Un terminale/una console
  • Un browser di tua scelta, ad esempio Chrome
  • Il codice campione del codelab (consulta il passaggio successivo del codelab per scoprire come ottenere il codice).

2. recupera il codice campione

Clona il repository GitHub del codelab dalla riga di comando:

git clone https://github.com/firebase/codelab-friendlychat-web

In alternativa, se non hai installato Git, puoi scaricare il repository come file ZIP.

Importa l'app iniziale

Utilizzando l'IDE, apri o importa la directory 📁 appcheck-start dal repository clonato. Questa directory 📁 appcheck-start contiene il codice iniziale del codelab, che sarà un'app web di chat completamente funzionale. La directory 📁 appcheck conterrà il codice completato per il codelab.

3. Crea e configura un progetto Firebase

Crea un progetto Firebase

  1. Accedi alla console Firebase utilizzando il tuo Account Google.
  2. Fai clic sul pulsante per creare un nuovo progetto, quindi inserisci un nome per il progetto (ad esempio FriendlyChat).
  3. Fai clic su Continua.
  4. Se richiesto, leggi e accetta i Termini di Firebase, quindi fai clic su Continua.
  5. (Facoltativo) Attiva l'assistenza AI nella console Firebase (chiamata "Gemini in Firebase").
  6. Per questo codelab, non hai bisogno di Google Analytics, quindi disattiva l'opzione Google Analytics.
  7. Fai clic su Crea progetto, attendi il provisioning del progetto, quindi fai clic su Continua.

Esegui l'upgrade del piano tariffario Firebase

Per utilizzare Cloud Storage for Firebase, il tuo progetto Firebase deve essere incluso nel piano tariffario Blaze con pagamento a consumo, il che significa che è collegato a un account di fatturazione Cloud.

Per eseguire l'upgrade del progetto al piano Blaze, segui questi passaggi:

  1. Nella console Firebase, seleziona l'opzione per eseguire l'upgrade del piano.
  2. Seleziona il piano Blaze. Segui le istruzioni sullo schermo per collegare un account di fatturazione Cloud al tuo progetto.
    Se hai dovuto creare un account di fatturazione Cloud nell'ambito di questo upgrade, potresti dover tornare al flusso di upgrade nella console Firebase per completare l'upgrade.

Aggiungi un'app web Firebase al progetto

  1. Fai clic sull'icona web 58d6543a156e56f9.png per creare una nuova app web Firebase.
  2. Registra l'app con il nickname Friendly Chat, quindi seleziona la casella accanto a Inoltre, configura Firebase Hosting per questa app. Fai clic su Registra l'app.
  3. Nel passaggio successivo, vedrai un comando per installare Firebase utilizzando npm e un oggetto di configurazione. Copierai questo oggetto più avanti nel codelab, quindi per ora premi Avanti.

La finestra Aggiungi Firebase alla tua app web

  1. Poi vedrai un'opzione per installare l'interfaccia a riga di comando di Firebase. Se non l'hai ancora installato, fallo ora utilizzando il comando npm install -g firebase-tools. Quindi, fai clic su Avanti.
  2. Viene visualizzata un'opzione per accedere a Firebase ed eseguire il deployment in Firebase Hosting. Accedi a Firebase utilizzando il comando firebase login, quindi fai clic su Vai alla console. Eseguirai il deployment su Firebase Hosting in un passaggio successivo.

Configura i prodotti Firebase

L'applicazione che creeremo utilizza i prodotti Firebase disponibili per le app web:

  • Firebase Authentication per consentire facilmente agli utenti di accedere alla tua app.
  • Cloud Firestore per salvare i dati strutturati nel cloud e ricevere una notifica istantanea quando i dati cambiano.
  • Cloud Storage for Firebase per salvare i file nel cloud.
  • Firebase Hosting per ospitare e pubblicare i tuoi asset.
  • Firebase Cloud Messaging per inviare notifiche push e visualizzare notifiche popup del browser.
  • Firebase Performance Monitoring per raccogliere i dati sul rendimento degli utenti per la tua app.

Alcuni di questi prodotti richiedono una configurazione speciale o devono essere abilitati utilizzando la console Firebase.

Attiva Accedi con Google per Firebase Authentication

Per consentire agli utenti di accedere all'app web con i loro Account Google, utilizzeremo il metodo Accedi con Google.

Dovrai attivare Accedi con Google:

  1. Nella console Firebase, individua la sezione Build nel riquadro a sinistra.
  2. Fai clic su Authentication, poi su Get Started se applicabile, quindi fai clic sulla scheda metodo di accesso (o fai clic qui per andare direttamente alla scheda).
  3. Attiva il provider di accesso con Google
  4. Imposta il nome visibile al pubblico della tua app su Friendly Chat e scegli un'email di assistenza per il progetto dal menu a discesa.
  5. Fai clic su Salva.

f96888973c3d00cc.png

Configura Cloud Firestore

L'app web utilizza Cloud Firestore per salvare i messaggi chat e riceverne di nuovi.

Ecco come configurare Cloud Firestore nel tuo progetto Firebase:

  1. Nel riquadro a sinistra della console Firebase, espandi Build e seleziona Database Firestore.
  2. Fai clic su Crea database.
  3. Lascia l'ID database impostato su (default).
  4. Seleziona una località per il database, quindi fai clic su Avanti.
    Per un'app reale, devi scegliere una località vicina ai tuoi utenti.
  5. Fai clic su Avvia in modalità di test. Leggi il disclaimer sulle regole di sicurezza.
    Più avanti in questo codelab, aggiungerai regole di sicurezza per proteggere i tuoi dati. Non distribuire o esporre pubblicamente un'app senza aggiungere regole di sicurezza per il tuo database.
  6. Fai clic su Crea.

Configura Cloud Storage for Firebase

L'app web utilizza Cloud Storage for Firebase per archiviare, caricare e condividere immagini.

Ecco come configurare Cloud Storage for Firebase nel tuo progetto Firebase:

  1. Nel riquadro a sinistra della console Firebase, espandi Build e seleziona Storage.
  2. Fai clic su Inizia.
  3. Seleziona una località per il bucket di archiviazione predefinito.
    I bucket in US-WEST1, US-CENTRAL1 e US-EAST1 possono usufruire del livello "Always Free" per Google Cloud Storage. I bucket in tutte le altre località seguono i prezzi e l'utilizzo di Google Cloud Storage.
  4. Fai clic su Avvia in modalità di test. Leggi il disclaimer sulle regole di sicurezza.
    Più avanti in questo codelab, aggiungerai regole di sicurezza per proteggere i tuoi dati. Non distribuire o esporre pubblicamente un'app senza aggiungere regole di sicurezza per il bucket di Storage.
  5. Fai clic su Crea.

4. Configura Firebase

Dalla directory appcheck-start, chiama:

firebase use --add

Quando richiesto, seleziona l'ID progetto, quindi assegna un alias al progetto Firebase. Per questo progetto, puoi semplicemente assegnare l'alias default. Successivamente, dovrai configurare il progetto locale per l'utilizzo con Firebase.

  1. Vai alle impostazioni progetto nella console Firebase.
  2. Nella scheda "Le tue app", seleziona il nickname dell'app per cui hai bisogno di un oggetto di configurazione.
  3. Seleziona Config (Configurazione) dal riquadro dello snippet dell'SDK Firebase.
  4. Copia lo snippet dell'oggetto di configurazione e aggiungilo a appcheck-start/hosting/src/firebase-config.js. Il resto del codelab presuppone che la variabile si chiami config.

firebase-config.js

const config = {
  apiKey: "API_KEY",
  authDomain: "PROJECT_ID.firebaseapp.com",
  databaseURL: "https://PROJECT_ID.firebaseio.com",
  projectId: "PROJECT_ID",
  storageBucket: "PROJECT_ID.firebasestorage.app",
  messagingSenderId: "SENDER_ID",
  appId: "APP_ID",
  measurementId: "G-MEASUREMENT_ID",
};

Dalla stessa directory appcheck-start, chiama:

firebase experiments:enable webframeworks

In questo modo viene attivato il supporto dei framework web, con cui è stato creato questo progetto.

Ora dovremmo essere pronti per eseguire il progetto e verificare che il progetto predefinito funzioni.

5. Prova l'app senza App Check

Ora che hai configurato l'app e l'SDK, prova a utilizzare l'app come era stata originariamente progettata. Innanzitutto, installa tutte le dipendenze. Dal terminale, vai alla directory appcheck-start/hosting. All'interno della directory, esegui npm install. In questo modo vengono recuperate tutte le dipendenze necessarie per il funzionamento del progetto. Per avviare l'app nello stato corrente, puoi eseguire firebase serve. L'app ti chiede di accedere con un Account Google. Fallo e poi prova a pubblicare alcuni messaggi di chat e alcune foto nella chat.

Ora che l'hai testato localmente, è il momento di vederlo in produzione. Esegui firebase deploy per eseguire il deployment dell'applicazione web sul web. Questa parte è un passaggio fondamentale per dimostrare come funziona App Check nel mondo reale, in quanto richiede la configurazione di un dominio per il provider di attestazione reCAPTCHA Enterprise.

Ci auguriamo che tu stia sperimentando la funzionalità predefinita fornita dall'app. Pubblicare messaggi chat e tutto ciò che dovrebbe essere fatto solo da un'app come questa. Lo svantaggio dello stato attuale è che chiunque abbia la configurazione dell'app del passaggio precedente può accedere alle risorse di backend. Devono comunque rispettare le regole di sicurezza applicate dai sistemi Firestore e Cloud Storage, ma per il resto possono comunque eseguire query, archiviare e accedere ai dati archiviati lì.

Nei prossimi passaggi:

  • Registrati su App Check
  • Convalida l'applicazione
  • Inizia ad applicare le regole

6. Attiva App Check e l'applicazione

Iniziamo recuperando una chiave reCAPTCHA Enterprise per il tuo progetto e aggiungendola ad App Check. Per iniziare, visita la sezione reCAPTCHA Enterprise della console Google Cloud. Seleziona il progetto e ti verrà chiesto di abilitare l'API reCAPTCHA Enterprise. Abilita l'API e attendi qualche minuto per il completamento. Poi fai clic su Crea chiave accanto a Chiavi Enterprise. In questa sezione, specifica un nome visualizzato e seleziona un tipo di chiave Sito web. Devi specificare i domini su cui è ospitata la tua app. Poiché prevedi di ospitare l'app su Firebase Hosting, utilizza il nome host predefinito, che in genere è ${YOUR_PROJECT_ID}.web.app. Puoi trovare il tuo dominio di hosting nella sezione Hosting della console Firebase. Dopo aver inserito queste informazioni, premi Fine e Crea chiave.

Schermata di creazione della chiave reCAPTCHA

Al termine, vedrai un ID nella parte superiore della pagina Dettagli chiave.

La finestra di registrazione di reCAPTCHA Enterprise

Copia questo ID negli appunti. Questa è la chiave che utilizzi per App Check. Poi, vai alla sezione App Check della console Firebase e fai clic su Inizia. Poi, fai clic su Registrati, quindi su reCAPTCHA Enterprise e inserisci l'ID copiato nella casella di testo per la chiave di sito reCAPTCHA Enterprise. Lascia invariate le altre impostazioni predefinite. La pagina App Check dovrebbe avere il seguente aspetto:

La finestra delle app di App Check in cui registri il token reCAPTCHA Enterprise

Richieste non verificate e non applicate

Ora che hai una chiave registrata nella console Firebase, torna a eseguire il tuo sito nel browser eseguendo firebase serve. Ora l'app web è in esecuzione localmente e puoi ricominciare a effettuare richieste al backend Firebase. Poiché le richieste vengono inviate al backend Firebase, vengono monitorate da App Check, ma non vengono applicate. Se vuoi visualizzare lo stato delle richieste in arrivo, puoi visitare la sezione Cloud Firestore nella scheda API della pagina App Check nella console Firebase. Poiché non hai ancora configurato il client per l'utilizzo di App Check, dovresti vedere un messaggio simile al seguente:

Una dashboard di App Check che mostra il 100% di richieste client non verificate per la tua app.

Il backend riceve il 100% di richieste non verificate. Questa schermata è utile perché mostra che quasi tutte le richieste dei client provengono da client che non hanno App Check integrato.

Questa dashboard può indicare alcune cose. La prima cosa che può indicare è se tutte le tue app client eseguono l'ultima versione del client. In questo caso, puoi applicare App Check in sicurezza senza preoccuparti di disattivare l'accesso per un client autentico della tua applicazione. Un'altra informazione che potresti ottenere è il numero di tentativi di accesso al backend che non provengono dall'interno della tua app. Potrebbe trattarsi di utenti che eseguono query direttamente sul backend a tua insaputa. Poiché puoi vedere che le richieste non sono verificate, è il momento di vedere cosa accadrebbe agli utenti che potrebbero avere una richiesta non verificata al tuo backend prima di procedere alla verifica delle loro richieste.

Richieste non verificate e applicate

Premi il pulsante Applica nella schermata precedente, quindi premi di nuovo Applica se richiesto.

Una dashboard delle metriche non verificate con un pulsante Applica evidenziato

In questo modo, verrà avviata l'applicazione di App Check, che ora bloccherà le richieste ai tuoi servizi di backend non verificate tramite il provider di attestazione scelto (in questo caso reCAPTCHA Enterprise). Torna all'app web in esecuzione, che dovrebbe essere in esecuzione all'indirizzo http://localhost:5000. Quando aggiorni la pagina e provi a recuperare i dati dal database, non succede nulla. Se apri la console di Chrome per leggere gli errori, dovresti vedere qualcosa di simile a quanto segue:

Uncaught Error in snapshot listener: FirebaseError: [code=permission-denied]: Missing or insufficient permissions.

Ciò significa che App Check sta bloccando le richieste che non hanno superato un token di attestazione valido nelle richieste alle tue risorse Firebase. Per il momento, puoi disattivare l'applicazione di App Check e, nella sezione successiva, esaminare come aggiungere App Check di reCAPTCHA Enterprise all'esempio di Friendly Chat.

7. Aggiungi la chiave reCAPTCHA Enterprise al sito

Aggiungeremo la chiave Enterprise alla tua applicazione. Innanzitutto, apri hosting/src/firebase-config.js e aggiungi la chiave reCAPTCHA Enterprise al seguente snippet di codice:

const reCAPTCHAEnterpriseKey = {
  // Replace with your recaptcha enterprise site key
  key: "Replace with your recaptcha enterprise site key"
};

Al termine, apri hosting/src/index.js e, alla riga 51, aggiungi un'importazione da firebase-config.js per recuperare la chiave reCAPTCHA e importa anche la libreria App Check in modo da poter lavorare con il provider reCAPTCHA Enterprise.

// add from here
 import {
   initializeAppCheck,
   ReCaptchaEnterpriseProvider,
 } from 'firebase/app-check';
// to here

// replace this line
import { getFirebaseConfig } from './firebase-config.js';
// with this line
import { getFirebaseConfig, getReCaptchaKey } from './firebase-config.js';

Poi, nella riga successiva, creerai una funzione per configurare App Check. La funzione verificherà innanzitutto se ti trovi in un ambiente di sviluppo e, in caso affermativo, stamperà un token di debug che puoi utilizzare per lo sviluppo locale.

import { getFirebaseConfig, getReCaptchaKey } from './firebase-config.js';
// add from here
 function setupAppCheck(app) {
   if(import.meta.env.MODE === 'development') {
     self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   }
 }
// to here

Ora è il momento di inizializzare App Check per l'utilizzo con il provider selezionato, in questo caso reCAPTCHA Enterprise. Inoltre, ti consigliamo di aggiornare automaticamente il token App Check in background, in modo da evitare qualsiasi tipo di ritardo nell'interazione dell'utente con il tuo servizio nel caso in cui il token App Check sia diventato obsoleto.

function setupAppCheck(app) {
   if(import.meta.env.MODE === 'development') {
     self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   }
// add from here
   // Create a ReCaptchaEnterpriseProvider instance using your reCAPTCHA Enterprise
   // site key and pass it to initializeAppCheck().
   initializeAppCheck(app, {
     provider: new ReCaptchaEnterpriseProvider(getReCaptchaKey()),
     isTokenAutoRefreshEnabled: true // Set to true to allow auto-refresh.
   });
// to here
 }

Infine, dopo aver verificato che l'app è inizializzata, devi chiamare la funzione setupAppCheck appena creata. Nella parte inferiore del file hosting/src/index.js, aggiungi la chiamata al metodo aggiunto di recente.

const firebaseApp = initializeApp(getFirebaseConfig());
// add from here
setupAppCheck(firebaseApp);
// to here
getPerformance();
initFirebaseAuth();
loadMessages();

Esegui prima i test localmente

Testa l'applicazione prima localmente. Se non stai già pubblicando l'applicazione localmente, esegui firebase serve. Dovresti notare che l'applicazione non viene ancora caricata localmente. Questo perché hai registrato il tuo dominio Firebase solo con il provider di attestazioni reCAPTCHA e non con il dominio localhost. Non devi mai registrare localhost come dominio approvato, in quanto ciò consente agli utenti di accedere ai tuoi backend con limitazioni da un'applicazione in esecuzione localmente sulla loro macchina. Invece, poiché hai impostato self.FIREBASE_APPCHECK_DEBUG_TOKEN = true, dovresti controllare nella console JavaScript se è presente una riga simile alla seguente:

App Check debug token: 55183c20-de61-4438-85e6-8065789265be. You will need to add it to your app's App Check settings in the Firebase console for it to work.

Dovrai prendere il token di debug fornito (nel caso di esempio è : 55183c20-de61-4438-85e6-8065789265be) e inserirlo nella configurazione di App Check nel menu extra della tua app.

La dashboard di App Check che indica la posizione di Gestisci token di debug

Assegna al token un nome univoco che ricorderai e fai clic su Salva. Questa opzione ti consente di utilizzare un token generato dal client con la tua app, un'alternativa più sicura rispetto alla generazione di un token di debug e alla sua incorporazione nell'applicazione. L'incorporamento di un token nell'app potrebbe comportare la sua distribuzione accidentale agli utenti finali, che potrebbero sfruttarlo per aggirare i tuoi controlli. Se vuoi distribuire un token di debug, ad esempio in un ambiente CI, leggi questa documentazione per scoprire di più su come distribuirlo.

Esempio di compilazione del token di debug con un alias

Una volta registrato il token di debug nella console Firebase, puoi riattivare l'applicazione di App Check e verificare che i contenuti dell'app vengano caricati localmente chiamando firebase serve dal terminale. Dovresti vedere i dati inseriti in precedenza che vengono forniti alla versione locale dell'applicazione web. Dovresti comunque vedere il messaggio con il token di debug stampato nella console.

Prova in produzione

Una volta che hai la certezza che App Check funzioni localmente, esegui il deployment dell'applicazione web in produzione. Dal terminale, chiama di nuovo firebase deploy e ricarica la pagina. In questo modo, l'applicazione web verrà pacchettizzata per l'esecuzione su Firebase Hosting. Una volta che l'applicazione è ospitata su Firebase Hosting, prova a visitarla all'indirizzo ${YOUR_PROJECT_ID}.web.app. Puoi aprire la console JavaScript, dove non dovresti più vedere il token di debug, ma dovresti vedere le chat caricate nel tuo progetto. Inoltre, dopo aver interagito con l'applicazione per qualche istante, puoi visitare la sezione App Check della console Firebase e verificare che le richieste alla tua applicazione siano state tutte verificate.

8. Complimenti!

Congratulazioni, hai aggiunto correttamente Firebase App Check a un'app web.

Hai configurato la console Firebase per gestire un token reCAPTCHA Enterprise per gli ambienti di produzione e hai persino configurato i token di debug per lo sviluppo locale. In questo modo, le tue app possono continuare ad accedere alle risorse Firebase dai client approvati e si evitano attività fraudolente all'interno dell'applicazione.

Passaggi successivi

Consulta la seguente documentazione per aggiungere Firebase App Check a:

Documentazione di riferimento