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 risorse di backend richiedendo che le richieste in entrata siano accompagnate da un'attestazione che dimostri che provengono dalla tua app autentica e bloccando il traffico che non dispone di un'attestazione adeguata. Firebase App Check si basa su provider di attestazione specifici della piattaforma per verificare l'autenticità del client: per le app web, App Check supporta reCAPTCHA v3 e reCAPTCHA Enterprise come provider di attestazione.

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 personalmente.

Cosa creerai

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

Cosa imparerai a fare

• Come monitorare il backend per rilevare accessi non autorizzati
• Come aggiungere 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 a tua scelta, ad esempio Chrome
• Il codice campione del codelab (vedi 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.

Il repository friendlychat-web contiene progetti di esempio per più piattaforme.

Questo codelab utilizza solo queste due cartelle:

• 📁 appcheck-start: il codice iniziale su cui si basa questo codelab.
• 📁 appcheck: il codice completo dell'app campione finita.

Nota: se vuoi eseguire l'app finita, devi creare un progetto Firebase nella Console Firebase (per istruzioni, consulta la sezione Crea e configura un progetto Firebase di questo codelab).

Importare l'app iniziale

Utilizzando il tuo IDE, apri o importa la directory 📁 appcheck-start dal repository clonato. Questa directory 📁 appcheck-start contiene il codice iniziale per il codelab, che sarà un'app web di chat completamente funzionante. 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).
   

   Questo nome del progetto viene utilizzato come nome visualizzato nelle interfacce Firebase e Firebase crea automaticamente un ID progetto univoco in base a questo nome. Tieni presente che ora puoi fare clic sull'icona Modifica per impostare l'ID progetto che preferisci, ma non potrai modificarlo dopo la creazione del progetto.

   Ricorda l'ID progetto perché ti servirà in seguito per identificare il tuo progetto Firebase nella CLI Firebase. Se dimentichi l'ID, puoi sempre trovarlo in un secondo momento nelle Impostazioni progetto.

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 (denominata "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, poi 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 con pagamento a consumo (Blaze), il che significa che è collegato a un account di fatturazione Cloud.

• Un account di fatturazione Cloud richiede un metodo di pagamento, ad esempio una carta di credito.
• Se non hai mai utilizzato Firebase e Google Cloud, verifica se hai diritto a un credito di 300$e a un account Cloud Billing di prova senza costi.
• Se stai svolgendo questo codelab nell'ambito di un evento, chiedi all'organizzatore se sono disponibili crediti Cloud.

Per eseguire l'upgrade del progetto al piano Blaze:

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 completarlo.

Nota: dopo aver completato questo codelab, puoi eseguire il downgrade del progetto al piano tariffario senza costi aggiuntivi (Spark).

Aggiungere un'app web Firebase al progetto

1. Fai clic sull'icona web per creare una nuova app web Firebase.
2. Registra l'app con lo pseudonimo Friendly Chat, poi seleziona la casella accanto a Configura anche Firebase Hosting per questa app. Fai clic su Registra 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.

4. 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.
5. Poi vedrai 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 Continua alla console. Esegui il deployment in 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 dati strutturati sul cloud e ricevere una notifica immediata quando i dati cambiano.
• Cloud Storage for Firebase per salvare i file nel cloud.
• Firebase Hosting per ospitare e pubblicare le tue risorse.
• Firebase Cloud Messaging per inviare notifiche push e visualizzare notifiche popup del browser.
• Firebase Performance Monitoring per raccogliere i dati sulle prestazioni degli utenti per la tua app.

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

Attivare Accedi con Google per Firebase Authentication

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

Dovrai attivare Accedi con Google:

1. Nella console Firebase, individua la sezione Build nel riquadro a sinistra.
2. Fai clic su Autenticazione, su Inizia, se applicabile, quindi sulla scheda Metodo di accesso (o fai clic qui per andare direttamente alla scheda).
3. Abilitare 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 del progetto dal menu a discesa.
5. Fai clic su Salva.

Configura Cloud Firestore

L'app web utilizza Cloud Firestore per salvare i messaggi di 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 posizione per il database, poi fai clic su Avanti.
   Per un'app reale, devi scegliere una posizione vicina ai tuoi utenti.
5. Fai clic su Avvia in modalità di test. Leggi l'esclusione di responsabilità relativa alle regole di sicurezza.
   Più avanti in questo codelab, aggiungerai regole di sicurezza per proteggere i tuoi dati. Nondistribuire 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 per 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 posizione per il bucket di archiviazione predefinito.
   I bucket in US-WEST1, US-CENTRAL1 e US-EAST1 possono usufruire del livello"Sempre senza costi" 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 l'esclusione di responsabilità relativa alle regole di sicurezza.
   Più avanti in questo codelab, aggiungerai regole di sicurezza per proteggere i tuoi dati. Nondistribuire o esporre pubblicamente un'app senza aggiungere regole di sicurezza per il bucket 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 tuo progetto Firebase. Per questo progetto, puoi semplicemente assegnare l'alias default. Successivamente, dovrai configurare il progetto locale per funzionare con Firebase.

1. Vai alle impostazioni del progetto nella console Firebase.
2. Nella scheda "Le tue app", seleziona il nickname dell'app per cui ti serve un oggetto di configurazione.
3. Seleziona Configurazione dal riquadro dello snippet dell'SDK Firebase.
4. Copia lo snippet dell'oggetto di configurazione e poi aggiungilo a appcheck-start/hosting/src/firebase-config.js. Il resto del codelab presuppone che la variabile sia denominata 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",
};

Il codice riportato sopra deve contenere l'oggetto di configurazione Firebase specifico per la tua app, non i valori segnaposto.

Dalla stessa directory appcheck-start, chiama:

firebase experiments:enable webframeworks

In questo modo viene abilitato il supporto del 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. Per prima cosa, installa tutte le dipendenze. Dal terminale, vai alla directory appcheck-start/hosting. All'interno della directory, esegui npm install. Vengono recuperate tutte le dipendenze necessarie per il funzionamento del progetto. Per avviare l'app nel suo stato attuale, puoi eseguire firebase serve. L'app ti chiede di accedere con un Account Google. Fallo, quindi 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 cruciale per dimostrare come funziona App Check nel mondo reale, in quanto richiede la configurazione di un dominio per il fornitore di attestazione reCAPTCHA Enterprise.

Ci auguriamo che tu stia usufruendo della funzionalità predefinita fornita dall'app. Pubblicare messaggi di chat e tutto ciò che deve essere fatto solo da un'app come questa. Lo svantaggio dello stato attuale è che chiunque disponga della configurazione dell'app del passaggio precedente può accedere alle risorse di backend. Devono comunque rispettare le regole di sicurezza in vigore nei sistemi Firestore e Cloud Storage, ma altrimenti possono comunque eseguire query, archiviare e accedere ai dati archiviati.

Nei prossimi passaggi:

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

6. Attivare 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 tuo progetto e ti verrà chiesto di abilitare l'API reCAPTCHA Enterprise. Abilita l'API e attendi qualche minuto per il completamento dell'operazione. Quindi, fai clic su Crea chiave accanto a Chiavi aziendali. Quindi, in questa sezione, specifica un nome visualizzato e seleziona una chiave di tipo Sito web. Devi specificare i domini su cui è ospitata la tua app. Poiché prevedi di ospitare questo sito su Firebase Hosting, utilizza il nome di hosting predefinito, che in genere è ${YOUR_PROJECT_ID}.web.app. Puoi trovare il tuo dominio di hosting nella sezione Hosting della console Firebase. Dopo aver compilato queste informazioni, premi Fine e Crea chiave.

Una volta completata, vedrai un ID nella parte superiore della pagina Dettagli chiave.

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 Registra, poi su reCAPTCHA Enterprise e inserisci l'ID copiato nella casella di testo per la chiave di sito reCAPTCHA Enterprise. Lascia le altre impostazioni sui valori predefiniti. La pagina Controllo app dovrebbe avere il seguente aspetto:

Richieste non verificate e non applicate

Ora che hai una chiave registrata nella console Firebase, torna a eseguire il sito nel browser eseguendo firebase serve. A questo punto l'app web viene eseguita localmente e puoi iniziare a effettuare di nuovo 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 utilizzare App Check, dovresti visualizzare un messaggio simile a questo:

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 integrato App Check.

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 modo sicuro senza preoccuparti di disattivare l'accesso per un client autentico della tua applicazione. Un altro aspetto che può essere utile è il numero di tentativi di accesso al backend che non provengono dall'app. Potrebbe trattarsi di utenti che interrogano il backend direttamente a tua insaputa. Poiché puoi vedere che le richieste non sono verificate, è il momento di vedere cosa succederebbe agli utenti che potrebbero avere una richiesta non verificata al tuo backend prima di passare alla verifica delle loro richieste.

Richieste non verificate e applicate

Premi il pulsante Applica nella schermata precedente e poi premi di nuovo Applica se richiesto.

In questo modo, App Check inizierà a essere applicato e bloccherà le richieste ai tuoi servizi di backend che non sono verificate tramite il fornitore di attestazione scelto (in questo caso reCAPTCHA Enterprise). Torna all'app web per la corsa, che dovrebbe essere in esecuzione alle ore 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.

App Check blocca 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 esamineremo come aggiungere App Check reCAPTCHA Enterprise all'esempio di Friendly Chat.

7. Aggiungi la chiave reCAPTCHA Enterprise al sito

Aggiungeremo la chiave aziendale 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 utilizzare 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';

Nella riga successiva, crea 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 potrai 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 funzionare 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 ritardi quando l'utente interagisce con il tuo servizio nel caso in cui il token App Check non sia più valido.

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 sia inizializzata, devi chiamare la funzione setupAppCheck che hai appena creato. 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();

Testa localmente prima di tutto

Testa prima l'applicazione 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 fornitore di attestazione reCAPTCHA e non con il dominio localhost. Non registrare mai localhost come dominio approvato, in quanto ciò consente agli utenti di accedere ai backend con limitazioni da un'applicazione in esecuzione localmente sulla loro macchina. Poiché hai impostato self.FIREBASE_APPCHECK_DEBUG_TOKEN = true, devi controllare nella console JavaScript una riga simile a questa:

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.

Prendi il token di debug fornito (nell'esempio è 55183c20-de61-4438-85e6-8065789265be) e inseriscilo nella configurazione di App Check nel menu di overflow della tua app.

Assegna al token un nome univoco facile da ricordare 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 all'incorporamento nell'applicazione. L'incorporamento di un token all'interno dell'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.

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 visualizzare i dati inseriti in precedenza nella versione locale dell'applicazione web. Dovresti comunque vedere il messaggio con il token di debug stampato nella console.

Prova in produzione

Una volta verificato 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, la tua applicazione web verrà pacchettizzata per essere eseguita su Firebase Hosting. Una volta ospitata l'applicazione su Firebase Hosting, prova a visitarla all'indirizzo ${YOUR_PROJECT_ID}.web.app. Puoi aprire la console JavaScript e non dovresti più vedere il token di debug stampato e dovresti vedere le chat caricate nel tuo progetto. Inoltre, dopo aver interagito con l'applicazione per alcuni istanti, puoi visitare la sezione App Check della console Firebase e verificare che le richieste alla tua applicazione siano tutte verificate.

8. Complimenti!

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

Configura la console Firebase per gestire un token reCAPTCHA Enterprise per gli ambienti di produzione e configura anche i token di debug per lo sviluppo locale. In questo modo, le tue app possono comunque accedere alle risorse Firebase dai client approvati e si impedisce che si verifichino attività fraudolente all'interno dell'applicazione.

Passaggi successivi

Consulta la seguente documentazione per aggiungere Firebase App Check a:

• Abilita l'applicazione in Cloud Functions
• Verificare i token App Check sui backend personalizzati

Documenti di riferimento

• Inizia a utilizzare App Check con reCAPTCHA Enterprise nelle app web
• Utilizzare il provider di debug nelle app web