Abilita reCAPTCHA SMS defense per l'autenticazione basata su SMS

Questo documento spiega come utilizzare reCAPTCHA SMS defense per proteggere i flussi basati su SMS di Identity Platform, come l'autenticazione a più fattori e tramite telefono, dalla frode tariffaria SMS (nota anche come attacco di tipo SMS pumping). Questa integrazione aiuta a impedire che il traffico SMS non autorizzato influisca negativamente sui tuoi utenti e sulle tue risorse.

Panoramica

Se la tua app si basa sugli SMS per l'autenticazione, ti consigliamo di abilitare l'integrazione di reCAPTCHA SMS defense. Una volta attivata, Firebase Authentication e Identity Platform richiamano automaticamente la funzionalità di protezione SMS reCAPTCHA ogni volta che un utente finale richiede un messaggio SMS di verifica dalla tua app o dal tuo sito utilizzando le seguenti operazioni phoneProvider:

reCAPTCHA fornisce quindi a Firebase Authentication o Identity Platform un punteggio di rischio che indica la probabilità di frode tariffaria SMS per il numero di telefono dell'utente. Questo punteggio viene quindi confrontato con la soglia configurata. Se il punteggio di rischio supera questa soglia, il messaggio SMS non viene inviato, bloccando di fatto i tentativi fraudolenti.

Per capire come funzionano i punteggi di reCAPTCHA SMS defense, consulta la sezione Interpretare i punteggi.

Per saperne di più sulla funzionalità di difesa dagli SMS di reCAPTCHA, vedi Rilevare e prevenire le frodi via SMS.

Modalità di applicazione forzata dell'autenticazione telefonica reCAPTCHA

Puoi configurare l'applicazione forzata dell'autenticazione telefonica per reCAPTCHA SMS defense in modo da utilizzare la modalità Controllo o Applicazione forzata.

Modalità di audit

Quando imposti l'applicazione forzata dell'autenticazione telefonica sulla modalità di controllo, Identity Platform utilizza la difesa SMS reCAPTCHA perverifica appp. Se la richiesta di un utente supera la valutazione della frode tariffaria, viene inviato un codice di verifica via SMS. Se la richiesta di un utente non supera la valutazione della frode tariffaria e utilizzi l'SDK client, Identity Platform attiva metodi di verifica di riserva per completare il flusso di autenticazione telefonica. I metodi di riserva accettati dipendono dalla piattaforma della tua app.

L'SDK client attiva i metodi di verifica di riserva negli scenari seguenti:

• Il token reCAPTCHA è mancante.
• Il token reCAPTCHA non è valido o è scaduto.
• Il token reCAPTCHA non supera la soglia del punteggio.
• reCAPTCHA non è configurato correttamente.

Assicurati che i metodi di verifica di riserva per la piattaforma della tua app siano configurati e pronti per essere attivati dall'SDK client, se necessario.

Modalità di applicazione forzata

Quando imposti l'applicazione forzata dell'autenticazione telefonica sulla modalità di applicazione forzata, Identity Platform utilizza la protezione SMS reCAPTCHA perverifica appp. Se la richiesta di un utente supera la valutazione della frode tariffaria, viene inviato un codice di verifica via SMS. Se la richiesta di un utente non supera la valutazione della frode tariffaria, Identity Platform blocca la richiesta e non invia un messaggio SMS contenente un codice di verifica.

In modalità di applicazione forzata non è richiesta alcuna verifica di riserva, quindi non devi configurare metodi di verifica aggiuntivi per la tua app. Tuttavia, ti consigliamo di configurare il programma di verifica reCAPTCHA per le app web per assicurarti che reCAPTCHA v2 sia abilitato se decidi di impostare la modalità reCAPTCHA della tua app su AUDIT o OFF.

Prima di iniziare

Prima di abilitare reCAPTCHA SMS defense per Identity Platform, completa le seguenti attività:

• Configura quanto segue per la tua app o il tuo sito, a seconda dei casi:

  • Accesso con il telefono per gli utenti.
  • Autenticazione a più fattori per la tua app web, Android o iOS.

• Configura Firebase Authentication per la tua app o il tuo sito, a seconda dei casi:

  • Web: Configurazione dell'autenticazione tramite telefono
  • iOS:configurazione dell'autenticazione tramite telefono
  • Android: configurazione dell'autenticazione tramite smartphone

Abilitare reCAPTCHA SMS defense

