Questa pagina è stata tradotta dall'API Cloud Translation.

Attivare reCAPTCHA SMS defense per l'autenticazione basata su SMS

Questo documento spiega come utilizzare reCAPTCHA 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).

Panoramica

Se la tua app si basa su un flusso di autenticazione basato su SMS, puoi attivare l'integrazione di Firebase Authentication o Identity Platform con reCAPTCHA. Se abilitata, Firebase Authentication e Identity Platform invocano la funzionalità di difesa reCAPTCHA SMS quando un utente richiede un SMS di verifica dalla tua app o dal tuo sito utilizzando le seguenti operazioniphoneProvider:

Operazione	Metodo
Registrazione o accesso con numero di telefono	`sendVerificationCode`
Registrazione del numero di telefono per l'autenticazione a due fattori	`mfaSmsEnrollment`
Accesso con il numero di telefono per l'autenticazione a due fattori	`mfaSmsSignIn`

reCAPTCHA fornisce quindi a Firebase Authentication o Identity Platform un punteggio di rischio che indica la probabilità che il numero di telefono dell'utente commetta frodi tariffarie tramite SMS. Firebase Authentication e Identity Platform confrontano questo punteggio con la soglia impostata nella configurazione della difesa antifrode tariffaria SMS di reCAPTCHA e poi gestiscono la richiesta in base all'azione impostata nella configurazione.

Per ulteriori informazioni sulla funzionalità di difesa reCAPTCHA SMS, vedi Rilevare e prevenire le attività fraudolente via SMS.

Prima di iniziare

Prima di attivare 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.
- L'autenticazione a più fattori per la tua app web, Android o iOS.
Se non l'hai ancora fatto, crea un account di servizio per ogni progetto che utilizzerà reCAPTCHA. Per le istruzioni, vedi Creare un account di servizio.

Modalità di applicazione forzata dell'autenticazione telefonica reCAPTCHA

reCAPTCHA SMS defense richiede che tu abbia configurato l'applicazione forzata dell'autenticazione tramite telefono reCAPTCHA, che ha due modalità: controllo e applicazione forzata.

Modalità di controllo

Quando imposti l'applicazione dell'autenticazione tramite telefono in modalità di controllo, Identity Platform utilizza la difesa SMS reCAPTCHA per la verifica dell'app. Se la richiesta dell'utente supera la valutazione della frode tariffaria, Identity Platform invia un messaggio SMS contenente un codice di verifica al telefono dell'utente. Se una richiesta non supera la valutazione della frode per pedaggi e utilizzi l'SDK client, vengono attivati i metodi di verifica di riserva per completare il flusso di autenticazione telefonica. I metodi di riserva accettati dipendono dalla piattaforma dell'app.

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

Il token reCAPTCHA è mancante.
Il token reCAPTCHA non è valido o è scaduto.
Il token reCAPTCHA non supera la soglia di 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.

Web

Se la valutazione iniziale della frode relativa ai pedaggi non va a buon fine, la modalità di controllo si basa su reCAPTCHA 2.0 per la verifica. Pertanto, devi configurare il verificatore reCAPTCHA (RecaptchaVerifier) e passarlo alle seguenti operazioni di autenticazione dello smartphone:

verifyPhoneNumber
signInWithPhoneNumber
linkWithPhoneNumber
reauthenticateWithPhoneNumber

Senza il verificatore reCAPTCHA, Identity Platform non può avviare reCAPTCHA v2 e restituirà auth/argument-error. Per ulteriori informazioni sulla configurazione del verificatore reCAPTCHA, consulta Configurare il verificatore reCAPTCHA nella documentazione di Firebase.

Android

Se la valutazione iniziale della frode relativa ai pedaggi non va a buon fine, la modalità di controllo verifica la tua app in base all'API Play Integrity. Se questa verifica non va a buon fine, viene attivato reCAPTCHA v2. reCAPTCHA v2 potrebbe essere attivato nei seguenti scenari:

Se sul dispositivo dell'utente finale non sono installati Google Play Services.
Se l'app non è distribuita tramite il Google Play Store (su Authentication SDK v21.2.0 e versioni successive).
Se il token SafetyNet ottenuto non era valido (nelle versioni dell'SDK Authentication precedenti alla v21.2.0).

Per ulteriori informazioni sulla configurazione della verifica app per Android, consulta Attivare la verifica app nella documentazione di Firebase.

iOS

Se la valutazione iniziale della frode relativa ai pedaggi non va a buon fine, la modalità di controllo si basa su notifiche push silenziose per la verifica. Questo metodo di verifica prevede l'invio di un token alla tua app sul dispositivo richiedente tramite una notifica push silenziosa. Se l'app riceve correttamente la notifica, il flusso di autenticazione dello smartphone procede. Se la tua app non riceve la notifica push, viene attivato reCAPTCHA 2.0. reCAPTCHA v2 potrebbe essere attivato se le notifiche push silenziose non sono configurate correttamente.

Per ulteriori informazioni sulla configurazione della verifica delle app per iOS, consulta Attivare la verifica nella documentazione di Firebase.

Modalità di applicazione forzata

Quando imposti l'applicazione forzata dell'autenticazione telefonica, Identity Platform utilizza la difesa SMS reCAPTCHA per la verifica dell'app. Se la richiesta dell'utente supera la valutazione per i reati correlati ai pedaggi, Identity Platform invia un messaggio SMS contenente un codice di verifica al telefono dell'utente. Se la richiesta non supera la valutazione per la frode stradale, Identity Platform la blocca e non invia un messaggio SMS contenente un codice di verifica.

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

Attivare la difesa reCAPTCHA SMS

Per attivare reCAPTCHA SMS defense:

Se non l'hai ancora fatto, abilita l'API reCAPTCHA Enterprise nel tuo progetto.
Attiva reCAPTCHA SMS defense con reCAPTCHA. Per istruzioni, consulta la sezione Prima di iniziare della pagina Rileva e previeni le attività fraudolente tramite SMS nella documentazione di reCAPTCHA.
Per attivare reCAPTCHA SMS defense per un progetto, utilizza l'SDK Admin per chiamare updateConfig come segue:
```
  // Update the reCAPTCHA config to enable toll fraud protection
  const updateProjectConfigRequest = {
    recaptchaConfig: {
      phoneEnforcementState: 'ENFORCE_MODE',
      useSmsTollFraudProtection: 'true',
      tollFraudManagedRules: [{ startScore: START_SCORE,
        action: 'BLOCK' }],
    }
  }
  let projectConfig = await getAuth().projectConfigManager().updateProject(updateProjectConfigRequest);
```
Sostituisci quanto segue:
- ENFORCE_MODE: la modalità da impostare per l'applicazione forzata dell'autenticazione telefonica reCAPTCHA. I valori validi sono OFF, AUDIT e ENFORCE. Per attivare la difesa reCAPTCHA SMS, questo parametro deve essere impostato su AUDIT o ENFORCE e useSmsTollFraudProtection deve essere impostato su true.
  
  Quando attivi la difesa reCAPTCHA per gli SMS per la prima volta, consigliamo di impostare lo stato di applicazione su AUDIT e di assicurarti che i flussi di autenticazione siano protetti prima di impostarlo su ENFORCE. Per maggiori informazioni sul funzionamento delle modalità, consulta le modalità di applicazione forzata dell'autenticazione telefonica reCAPTCHA.
- START_SCORE: il punteggio più alto per la valutazione delle attività fraudolente relative ai pedaggi che una richiesta può avere prima di non riuscire. Puoi impostare questo punteggio tra 0.0 e 1.0. Qualsiasi punteggio superiore alla soglia impostata verrà considerato una frode tariffaria SMS. Ad esempio, se imposti una soglia di 0.3, reCAPTCHA non accetterà alcuna richiesta con un valore pari o superiore a 0.3.0.4 Pertanto, più basso è il punteggio impostato, più severe saranno le regole.
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. 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 di dominio e fai clic su Aggiungi per salvarlo.
Il provisioning della chiave reCAPTCHA può richiedere diversi minuti.
Se hai impostato l'applicazione in modalità di controllo, ti consigliamo di monitorare le metriche di reCAPTCHA per la difesa reCAPTCHA SMS per assicurarti che i tuoi flussi siano protetti.

Configura l'SDK client

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

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 dell'SDK JavaScript 9.20.0 e successive.
- 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 fornitori che hai configurato.

Se necessario, puoi forzare il recupero dell'indicatore reCAPTCHA come segue:

import { initializeRecaptchaConfig } from '@firebase/auth';

// Initialize Firebase Authentication
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

Esegui l'aggiornamento alla versione più recente dell'SDK Android. Il supporto di reCAPTCHA per l'autenticazione via email e password e l'autenticazione telefonica nelle app per Android è disponibile dalla versione 23.1.0 dell'SDK Android 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 attiva la protezione per i provider che hai configurato.
Aggiungi la seguente regola di compilazione alla sezione delle dipendenze del file build.gradle a 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.

Se necessario, puoi forzare il recupero dell'indicatore reCAPTCHA come segue:

Kotlin:

// Initialize Firebase Authentication
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 Authentication
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

Esegui l'aggiornamento alla versione 11.6.0 o successive dell'SDK per iOS. Dopo aver integrato l'SDK per iOS con la tua app, l'SDK recupera automaticamente la configurazione di reCAPTCHA e attiva la protezione per i fornitori che hai configurato.
Per integrare l'SDK reCAPTCHA per iOS nella tua app, consulta Preparare l'ambiente.
Assicurati che -ObjC sia elencato nei flag del linker. Vai a Destinazione > Impostazioni di compilazione > Tutte > Collegamento e verifica che in Other Linker Flags sia visualizzato -ObjC.

Se necessario, puoi forzare il recupero dell'indicatore reCAPTCHA come segue:

Swift:

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

Objective-C:

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

Monitorare le metriche di reCAPTCHA per la difesa reCAPTCHA SMS

Prima di impostare l'applicazione forzata di reCAPTCHA in modalità di applicazione, consigliamo di utilizzare la modalità di controllo e di monitorare le metriche di reCAPTCHA emesse dal progetto per assicurarti 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. Inoltre, possono aiutarti a perfezionare la soglia di punteggio per il traffico degli utenti.

Assicurati che la funzionalità reCAPTCHA SMS defense funzioni esaminando le seguenti metriche emesse dal tuo progetto in Cloud Monitoring:

Per ulteriori informazioni, consulta Monitorare le metriche di reCAPTCHA.

Applicare la difesa reCAPTCHA SMS

Dopo aver verificato che la tua app riceve traffico degli utenti accettabile, puoi attivare 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 i flussi di autenticazione basati su SMS in un progetto o un tenant, utilizza l'SDK Admin per eseguire il seguente comando:

  const enforceRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE',
      useSmsTollFraudProtection: 'true'
    }
  };

