Abilita reCAPTCHA Enterprise

Questo documento mostra come utilizzare l'integrazione di Identity Platform con reCAPTCHA Enterprise 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 Enterprise crea una valutazione reCAPTCHA Enterprise per tuo conto per convalidare le richieste degli utenti. Per informazioni sui prezzi, consulta i prezzi di reCAPTCHA Enterprise.

Importante: questa funzionalità supporta solo gli accessi e le registrazioni tramite email e password, la reimpostazione delle password e gli accessi tramite link via email. Se un utente legittimo è bloccato, consulta la sezione Risoluzione dei problemi per conoscere i passaggi per risolvere il problema.

Panoramica

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

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

reCAPTCHA fornisce 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 account di servizio

Prima di abilitare reCAPTCHA Enterprise, devi creare un account di servizio per ogni progetto che utilizzerà reCAPTCHA e concedere a ogni account di servizio l'accesso a reCAPTCHA Enterprise. Ciò consente a Identity Platform di gestire le chiavi reCAPTCHA per tuo conto.

Per creare un account di servizio, segui questi passaggi:

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 Enterprise:

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

   Sostituisci quanto segue:

   • PROJECT_ID: l'ID progetto
   • PROJECT_NUMBER: il numero dell'account del progetto

Abilita reCAPTCHA Enterprise

reCAPTCHA offre due modalità che ti consentono di proteggere gli utenti:

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

Importante: non modificare o eliminare le chiavi reCAPTCHA Enterprise denominate "Key for Identity Platform Integration with reCAPTCHA Enterprise" a meno che reCAPTCHA non sia disattivato. In questo modo, Identity Platform non potrà applicare la protezione reCAPTCHA. Inoltre, gli SDK Identity Platform non possono generare token da chiavi reCAPTCHA generate autonomamente.

Per abilitare reCAPTCHA Enterprise, segui questi passaggi:

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

2. Abilita l'integrazione di Identity Platform con reCAPTCHA Enterprise per un progetto utilizzando l'SDK amministrativo. L'assistenza di reCAPTCHA Enterprise è disponibile su 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 Enterprise 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: l'ID tenant
   Nota: Identity Platform non supporta la multitenancy con reCAPTCHA Enterprise sulle piattaforme mobile.

4. Se utilizzi Identity Platform su piattaforme Apple o Android, devi registrare 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 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 della chiave di 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 alla versione più recente dell'SDK web. Il supporto di reCAPTCHA Enterprise è disponibile su SDK JavaScript 9.20.0 e versioni successive. Dopo aver integrato l'SDK web con la tua app, questa recupera automaticamente la configurazione di reCAPTCHA Enterprise e protegge i provider che hai configurato.

2. Per ridurre il numero di chiamate di rete effettuate dall'SDK e migliorare la raccolta di indicatori reCAPTCHA, ti consigliamo di configurarlo in modo esplicito 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 Enterprise richiede l'API 19 (Kit) o versioni successive e Android 4.4 o versioni successive. Dopo aver integrato l'SDK Android nella tua app, questa recupera automaticamente la configurazione di reCAPTCHA Enterprise 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 per rendere più efficace la raccolta di indicatori reCAPTCHA, ti consigliamo di configurarla esplicitamente nel seguente modo:

   • 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 l'integrazione dell'SDK per iOS nell'app, questa recupera automaticamente la configurazione di reCAPTCHA Enterprise e protegge i provider che hai configurato.

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

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

4. Per ridurre il numero di chiamate di rete effettuate dall'SDK e per rendere più efficace la raccolta di indicatori reCAPTCHA, ti consigliamo di configurarla esplicitamente nel seguente modo:

   • 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 di reCAPTCHA Enterprise

Dopo aver abilitato reCAPTCHA Enterprise, monitora le metriche reCAPTCHA inviate 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 gli account di servizio richiesti non sono stati creati, l'autenticazione reCAPTCHA non si apre.

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

identitytoolkit.googleapis.com/recaptcha/verdict_count

Monitora i diversi esiti restituiti da reCAPTCHA Enterprise. Se è presente un token, viene generato un esito. Puoi filtrare i seguenti esiti:

• PASSED: indica che una determinata richiesta è consentita se è abilitata l'applicazione forzata.
• FAILED_AUDIT: indica che una determinata richiesta viene rifiutata quando è attiva la modalità di controllo reCAPTCHA.
• FAILED_ENFORCE: indica che una determinata richiesta viene rifiutata quando la modalità di applicazione reCAPTCHA è abilitata.
• CLIENT_TYPE_MISSING: indica che una determinata richiesta ha un tipo di client mancante quando è abilitata l'applicazione reCAPTCHA. In genere questo accade se una richiesta è stata inviata utilizzando una versione obsoleta dell'SDK 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 superati e non superati, consulta Abilitare reCAPTCHA Enterprise.

identitytoolkit.googleapis.com/recaptcha/token_count

Tiene traccia del numero e dello stato dei token reCAPTCHA Enterprise ricevuti dal backend di Identity Platform. Puoi filtrare 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 nella rete del client.
• DUPLICATE: indica che il token reCAPTCHA trasmesso è un duplicato. Un token duplicato potrebbe indicare problemi o comportamenti illeciti nella 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 l'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 la tua app aggiornata.

identitytoolkit.googleapis.com/recaptcha/risk_scores

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

Utilizza queste metriche per determinare se è possibile abilitare l'applicazione forzata. Prima di abilitare l'applicazione, tieni presente quanto segue:

• Se la maggior parte delle richieste recenti ha token validi e il rapporto di esiti PASSED-FAILED_AUDIT o FAILED_ENFORCE è accettabile per il tuo caso aziendale, valuta la possibilità di abilitare l'applicazione forzata.
• Se è probabile che la maggior parte delle richieste recenti provenga da client obsoleti, valuta la possibilità di attendere che altri utenti aggiornino la loro app prima di abilitare l'applicazione forzata. L'applicazione dell'integrazione di Identity Platform con reCAPTCHA Enterprise provoca l'interruzione delle versioni precedenti dell'app che non sono integrate con reCAPTCHA Enterprise.

Per visualizzare queste metriche:

1. Nella console Google Cloud, vai alla pagina Metrics Explorer.

   Vai a Metrics Explorer

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

Abilita applicazione

Dopo aver verificato che la tua app riceva traffico utente accettabile, puoi abilitare 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 tenant, utilizza l'SDK di amministrazione per eseguire quanto segue:

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

Disattiva reCAPTCHA Enterprise

Per disabilitare reCAPTCHA Enterprise, utilizza l'SDK di amministrazione per eseguire quanto segue:

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

Override degli esiti di reCAPTCHA Enterprise con Cloud Functions

Oltre a configurare le soglie di punteggio, puoi eseguire l'override di un esito reCAPTCHA Enterprise per un determinato token utilizzando una funzione di blocco di Cloud Functions personalizzata. Questa operazione è 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 con altri mezzi e pertanto gli è consentito completare l'accesso.

Per saperne di più sulla configurazione delle funzioni di blocco con reCAPTCHA Enterprise, consulta Estensione dell'autenticazione Firebase 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 della tua app che utilizza l'SDK client, disattiva immediatamente la modalità di applicazione forzata. In caso contrario, chiedi ai tuoi utenti di aggiornare l'app.

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

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