1. Configura l'autenticazione:

   1. In the Google Cloud console, activate Cloud Shell.

      Activate Cloud Shell

   2. Crea un'identità del servizio:

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

      Sostituisci PROJECT_ID con l'ID del progetto.

   3. Concedi il ruolo roles/identitytoolkit.serviceAgent all'identità di servizio che hai creato.

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-identitytoolkit.iam.gserviceaccount.com \
       --role=roles/identitytoolkit.serviceAgent
   

   Sostituisci quanto segue:

   • PROJECT_ID: l'ID progetto
   • PROJECT_NUMBER: il numero di conto del progetto

2. Abilita l'API reCAPTCHA Enterprise nel tuo progetto.

3. Abilita reCAPTCHA SMS defense per il tuo progetto:

   1. Nella console Google Cloud , vai alla pagina reCAPTCHA.

      Vai a reCAPTCHA

   2. Verifica che il nome del tuo progetto venga visualizzato nel selettore di risorse.

      Se non vedi il nome del tuo progetto, fai clic sul selettore di risorse e poi seleziona il tuo progetto.

   3. Fai clic su settingsImpostazioni.

   4. Nel riquadro Protezione SMS, fai clic su Configura.

   5. Fai clic sul pulsante di attivazione/disattivazione Attiva e poi su Salva.

   Quando abiliti reCAPTCHA SMS defense, viene abilitato anche Account defender, se non lo è già.

   Potrebbero essere necessari alcuni minuti prima che l'abilitazione di reCAPTCHA SMS defense venga propagata ai nostri sistemi. Una volta propagate, inizierai a ricevere risposte relative a reCAPTCHA SMS defense nell'ambito dei test.

4. Per configurare le impostazioni di reCAPTCHA SMS defense per un progetto Firebase Authentication o Identity Platform:

   1. Nel seguente URL, sostituisci PROJECT_ID, Recaptcha_MODE e START_SCORE:

      https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig?apix_params={"name":"projects/PROJECT_ID/config","updateMask":"recaptchaConfig","resource":{"recaptchaConfig":{"emailPasswordEnforcementState":"OFF","phoneEnforcementState":"Recaptcha_MODE","useSmsTollFraudProtection":true,"tollFraudManagedRules":[{"action":"BLOCK","startScore":START_SCORE}]}}}
      

      • PROJECT_ID: l'identificatore del progetto con Identity Platform abilitato.

      • Recaptcha_MODE: la modalità che vuoi impostare per l'applicazione forzata dell'autenticazione telefonica reCAPTCHA. I valori validi sono OFF, AUDIT e ENFORCE. Per abilitare reCAPTCHA SMS defense, questo parametro deve essere impostato su AUDIT o ENFORCE e useSmsTollFraudProtection deve essere impostato su true.

        Quando abiliti reCAPTCHA SMS defense per la prima volta, utilizza la modalità AUDIT per assicurarti che la configurazione di reCAPTCHA SMS defense funzioni correttamente. La modalità AUDIT è esclusivamente a scopo di verifica. Questa modalità non impedisce il traffico SMS non autorizzato. Verifica che non vengano visualizzati errori nel dashboard Metriche. Dopo la verifica, attiva immediatamente la modalità ENFORCE. Per ulteriori informazioni sul funzionamento delle modalità, consulta Modalità di applicazione dell'autenticazione telefonica reCAPTCHA.

      • START_SCORE: il punteggio di valutazione della frode tariffaria più alto che una richiesta può avere prima di non riuscire. Puoi impostare questo punteggio tra 0.1 e 0.9. Ti consigliamo di iniziare con una soglia più alta, ad esempio 0.8, e poi abbassare gradualmente il punteggio. I punteggi superiori alla soglia che hai impostato vengono trattati come frode via SMS. Se imposti un punteggio pari a 1,0, la protezione antifrode viene disattivata, mentre se imposti un punteggio pari a 0,0, tutti i messaggi SMS vengono bloccati. Più basso è il punteggio impostato, più rigide sono le regole. Se imposti una soglia di 0.3, ad esempio, reCAPTCHA non riesce a gestire qualsiasi richiesta con un punteggio pari o superiore a 0.4.

   2. Inserisci l'URL in una nuova finestra del browser in cui hai eseguito l'accesso alla console. Google Cloud

1. Se utilizzi Identity Platform sul web o su Android, registra la tua app dalla Console Firebase:

   • Per Android, registra ogni nome pacchetto Android che utilizza Identity Platform.

   • Per il web, aggiungi un dominio autorizzato per ogni dominio che utilizza reCAPTCHA:

     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 provisioning della chiave reCAPTCHA può richiedere diversi minuti.

