Abilita reCAPTCHA Enterprise

Questo documento mostra come utilizzare l'integrazione di Identity Platform con reCAPTCHA per migliorare la sicurezza dei tuoi utenti. Questa funzionalità rende la tua app più resiliente contro spam, comportamenti illeciti e altre attività fraudolente.

L'integrazione di Identity Platform con reCAPTCHA crea una test reCAPTCHA per tuo conto per convalidare le richieste degli utenti. Per informazioni sui prezzi, vedi i prezzi di reCAPTCHA.

Importante: questa funzionalità supporta solo gli accessi e le registrazioni con email e password, la reimpostazione della password e gli accessi tramite link via email. Se un utente legittimo è bloccato, consulta la sezione Risoluzione dei problemi per la procedura di risoluzione.

Panoramica

Quando configuri l'integrazione di Identity Platform con reCAPTCHA, Identity Platform esegue per tuo conto il provisioning delle chiavi di sito reCAPTCHA basate su punteggi nel tuo progetto. Quando un utente accede alla tua app o al tuo sito utilizzando una delle seguenti operazioni, l'SDK del client carica reCAPTCHA:

Operazione	Metodo
Accesso con email e password	signInWithPassword
Registrazione con email e password	signUpPassword
Accesso via email tramite link	getOobCode
Reimpostazione password	getOobCode

reCAPTCHA fornisce quindi a Identity Platform indicatori di rischio che valutano il rischio della richiesta in base alla configurazione e alla tolleranza al rischio.

Per ulteriori informazioni, consulta la panoramica di reCAPTCHA Enterprise.

Importante: In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

• reCAPTCHA Enterprise
• Identity Platform

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud possono essere idonei a una prova senza costi aggiuntivi.

Prima di iniziare

Configura l'accesso via email per gli utenti.

Crea un service account

Prima di abilitare reCAPTCHA, devi creare un account di servizio per ogni progetto che utilizzerà reCAPTCHA e concedere a ciascun account di servizio l'accesso a reCAPTCHA. In questo modo Identity Platform può gestire le chiavi reCAPTCHA per tuo conto.

Per creare un account di servizio:

1. Utilizza Google Cloud CLI per creare un account di servizio:

   gcloud beta services identity create \
       --service=identitytoolkit.googleapis.com \
       --project=PROJECT_ID
   

   Sostituisci PROJECT_ID con l'ID del progetto.

2. Concedi all'account di servizio l'accesso a reCAPTCHA:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/identitytoolkit.serviceAgent
   

   Sostituisci quanto segue:

   • PROJECT_ID: ID progetto
   • PROJECT_NUMBER: il numero di account del progetto

Abilita reCAPTCHA

reCAPTCHA prevede due modalità che ti aiutano a proteggere gli utenti:

• Controllo: se questa opzione è abilitata, Identity Platform crea una o più chiavi reCAPTCHA nel tuo progetto che vengono utilizzate per valutare il traffico verso le API Identity Platform senza bloccare alcuna richiesta. Utilizza le metriche emesse durante la modalità di controllo per determinare se è necessario abilitare l'applicazione forzata di reCAPTCHA.
• Applicazione forzata: se abilitata, Identity Platform crea una o più chiavi reCAPTCHA nel tuo progetto che vengono utilizzate per valutare il traffico verso le API Identity Platform. Le richieste API che non includono un token reCAPTCHA vengono rifiutate. Attiva l'applicazione forzata solo dopo aver eseguito la migrazione di tutti i tuoi client a un SDK che supporta reCAPTCHA.

Importante: non modificare o eliminare le chiavi reCAPTCHA denominate "Key for Identity Platform integration with reCAPTCHA" a meno che reCAPTCHA non sia disabilitato. Questo impedisce a Identity Platform di applicare la protezione reCAPTCHA. Inoltre, gli SDK Identity Platform non possono generare token dalle chiavi reCAPTCHA generate autonomamente.

Per abilitare reCAPTCHA, segui questi passaggi:

1. Se non lo hai già fatto, abilita l'API reCAPTCHA nel tuo progetto.

