Iniziare a utilizzare App Check con reCAPTCHA Enterprise nelle app web

Questa pagina mostra come abilitare App Check in un'app web utilizzando il provider reCAPTCHA Enterprise. Quando abiliti App Check, contribuisci a garantire che solo la tua app possa accedere alle risorse di backend del tuo progetto. Consulta una panoramica di questa funzionalità.

Tieni presente che App Check utilizza le chiavi di sito basate sul punteggio di reCAPTCHA Enterprise, che lo rendono invisibile agli utenti. Il provider reCAPTCHA Enterprise non richiederà mai agli utenti di risolvere una richiesta di verifica.

Se il tuo caso d'uso richiede funzionalità di reCAPTCHA Enterprise non implementate da App Check, o se vuoi utilizzare App Check con il tuo provider personalizzato, consulta Implementare un provider App Check personalizzato.

1. Configurare il progetto Firebase

Aggiungi Firebase al tuo progetto JavaScript, se non l'hai già fatto.
Apri la sezione reCAPTCHA Enterprise della console Cloud e procedi nel seguente modo:
1. Se ti viene chiesto di abilitare l'API reCAPTCHA Enterprise, fallo.
2. Crea una chiave di tipo Sito web. Dovrai specificare i domini su cui ospiti la tua app web. Lascia l'opzione "Utilizza la richiesta di verifica con casella di controllo" deselezionata.
Registra le tue app per utilizzare App Check con il provider reCAPTCHA Enterprise nella sezione App Check della console Firebase. Dovrai fornire la chiave di sito che hai ottenuto nel passaggio precedente.

In genere, devi registrare tutte le app del tuo progetto, perché una volta abilitata l'applicazione forzata per un prodotto Firebase, solo le app registrate potranno accedere alle risorse di backend del prodotto.
Facoltativo: nelle impostazioni di registrazione dell'app, imposta una durata (TTL) personalizzata per i token App Check emessi dal provider. Puoi impostare la durata TTL su qualsiasi valore compreso tra 30 minuti e 7 giorni. Quando modifichi questo valore, tieni presente i seguenti compromessi:
- Sicurezza: le durate TTL più brevi offrono una maggiore sicurezza, perché riducono la finestra in cui un token trapelato o intercettato può essere utilizzato in modo illecito da un utente malintenzionato.
- Prestazioni: le durate TTL più brevi significano che la tua app eseguirà l'attestazione più frequentemente. Poiché il processo di attestazione dell'app aggiunge latenza alle richieste di rete ogni volta che viene eseguito, una durata TTL breve può influire sulle prestazioni dell'app.
- Quota e costi: le durate TTL più brevi e la riattestazione frequente esauriscono la quota più rapidamente e, per i servizi a pagamento, potrebbero costare di più. Consulta Quote e limiti.
La durata TTL predefinita di 1 ora è ragionevole per la maggior parte delle app. Tieni presente che la App Check libreria aggiorna token a circa metà della durata TTL.

Configurare le impostazioni avanzate (facoltativo)

Quando un utente visita la tua app web, reCAPTCHA Enterprise valuta il livello di rischio dell'interazione dell'utente e restituisce un punteggio compreso tra 0,0 e 1,0, con incrementi di 0,1. Il punteggio 1,0 indica che l'interazione presenta un rischio basso e molto probabilmente è legittima, mentre 0,0 indica che l'interazione presenta un rischio elevato e potrebbe essere fraudolenta. App Check ti consente di configurare una soglia di rischio dell' app in modo da poter regolare la tolleranza a questo rischio.

Per la maggior parte dei casi d'uso, è consigliato il valore di soglia predefinito di 0,5. Se il tuo caso d'uso richiede una regolazione, puoi configurarlo nella App Check sezione della Firebase console per ciascuna delle tue app web.

Dettagli

App Check utilizza la soglia di rischio dell'app configurata come punteggio minimo di reCAPTCHA Enterprise richiesto per considerare legittima un'interazione utente. Tutti i punteggi di reCAPTCHA Enterprise strettamente inferiori alla soglia configurata verranno rifiutati. Quando regoli la soglia di rischio dell'app, tieni presente quanto segue:

Dei 11 possibili livelli di punteggio di reCAPTCHA Enterprise, solo i seguenti quattro sono disponibili prima di aggiungere un account di fatturazione Cloud al tuo progetto: 0,1, 0,3, 0,7 e 0,9. Durante questo periodo, App Check consentirà di conseguenza solo i valori di soglia di rischio dell'app 0,1, 0,3, 0,5, 0,7, e 0,9. Per la maggior parte dei casi d'uso, è comunque consigliato un valore di soglia di rischio dell'app pari a 0,5.
- Per abilitare tutti gli 11 livelli di punteggio di reCAPTCHA Enterprise, aggiungi un account di fatturazione Google Cloud al tuo progetto. Un modo per farlo è eseguire l'upgrade al piano tariffario Blaze. Una volta fatto, App Check ti consentirà di configurare qualsiasi app valore di soglia di rischio compreso tra 0,0 e 1,0, con incrementi di 0,1.
  
  Nota: dopo aver aggiunto un account di fatturazione Google Cloud al tuo progetto, viene attivata una revisione automatica della sicurezza per il progetto. Per ulteriori informazioni, consulta la documentazione di reCAPTCHA Enterprise.
