Iniziare a utilizzare App Check con reCAPTCHA v3 nelle app web

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

Tieni presente che reCAPTCHA v3 è invisibile agli utenti. Il provider reCAPTCHA v3 non richiederà mai agli utenti di risolvere una verifica. Consulta la documentazione di reCAPTCHA v3.

Se vuoi utilizzare App Check con il tuo provider personalizzato, consulta Implementare un provider App Check personalizzato.

1. Configurare il progetto Firebase

  1. Aggiungi Firebase al tuo progetto JavaScript, se non l'hai già fatto.

  2. Registra il tuo sito per reCAPTCHA v3 e ottieni la chiave di sito e la chiave secret di reCAPTCHA v3.

  3. Nella Firebase console, vai a Sicurezza > App Check.

  4. Nella scheda App, registra le tue app per utilizzare App Check con il provider reCAPTCHA. Dovrai fornire la chiave secret che hai ottenuto nel sito reCAPTCHA.

    In genere, devi registrare tutte le app del progetto, perché una volta abilitata l'applicazione per un prodotto Firebase, solo le app registrate potranno accedere alle risorse di backend del prodotto.

  5. Facoltativo: nelle impostazioni di registrazione dell'app, imposta una durata (TTL) personalizzata per i token App Check emessi dal provider. Puoi impostare la durata su qualsiasi valore compreso tra 30 minuti e 7 giorni. Quando modifichi questo valore, tieni presente i seguenti compromessi:

    • Sicurezza: le durate 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 più brevi significano che la tua app eseguirà l'attestazione più spesso. Poiché il processo di attestazione dell'app aggiunge latenza alle richieste di rete ogni volta che viene eseguito, una durata breve può influire sulle prestazioni dell'app.
    • Quota e costi: le durate più brevi e la riattestazione frequente esauriscono più rapidamente la quota e, per i servizi a pagamento, potrebbero costare di più. Consulta Quote e limiti.

    La durata predefinita di 1 giorno è ragionevole per la maggior parte delle app. Tieni presente che la libreria App Check aggiorna i token a circa metà della durata.

Configurare le impostazioni avanzate (facoltativo)

Quando un utente visita la tua app web, reCAPTCHA v3 valuta il livello di rischio posto dall'interazione dell'utente e restituisce un punteggio compreso tra 0,0 e 1,0; 1,0 indica un'interazione molto probabilmente valida, 0,0 indica molto probabilmente un bot. 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 v3 richiesto per considerare legittima un'interazione utente. Tutti i punteggi di reCAPTCHA v3 strettamente inferiori alla soglia di rischio dell'app configurata verranno rifiutati. Quando regoli la soglia di rischio dell'app, tieni presente quanto segue:

  • Per monitorare la distribuzione dei punteggi di reCAPTCHA v3 per la tua app web, visita la console di amministrazione di reCAPTCHA e seleziona il sito corrispondente alla 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.

  • 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 v3.

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, che hai creato nella console reCAPTCHA, a activate().

Web

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

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

// Pass your reCAPTCHA v3 site key (public key) to activate(). Make sure this
// key is the counterpart to the secret key you set in the Firebase console.
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaV3Provider('abcdefghijklmnopqrstuvwxy-1234567890abcd'),

  // Optional argument. If true, the SDK automatically refreshes App Check
  // tokens as needed.
  isTokenAutoRefreshEnabled: true
});

Web

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

const appCheck = firebase.appCheck();
// Pass your reCAPTCHA v3 site key (public key) to activate(). Make sure this
// key is the counterpart to the secret key you set in the Firebase console.
appCheck.activate(
  'abcdefghijklmnopqrstuvwxy-1234567890abcd',

  // Optional argument. If true, the SDK automatically refreshes App Check
  // tokens as needed.
  true);

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 nella sezione App Check della console Firebase.

Monitorare le metriche e abilitare l'applicazione

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

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

Abilitare l'applicazione di App Check

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

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.