Disattivare la difesa reCAPTCHA SMS

Per disattivare la difesa reCAPTCHA SMS, utilizza l'SDK Amministrazione per eseguire il seguente comando:

  const disableRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'OFF',
      useSmsTollFraudProtection: 'false'
    }
  };

Per disattivare reCAPTCHA SMS defense mentre utilizzi la protezione dai bot, consulta Disattivare reCAPTCHA SMS defense mentre utilizzi la protezione dai bot.

Utilizzare reCAPTCHA SMS defense con la protezione dai bot

È possibile utilizzare reCAPTCHA SMS defense contemporaneamente alla protezione antibot. Per le configurazioni che utilizzano entrambe le funzionalità di protezione, tieni presente quanto segue:

Quando imposti lo stato di applicazione dell'autenticazione dello smartphone su controllo, Identity Platform passa una richiesta quando soddisfa almeno una delle valutazioni. Ti invitiamo a monitorare le metriche di reCAPTCHA per assicurarti che sia la difesa reCAPTCHA SMS sia la protezione antibot siano configurate con impostazioni di punteggio ragionevoli.
Quando imposti lo stato di applicazione dell'autenticazione dello smartphone su Enforce, Identity Platform passa una richiesta solo quando soddisfa entrambe le valutazioni e la richiesta di errore si chiude senza passare a un altro metodo di verifica.

Per attivare entrambe le funzionalità, utilizza SDK Admin per eseguire il seguente comando:

  const enableBothRequest = {
    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. Per attivare la difesa reCAPTCHA SMS, questo parametro deve essere impostato su AUDIT o ENFORCE. Quando attivi la difesa 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 la difesa reCAPTCHA SMS durante l'utilizzo della protezione dai bot

Se utilizzi contemporaneamente la difesa reCAPTCHA SMS e la protezione dai bot e vuoi disattivare la difesa reCAPTCHA SMS senza disattivare la protezione dai bot, utilizza l'SDK Admin per eseguire il seguente comando:

  const disableRequest = {
    recaptchaConfig: {
      phoneEnforcementState:  'ENFORCE_MODE',
      useSmsTollFraudProtection: 'false',
      useSmsBotScore: 'true'
    }
  };

Sostituisci ENFORCE_MODE con la modalità impostata 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.

Passaggi successivi

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