2. Abilita l'integrazione di Identity Platform con reCAPTCHA per un progetto utilizzando l'SDK Admin. Il supporto di reCAPTCHA è disponibile nell'SDK Admin di Node.js versione 11.7.0 e successive.

   Ad esempio:

   // Get project config
   const getProjectConfig = () => {
     getAuth().projectConfigManager().getProjectConfig()
     .then((response) => {
       console.log('Project reCAPTCHA config: ', response.recaptchaConfig);
     }).catch((error) => {
       console.log('Error getting project config:', error);
     });
   }
   
   // Update project config with reCAPTCHA config
   const updateConfigRequest = {
     recaptchaConfig: {
       emailPasswordEnforcementState:  'AUDIT',
       managedRules: [{
         endScore: 0.3,
         action: 'BLOCK'
       }]
     }
   };
   const updateProjectConfigWithRecaptcha = () => {
     getAuth().projectConfigManager().updateProjectConfig(updateConfigRequest).then((response) => {
       console.log('Updated reCAPTCHA config for project: ', response.recaptchaConfig);
     }).catch((error) => {
       console.log('Error updating project config:', error);
     });
   }
   

3. Abilita l'integrazione di Identity Platform con reCAPTCHA per un tenant utilizzando l'SDK Admin. Ad esempio:

   // Update tenant with reCAPTCHA config
   const updateTenantRequest = {
     recaptchaConfig: {
       emailPasswordEnforcementState:  'AUDIT',
       managedRules: [{
         endScore: 0.3,
         action: 'BLOCK'
       }]
     }
   };
   const updateTenantWithRecaptchaConfig = () => {
     getAuth().tenantManager().updateTenant("TENANT_ID", updateTenantRequest)
     .then((response) => {
       console.log('Updated reCAPTCHA config for tenant: ', response.recaptchaConfig);
     }).catch((error) => {
       console.log('Error updating the tenant:', error);
     });
   }
   

   Sostituisci quanto segue:

   • TENANT_ID: ID tenant
   Nota: Identity Platform non supporta l'architettura multi-tenancy con reCAPTCHA sulle piattaforme mobile.

4. Se utilizzi Identity Platform su piattaforme Apple o Android, devi registrare l'app dalla console di Firebase:

   • Per le piattaforme Apple, registra ogni ID pacchetto che utilizza Identity Platform
   • Per Android, registra ogni nome di pacchetto Android che utilizza Identity Platform

5. Se utilizzi Identity Platform sul web, devi aggiungere un dominio autorizzato per ogni dominio che utilizza reCAPTCHA. Per aggiungere domini autorizzati:

   1. Nella console Google Cloud, vai alla pagina Identity Platform.

      Vai a Identity Platform

   2. Vai a Impostazioni > Sicurezza.

   3. Fai clic su Aggiungi dominio.

   4. Inserisci il nome del dominio e fai clic su Aggiungi per salvare il dominio.

   Il completamento del provisioning delle chiavi del sito può richiedere diversi minuti. Per assicurarti che i flussi siano protetti, controlla le metrics.

Configura l'SDK client

Configura l'SDK client in base alla piattaforma della tua app.

Web

1. Esegui l'aggiornamento all'ultima versione dell'SDK web. Il supporto di reCAPTCHA è disponibile sull'SDK JavaScript versione 9.20.0 e successive. Dopo aver integrato l'SDK web con la tua app, l'SDK recupera automaticamente la configurazione reCAPTCHA e protegge i provider che hai configurato.

2. Per ridurre il numero di chiamate di rete effettuate dall'SDK e migliorare la raccolta degli indicatori reCAPTCHA, ti consigliamo di configurarlo esplicitamente come segue:

   import { initializeRecaptchaConfig } from '@firebase/auth';
   
   // Initialize Firebase Auth
   const auth = getAuth();
   initializeRecaptchaConfig(auth)
     .then(() => {
       console.log("Recaptcha Enterprise Config Initialization successful.")
     })
     .catch((error) => {
       console.error("Recaptcha Enterprise Config Initialization failed with " + error)
     });
   

Android

1. Esegui l'aggiornamento all'SDK per Android versione 31.5.0 o successive. Il supporto di reCAPTCHA richiede il livello API 19 (KitKat) o versioni successive e Android 4.4 o versioni successive. Dopo aver integrato l'SDK Android nella tua app, l'SDK recupera automaticamente la configurazione reCAPTCHA e protegge i provider che hai configurato.

2. Aggiungi la seguente regola di build alla sezione delle dipendenze del file build.gradle a livello di app:

   implementation 'com.google.android.recaptcha:recaptcha:18.4.0'
   

   Assicurati di utilizzare l'SDK reCAPTCHA versione 18.4.0 o successive.