Per monitorare la distribuzione dei punteggi di reCAPTCHA Enterprise alti e bassi per la tua app web, visita la pagina reCAPTCHA Enterprise nella Google Cloud console e seleziona la chiave di sito utilizzata dalla tua app web.
Se hai una tolleranza di rischio dell'app bassa, sposta il cursore verso sinistra per aumentare la soglia di rischio dell'app.
- Un valore pari a 1,0 non è consigliato, in quanto questa impostazione potrebbe anche negare l'accesso agli utenti legittimi che non soddisfano questa soglia di attendibilità elevata.
Avviso: prima di aumentare la soglia di rischio dell'app, ti consigliamo di disattivare temporaneamente la protezione App Check per tutti i servizi attualmente applicati per evitare di interrompere gli utenti legittimi. Prima di riprendere l'applicazione forzata, devi monitorare le metriche delle richieste App Check per verificare che il traffico non sia stato interrotto.
Se hai una tolleranza di rischio dell'app alta, sposta il cursore verso destra per diminuire la soglia di rischio dell'app.
- Un valore pari a 0,0 non è consigliato, in quanto questa impostazione disabilita la protezione dai comportamenti illeciti.

Per ulteriori dettagli, consulta la documentazione di reCAPTCHA Enterprise.

2. Aggiungere la libreria App Check all'app

Aggiungi Firebase alla tua app web, se non l'hai già fatto. Assicurati di importare la App Check libreria.

3. Inizializzare App Check

Aggiungi il seguente codice di inizializzazione all'applicazione prima di accedere a qualsiasi servizio Firebase. Dovrai passare la chiave di sito reCAPTCHA Enterprise, che hai creato nella console Cloud, a activate().

Web

import { initializeApp } from "firebase/app";
import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";

const app = initializeApp({
  // Your Firebase configuration object.
});

// Create a ReCaptchaEnterpriseProvider instance using your reCAPTCHA Enterprise
// site key and pass it to initializeAppCheck().
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider(/* reCAPTCHA Enterprise site key */),
  isTokenAutoRefreshEnabled: true // Set to true to allow auto-refresh.
});

Web

firebase.initializeApp({
  // Your Firebase configuration object.
});

// Create a ReCaptchaEnterpriseProvider instance using your reCAPTCHA Enterprise
// site key and pass it to activate().
const appCheck = firebase.appCheck();
appCheck.activate(
  new firebase.appCheck.ReCaptchaEnterpriseProvider(
    /* reCAPTCHA Enterprise site key */
  ),
  true // Set to true to allow auto-refresh.
);

Passaggi successivi

Una volta installata la libreria App Check nell'app, esegui il deployment.

L'app client aggiornata inizierà a inviare i token App Check insieme a ogni richiesta a Firebase, ma i prodotti Firebase non richiederanno la validità dei token finché non abiliti l'applicazione forzata nella sezione App Check della console Firebase.

Monitorare le metriche e abilitare l'applicazione forzata

Prima di abilitare l'applicazione forzata, devi assicurarti che non interrompa gli utenti legittimi esistenti. D'altra parte, se noti un utilizzo sospetto delle risorse dell'app, potresti voler abilitare l'applicazione forzata prima.

Per aiutarti a prendere questa decisione, puoi esaminare le metriche App Check per i servizi che utilizzi:

Monitora le metric1/} metriche delle richieste per Firebase AI Logic, Data Connect, Realtime Database, Cloud Firestore, Cloud Storage, Authentication, Google Identity per iOS, API Maps JavaScript e API Places (nuova).App Check
Monitora le metriche delle richieste App Check per Cloud Functions.

Abilitare l'applicazione forzata di App Check

Quando hai compreso l'impatto di App Check sugli utenti e sei pronto per procedere, puoi abilitare l'applicazione forzata di App Check:

Abilita l'App Checkapplicazione forzata per Firebase AI Logic, Data Connect, Realtime Database, Cloud Firestore, Cloud Storage, Authentication, Google Identity per iOS, API Maps JavaScript e API Places (nuova).
Abilita l'applicazione forzata per App CheckCloud Functions.

Utilizzare App Check negli ambienti di debug

Se, dopo aver registrato l'app per App Check, vuoi eseguire la tua app in un ambiente che App Check normalmente non classificherebbe come valido, ad esempio localmente durante lo sviluppo o da un ambiente di integrazione continua (CI), puoi creare una build di debug della tua app che utilizza il provider di debug di App Check anziché un provider di attestazione reale.

Consulta Utilizzare App Check con il provider di debug nelle app web.

Nota sui costi

App Check crea una valutazione per tuo conto per convalidare il token di risposta dell'utente ogni volta che un browser che esegue la tua app web aggiorna il token App Check. Al tuo progetto verrà addebitato un costo per ogni valutazione creata al di sopra della quota senza costi aggiuntivi. Per i dettagli, consulta i prezzi di reCAPTCHA.

Per impostazione predefinita, la tua app web aggiornerà questo token due volte ogni ora. Per controllare la frequenza con cui l'app aggiorna i token App Check (e quindi la frequenza con cui vengono create nuove valutazioni), configura la durata TTL.