2. Verifica la configurazione:

   • Recupera i dettagli di configurazione di reCAPTCHA:

     {replace-your-project} con il tuo projectId o projectNumber. Esegui l'API GetConfig nel riquadro laterale per recuperare la configurazione di reCAPTCHA.

   • Verifica che reCAPTCHA SMS defense sia configurato correttamente:

     1. Se la configurazione di reCAPTCHA è impostata correttamente, la risposta deve contenere i seguenti campi con i valori specificati:

        • recaptchaKeys: Il campo non deve essere vuoto e deve essere configurato per almeno una di queste piattaforme: iOS, web o Android.
        • useSmsTollFraudProtection: il valore di questo campo deve essere impostato su true.
        • phoneEnforcementState: il valore deve essere impostato su ENFORCE o AUDIT.
        • tollFraudManagedRules: all'interno di questo campo, startScore deve essere configurato con la soglia scelta, che deve essere un valore compreso tra 0 e 0,9.

        In caso contrario, configura di nuovo reCAPTCHA SMS defense.

        Esempio di risposta

          {
            "recaptchaConfig": {
                "recaptchaKeys": [
                  {
                    "key": "projects/{your-project}/keys/{recaptcha-key}",
                    "type": "WEB"
                  },
                  {
                    "type": "IOS"
                  },
                  {
                    "type": "ANDROID"
                  }
                ],
                "phoneEnforcementState": "ENFORCE",
                "tollFraudManagedRules": [
                  {
                    "startScore": 0.8,
                    "action": "BLOCK"
                  }
                ],
                "useSmsTollFraudProtection": true
            }
          }
          ```
        

3. Assicurati che le versioni dell'SDK siano corrette.

   Web

   Esegui l'aggiornamento alla versione più recente dell'SDK web.

   • Il supporto di reCAPTCHA per l'autenticazione tramite email e password nelle app web è disponibile nelle versioni 9.20.0 e successive dell'SDK JavaScript.
   • Il supporto di reCAPTCHA per l'autenticazione telefonica nelle app web è disponibile nelle versioni 11 e successive dell'SDK JavaScript.

   Dopo aver integrato l'SDK web con la tua app, l'SDK recupera automaticamente la configurazione di reCAPTCHA e attiva la protezione per i provider che hai configurato.

   Android

   1. Esegui l'aggiornamento all'ultima versione dell'SDK Android. Il supporto di reCAPTCHA per l'autenticazione tramite email e password e l'autenticazione tramite telefono nelle app per Android è disponibile nell'SDK Android versione 23.1.0 e successive.

      Inoltre, il supporto di reCAPTCHA richiede il livello API 23 (Marshmallow) o versioni successive e Android 6 o versioni successive.

      Dopo aver integrato l'SDK Android con la tua app, l'SDK recupera automaticamente la configurazione di reCAPTCHA e applica le soglie impostate per i provider che hai configurato.

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

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

      Assicurati di utilizzare la versione 18.5.1 o successive dell'SDK reCAPTCHA.

   iOS

   1. Esegui l'aggiornamento all'SDK per iOS versione 11.6.0 o successive.

   Dopo aver integrato l'SDK per iOS nella tua app, l'SDK recupera automaticamente la configurazione di reCAPTCHA e applica le soglie impostate per i provider che hai configurato.

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

   2. Per verificare che -ObjC sia elencato nei flag del linker, vai a Target > Impostazioni di build > Tutto > Collegamento e verifica che Other Linker Flags mostri -ObjC.

Monitorare le metriche reCAPTCHA per reCAPTCHA SMS defense

Monitora le metriche reCAPTCHA emesse dal tuo progetto per verificare che i flussi di autenticazione basati su SMS siano protetti. Ad esempio, queste metriche possono aiutarti a determinare se hai configurato correttamente l'integrazione di Identity Platform con l'API reCAPTCHA Enterprise. Possono anche aiutarti a perfezionare la soglia del punteggio per il traffico degli utenti.

Verifica che la funzionalità reCAPTCHA SMS defense funzioni controllando le seguenti metriche che il tuo progetto emette in Cloud Monitoring:

• identitytoolkit.googleapis.com/recaptcha/verdict_count
• identitytoolkit.googleapis.com/recaptcha/token_count
• identitytoolkit.googleapis.com/recaptcha/sms_tf_risk_scores

Per ulteriori informazioni, consulta Monitorare le metriche reCAPTCHA.

Applica reCAPTCHA SMS defense

Dopo aver verificato che la tua app riceve traffico utente accettabile, attiva la modalità ENFORCE di reCAPTCHA per bloccare attivamente le richieste fraudolente e proteggere gli utenti.

Per attivare la modalità ENFORCE per i flussi di autenticazione basati su SMS in un progetto o tenant, utilizza Google APIs Explorer per aggiornare la configurazione del progetto inserendo il seguente URL HTTP in una nuova finestra del browser in cui hai eseguito l'accesso alla Google Cloud console:

   https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig?apix_params={"name":"projects/PROJECT_ID/config","updateMask":"recaptchaConfig","resource":{"recaptchaConfig":{"phoneEnforcementState":"ENFORCE","useSmsTollFraudProtection":"true"}}}

Sostituisci PROJECT_ID con l'ID progetto.

Utilizzare reCAPTCHA SMS defense con la protezione dai bot

È possibile utilizzare reCAPTCHA SMS defense contemporaneamente alla protezione dai bot. Per le configurazioni che utilizzano entrambe le funzionalità di protezione, considera quanto segue:

• Quando imposti lo stato di applicazione forzata dell'autenticazione telefonica su AUDIT, Identity Platform trasmette una richiesta quando soddisfa almeno uno dei controlli. Ti consigliamo di monitorare le metriche reCAPTCHA per verificare che sia la protezione SMS reCAPTCHA sia la protezione da bot siano configurate con impostazioni di punteggio ragionevoli.
• Quando lo stato di applicazione forzata dell'autenticazione telefonica è impostato su ENFORCE, Identity Platform approva una richiesta solo quando soddisfa entrambe le valutazioni e la richiesta non riesce senza ricorrere a un altro metodo di verifica.

Per attivare entrambe le funzionalità, utilizza Google APIs Explorer per aggiornare la configurazione del progetto:

        recaptchaConfig: {
          phoneEnforcementState:  'ENFORCE_MODE',
          useSmsTollFraudProtection: true,
          useSmsBotScore: true
        }

Sostituisci ENFORCE_MODE con la modalità che vuoi impostare per l'applicazione forzata dell'autenticazione telefonica reCAPTCHA. I valori validi sono OFF, AUDIT e ENFORCE. Quando attivi la protezione SMS reCAPTCHA per la prima volta, ti consigliamo di impostare questo parametro su AUDIT e di assicurarti che i flussi di autenticazione siano protetti prima di impostarlo su ENFORCE. Per ulteriori informazioni sul funzionamento delle modalità, consulta Modalità di applicazione forzata dell'autenticazione telefonica reCAPTCHA.

Disattivare reCAPTCHA SMS defense durante l'utilizzo della protezione dai bot

Se utilizzi contemporaneamente reCAPTCHA SMS defense e la protezione dai bot e vuoi disattivare reCAPTCHA SMS defense senza disattivare la protezione dai bot, utilizza Google APIs Explorer per aggiornare la configurazione del progetto:

    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: 'false',
      useSmsBotScore: 'true'
    }

Sostituisci ENFORCE_MODE con la modalità che hai impostato in precedenza per l'applicazione forzata dell'autenticazione telefonica reCAPTCHA. Questo valore deve essere AUDIT o ENFORCE. Per ulteriori informazioni sul funzionamento delle modalità, consulta Modalità di applicazione forzata dell'autenticazione telefonica reCAPTCHA.

Disattiva reCAPTCHA SMS defense

Per disattivare la protezione SMS reCAPTCHA, utilizza Google APIs Explorer per aggiornare la configurazione del progetto inserendo il seguente URL HTTP in una nuova finestra del browser in cui hai eseguito l'accesso alla console Google Cloud :

   https://cloud.google.com/identity-platform/docs/reference/rest/v2/projects/updateConfig?apix_params={"name":"projects/PROJECT_ID/config","updateMask":"recaptchaConfig","resource":{"recaptchaConfig":{"phoneEnforcementState":"OFF","useSmsTollFraudProtection":"false"}}}

Sostituisci PROJECT_ID con l'ID progetto.

Per disattivare reCAPTCHA SMS defense mentre utilizzi la protezione da bot, consulta Disattivare reCAPTCHA SMS defense durante l'utilizzo della protezione da bot.

Passaggi successivi

• Scopri di più sulla funzionalità di difesa SMS di reCAPTCHA.