3. Per ridurre il numero di chiamate di rete effettuate dall'SDK e rendere più efficace la raccolta degli indicatori reCAPTCHA, ti consigliamo di configurarla in modo esplicito come segue:

   • Kotlin:

   // Initialize Firebase Auth
   auth = Firebase.auth
   
   auth.initializeRecaptchaConfig().addOnCompleteListener(this) { task ->
       if (task.isSuccessful) {
           Log.d(TAG, "Recaptcha Enterprise Initialization successful.")
       } else {
           Log.w(TAG, "Recaptcha Enterprise Initialization failed.")
       }
   }
   

   • Java:

   // Initialize Firebase Auth
   auth = FirebaseAuth.getInstance();
   auth.initializeRecaptchaConfig().addOnCompleteListener(
     this, new OnCompleteListener<void>() {
     @Override
     public void onComplete(@NonNull Task<void> task) {
       if (task.isSuccessful()) {
         Log.d(TAG, "Recaptcha Enterprise Initialization successful.");
       } else {
         Log.w(TAG, "Recaptcha Enterprise Initialization failed.");
       }
     }
   });
   

iOS

1. Esegui l'aggiornamento all'SDK per iOS versione 10.14.0 o successive. Dopo aver integrato l'SDK per iOS nella tua app, l'SDK recupera automaticamente la configurazione reCAPTCHA e protegge i provider che hai configurato.

2. Per integrare l'SDK reCAPTCHA per iOS nella tua app, vedi Preparare l'ambiente.

3. Assicurati che -ObjC sia elencato nei flag del linker. Vai a Target > Impostazioni build > Tutte > Collegamento e verifica che Other Linker Flags mostri -ObjC.

4. Per ridurre il numero di chiamate di rete effettuate dall'SDK e rendere più efficace la raccolta degli indicatori reCAPTCHA, ti consigliamo di configurarla in modo esplicito come segue:

   • SWIFT:

   // Initialize Firebase Auth
   try await Auth.auth().initializeRecaptchaConfig()
   

   • Obiettivo-C:

   // Initialize Firebase Auth
   [[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) {
     // Firebase Auth initialization finished
   }];
   

Metriche reCAPTCHA

Dopo aver abilitato reCAPTCHA, monitora le metriche reCAPTCHA emesse dal tuo progetto per assicurarti che i flussi di autenticazione siano protetti. Se il provisioning della chiave di sito reCAPTCHA non va a buon fine o se non sono stati creati gli account di servizio richiesti, l'autenticazione reCAPTCHA non si apre.

Assicurati che l'autenticazione reCAPTCHA funzioni esaminando le seguenti metriche inviate dal progetto a Cloud Monitoring:

identitytoolkit.googleapis.com/recaptcha/verdict_count

Tiene traccia dei diversi esiti restituiti da reCAPTCHA. Se è presente un token, viene generato un esito. Puoi filtrare in base ai seguenti esiti:

• PASSED: indica che una determinata richiesta è consentita quando è attiva l'applicazione forzata.
• FAILED_AUDIT: indica che una determinata richiesta viene rifiutata quando è abilitata la modalità di controllo reCAPTCHA.
• FAILED_ENFORCE: indica che una determinata richiesta viene rifiutata quando è abilitata la modalità di applicazione di reCAPTCHA.
• CLIENT_TYPE_MISSING: indica che per una determinata richiesta manca un tipo di client quando è abilitata l'applicazione forzata di reCAPTCHA. In genere questo si verifica se una richiesta è stata inviata utilizzando una versione obsoleta dell'SDK del client che non supporta il reCAPTCHA.
• KEYS_MISSING: indica che una determinata richiesta non può essere verificata a causa dell'impossibilità di recuperare o generare chiavi reCAPTCHA valide quando è abilitata l'applicazione di reCAPTCHA.

Per modificare gli intervalli di punteggi e cambiare il rapporto tra esiti positivi e non superati, consulta Abilitare reCAPTCHA Enterprise.

identitytoolkit.googleapis.com/recaptcha/token_count

Tiene traccia del numero e dello stato dei token reCAPTCHA ricevuti dal backend di Identity Platform. Puoi applicare un filtro in base ai seguenti stati:

• VALID: indica che il token reCAPTCHA trasmesso è valido.
• EXPIRED: indica che il token reCAPTCHA trasmesso è scaduto. Un token scaduto potrebbe indicare problemi o comportamenti illeciti di rete del client.
• DUPLICATE: indica che il token reCAPTCHA trasmesso è un duplicato. Un token duplicato potrebbe indicare problemi o comportamenti illeciti di rete del client.
• INVALID: indica che il token reCAPTCHA trasmesso non è valido. Un token non valido potrebbe indicare un abuso.
• MISSING: indica che il token reCAPTCHA non esiste nella richiesta specificata. I token mancanti potrebbero indicare un'app client obsoleta.
• UNCHECKED: indica che il token reCAPTCHA non è stato controllato a causa di esiti CLIENT_TYPE_MISSING o KEYS_MISSING.

Se la tua app è stata implementata correttamente per gli utenti, vedrai traffico con token validi. Il numero di token validi è probabilmente proporzionale al numero di utenti che utilizzano l'app aggiornata.

identitytoolkit.googleapis.com/recaptcha/risk_scores

Tiene traccia della distribuzione del punteggio reCAPTCHA. Questo può aiutarti a definire gli intervalli di punteggi ottimali per la tua configurazione.

Utilizza queste metriche per determinare se puoi abilitare l'applicazione forzata. Prima di attivare l'applicazione, considera quanto segue:

• Se la maggior parte delle richieste recenti ha token validi e il rapporto tra PASSED e risultati FAILED_AUDIT o FAILED_ENFORCE è accettabile per il tuo caso aziendale, valuta la possibilità di attivare l'applicazione forzata.
• Se la maggior parte delle richieste recenti proviene probabilmente da client obsoleti, ti consigliamo di attendere che un maggior numero di utenti aggiorni l'app prima di abilitare l'applicazione forzata. L'applicazione dell'integrazione di Identity Platform con reCAPTCHA interrompe le versioni precedenti dell'app che non sono integrate con reCAPTCHA.

Per visualizzare queste metriche:

1. Nella console Google Cloud, vai alla pagina Esplora metriche.

   Vai a Esplora metriche

2. In Seleziona una metrica, inserisci Identity Toolkit Tenant. Se utilizzi la multitenancy, puoi visualizzare le metriche per ogni tenant, così come il progetto padre, lasciando vuoto il campo tenant_name.

Abilita applicazione forzata

Dopo aver verificato che la tua app riceve traffico di utenti accettabile, puoi attivare l'applicazione forzata di reCAPTCHA per proteggere i tuoi utenti. Assicurati di non interrompere gli utenti esistenti, inclusi quelli che potrebbero utilizzare una versione precedente della tua app.

Per abilitare l'applicazione forzata di reCAPTCHA per un progetto o un tenant, utilizza l'SDK di amministrazione per eseguire quanto segue:

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE',
    managedRules: [{
      endScore: 0.3,
      action: 'BLOCK'
    }]
  }
};

Disabilita reCAPTCHA

Per disattivare reCAPTCHA, utilizza l'SDK Admin per eseguire questo comando:

const disableRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'OFF',
  }
};

Override degli esiti reCAPTCHA con Cloud Functions

Oltre a configurare soglie di punteggio, puoi eseguire l'override di un esito reCAPTCHA per un determinato token utilizzando una funzione di blocco di Cloud Functions personalizzata. Ciò è utile nei casi in cui il punteggio reCAPTCHA per un determinato accesso utente potrebbe essere basso, ma l'utente è attendibile o è stato verificato tramite altri metodi e può quindi completare l'accesso.

Per saperne di più sulla configurazione delle funzioni di blocco con reCAPTCHA, consulta Estendi Firebase Authentication con il blocco di Cloud Functions.

Risoluzione dei problemi

Gli utenti non riescono ad accedere, registrarsi o reimpostare la password

Gli utenti potrebbero utilizzare una versione obsoleta dell'app. Se non hai fornito una versione aggiornata dell'app che utilizza l'SDK client, disattiva immediatamente la modalità di applicazione forzata. In caso contrario, chiedi agli utenti di aggiornare la loro app.

In alternativa, gli utenti potrebbero essere bloccati in base alla tua configurazione attuale. Prova a procedere come segue:

• Valuta una configurazione più permissiva modificando i punteggi chiave reCAPTCHA.
• Chiedi all'utente di provare con un altro dispositivo, browser o rete.
• Ripristina la modalità di controllo e monitora le metriche prima di riattivare la modalità di applicazione forzata.