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 a spam, abusi e altre attività fraudolente.

L'integrazione di Identity Platform con reCAPTCHA crea una valutazione 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 l'accesso tramite link via email. Se un utente legittimo viene bloccato, consulta la sezione Risoluzione dei problemi per conoscere la procedura di risoluzione.

Panoramica

Quando configuri l'integrazione di Identity Platform con reCAPTCHA, Identity Platform provvede a eseguire il provisioning delle chiavi di sito reCAPTCHA basate su punteggi nel tuo progetto per tuo conto. 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 gli indicatori di rischio che valutano il rischio della richiesta in base alla tua configurazione e alla tua tolleranza al rischio.

Per ulteriori informazioni, consulta la panoramica di reCAPTCHA Enterprise.

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

• reCAPTCHA Enterprise
• Identity Platform

Per generare una stima dei costi basata sull'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud potrebbero essere idonei per una prova gratuita.

Prima di iniziare

Configura l'accesso via email per gli utenti.

Crea un account di servizio

Prima di attivare reCAPTCHA, devi creare un account di servizio per ogni progetto che utilizzerà reCAPTCHA e concedere a ogni 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 dell'account del progetto

Abilita reCAPTCHA

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

• Controllo: se abilitato, Identity Platform crea nel progetto una o più chiavi reCAPTCHA che vengono utilizzate per valutare il traffico verso le API di 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 uno o più reCAPTCHA chiave del progetto utilizzate per valutare il traffico verso le API Identity Platform. Le richieste API che non includono un token reCAPTCHA vengono rifiutate. Abilita l'applicazione forzata solo dopo aver eseguito la migrazione di tutti i tuoi client a un SDK con Supporto reCAPTCHA.

Importante: non modificare o eliminare le chiavi reCAPTCHA denominate "Chiave per l'integrazione di Identity Platform con reCAPTCHA" se reCAPTCHA non è disabilitato. In questo modo, Identity Platform non potrà applicare la protezione reCAPTCHA. Inoltre, gli SDK di Identity Platform non possono generare token dalle chiavi reCAPTCHA che generi autonomamente.

Per attivare reCAPTCHA:

1. Se non l'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. reCAPTCHA Il supporto è disponibile per l'SDK Admin di Node.js 11.7.0 e versioni 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 per dispositivi mobili.

4. Se utilizzi Identity Platform su piattaforme Apple o Android, devi registrarti per la tua app dalla console 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 i 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 che i flussi siano protetti, controlla le metriche.

Configura l'SDK client

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

Web

1. Esegui l'aggiornamento alla versione più recente dell'SDK web. Il supporto di reCAPTCHA è disponibile nelle versioni dell'SDK JavaScript 9.20.0 e successive. Dopo aver integrato l'SDK web con la tua app, questo recupera automaticamente la configurazione di 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 alla versione 31.5.0 o successiva dell'SDK Android. 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 con la tua app, viene recuperata automaticamente la configurazione di reCAPTCHA e vengono protetti i provider che hai configurato.

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

   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 configurarlo esplicitamente 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 con la tua app, questo recupera automaticamente la configurazione di 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 di compilazione > Tutte > Collegamento e verifica che in Other Linker Flags venga visualizzato -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 configurarlo esplicitamente 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 attivato reCAPTCHA, monitora le metriche reCAPTCHA generate 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 va a buon fine.

Verifica che l'autenticazione reCAPTCHA funzioni esaminando le seguenti metriche emesse dal progetto in 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 giudizi:

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

Per modificare gli intervalli di punteggi in modo da cambiare il rapporto tra giudizi di passaggio e fallimento, consulta Abilitare reCAPTCHA Enterprise.

identitytoolkit.googleapis.com/recaptcha/token_count

Monitora il numero e lo stato dei token reCAPTCHA ricevuti dal backend di Identity Platform. Puoi filtrare in base ai seguenti stati:

• VALID: indica che il token reCAPTCHA passato è valido.
• EXPIRED: indica che il token reCAPTCHA trasmesso è scaduto. Un token scaduto potrebbe indicare problemi di rete del client o comportamenti illeciti.
• DUPLICATE: indica che il token reCAPTCHA trasmesso è un duplicati. Un token duplicato potrebbe indicare problemi o comportamenti illeciti di rete del client.
• INVALID: indica che il token reCAPTCHA passato 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 verificato a causa degli esiti CLIENT_TYPE_MISSING o KEYS_MISSING.

Se l'implementazione dell'app è andata a buon fine per gli utenti, vedrai il traffico con token validi. Il numero di token validi è probabilmente proporzionale al numero di utenti che utilizzano la tua app aggiornata.

identitytoolkit.googleapis.com/recaptcha/risk_scores

Monitora la distribuzione del punteggio reCAPTCHA. In questo modo puoi 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 contiene token validi e il rapporto è pari a PASSED a FAILED_AUDIT o FAILED_ENFORCE è accettabile per la tua attività in questo caso, valuta la possibilità di abilitare l'applicazione forzata.
• Se la maggior parte delle richieste recenti proviene probabilmente da client obsoleti, prendi in considerazione attendere che altri utenti aggiornino l'app prima di abilitare l'applicazione forzata. L'applicazione dell'integrazione di Identity Platform con reCAPTCHA interrompe le versioni precedenti dell'app non 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, nonché per il progetto principale, lasciando vuoto tenant_name.

Attivare l'applicazione

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

Per attivare l'applicazione 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'
    }]
  }
};

Disattivare reCAPTCHA

Per disattivare reCAPTCHA, utilizza l'SDK Admin per eseguire quanto segue:

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

Sostituzione dei giudizi di reCAPTCHA con le funzioni Cloud Run

Oltre a configurare le soglie di punteggio, puoi eseguire l'override del verdetto reCAPCHA per un determinato token utilizzando una funzione di blocco delle funzioni Cloud Run personalizzate. Questo è utile nei casi in cui il punteggio reCAPTCHA per l'accesso di un determinato utente potrebbe essere basso, ma l'utente è attendibile o è stato verificato tramite altri mezzi e quindi è autorizzato a completare l'accesso.

Per scoprire 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 l'app.

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

• Considera una configurazione più permissiva tramite le modifiche. Punteggi delle chiavi 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.