Questa pagina è stata tradotta dall'API Cloud Translation.

Integrare Identity Platform con l'API reCAPTCHA Enterprise

Questo documento mostra come utilizzare l'integrazione di Identity Platform con l'API reCAPTCHA Enterprise per migliorare la sicurezza per i tuoi utenti. Questa funzionalità rende la tua app più resiliente a spam, abusi e altre attività fraudolente.

L'integrazione crea una valutazione reCAPTCHA Enterprise per tuo conto per convalidare le richieste degli utenti. Per informazioni sui prezzi, consulta Prezzi di reCAPTCHA.

Panoramica

Quando configuri l'integrazione di Identity Platform con l'API reCAPTCHA Enterprise, attivi la funzionalità di protezione predefinita di reCAPTCHA: la protezione reCAPTCHA dei bot. Con la protezione dai bot, Identity Platform fornisce per tuo conto nel tuo progetto chiavi reCAPTCHA basate su punteggi. Quando un utente accede alla tua app o al tuo sito utilizzando una delle seguenti operazioni, l'SDK client carica reCAPTCHA se il fornitore corrispondente è attivato.

Provider	Operazione	Metodo
`passwordProvider`	Accesso con email e password	`signInWithPassword`
	Registrazione con email e password	`signUpPassword`
	Accesso tramite link email	`getOobCode`
	Reimpostazione password	`getOobCode`
`phoneProvider`	Registrazione o accesso tramite numero di telefono	`sendVerificationCode`
	Registrazione del numero di telefono per MFA;autenticazione a due fattori	`mfaSmsEnrollment`
	Accesso tramite numero di telefono con l'MFA	`mfaSmsSignIn`

reCAPTCHA fornisce quindi a Identity Platform dei punteggi 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.

Prima di iniziare

In base al tipo di flusso di autenticazione che vuoi proteggere con reCAPTCHA, assicurati di aver configurato quanto segue:

Per i flussi di autenticazione email-password, assicurati di aver configurato l'accesso tramite email per gli utenti.
Per i flussi di autenticazione basati su SMS, assicurati di aver eseguito l'onboarding di almeno uno dei seguenti elementi:
- Accesso con il telefono per gli utenti.
- Autenticazione a più fattori per la tua app web o Android.

Crea un account di servizio

L'integrazione di Identity Platform con l'API reCAPTCHA Enterprise richiede un account di servizio Identity Platform per ogni progetto che utilizzerà reCAPTCHA. In questo modo, Identity Platform può gestire le chiavi reCAPTCHA per tuo conto. Se hai già creato un account di servizio, concedigli l'accesso a reCAPCHA.

Se non hai ancora creato un account di servizio o hai altri progetti che vuoi proteggere con reCAPTCHA, svolgi i seguenti passaggi:

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.

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

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 dell'account del progetto

Modalità di protezione dai bot di reCAPTCHA

La protezione reCAPTCHA dei bot ha due modalità che ti aiutano a proteggere gli utenti: controllo e applicazione forzata. Il comportamento di queste modalità varia in base al provider di identità.

Provider email e password

Le modalità di controllo e applicazione si comportano come segue per i flussi di autenticazione email-password.

Modalità di controllo

Quando imposti l'applicazione dell'email e della password in modalità di controllo, Identity Platform crea nel tuo 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 è opportuno attivare l'applicazione forzata di reCAPTCHA.

Modalità di applicazione forzata

Quando imposti l'applicazione dell'obbligo di indirizzo email e password in modalità di applicazione, Identity Platform crea una o più chiavi reCAPTCHA nel tuo progetto che vengono utilizzate per valutare il traffico verso le API di Identity Platform. Le richieste dell'API che non includono un token reCAPTCHA vengono rifiutate. Attiva l'applicazione solo dopo aver eseguito la migrazione di tutti i client a un SDK con il supporto di reCAPTCHA.

Operatore di telefonia

Le modalità di controllo e applicazione si comportano come segue per i flussi di autenticazione telefonica.

Modalità di controllo

Quando imposti l'applicazione dell'autenticazione telefonica in modalità di controllo, Identity Platform utilizza la protezione dei bot reCAPTCHA per verifica app. Se la richiesta dell'utente supera la valutazione della protezione antibot, Identity Platform invia un messaggio SMS contenente un codice di verifica al telefono dell'utente. Se una richiesta non supera la valutazione della protezione antibot 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 protezione antibot 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 protezione antibot 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 è installato 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.

Modalità di applicazione forzata

Quando imposti l'applicazione dell'autenticazione telefonica in modalità di applicazione forzata, Identity Platform utilizza la protezione reCAPTCHA bot per verifica app. Se la richiesta dell'utente supera la valutazione della protezione dai bot, Identity Platform invia un messaggio SMS contenente un codice di verifica al telefono dell'utente. Se la richiesta non supera la valutazione della protezione antibot, 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.

Configurare l'integrazione di Identity Platform con l'API reCAPTCHA Enterprise

Per configurare l'integrazione di Identity Platform con l'API reCAPTCHA Enterprise, svolgi le seguenti attività:

Utilizza l'SDK Admin per impostare lo stato di applicazione di reCAPTCHA e attivare la protezione antibot.
Configura l'SDK client per la piattaforma della tua app.

Ti consigliamo di attivare prima l'applicazione di reCAPTCHA in modalità di controllo e di monitorare le metriche di reCAPTCHA emesse dal tuo progetto per assicurarti che i flussi di autenticazione siano protetti in modo appropriato. In questo modo, non interrompi il traffico degli utenti mentre ne controlli l'uso di reCAPTCHA. Dopo aver verificato che i flussi di autenticazione siano protetti, imposta la protezione antibot su ENFORCE.

Attivare la protezione reCAPTCHA dai bot

Provider email e password

Per attivare la protezione reCAPTCHA dai bot per i flussi di autenticazione email-password, svolgi i seguenti passaggi:

Se non l'hai ancora fatto, abilita l'API reCAPTCHA Enterprise nel tuo progetto.
Per attivare la protezione antibot per un progetto, utilizza l'SDK Admin. Il supporto di reCAPTCHA è disponibile nelle versioni 11.7.0 e successive dell'SDK Admin Node.js.

Ad esempio:
```
// Update project config with reCAPTCHA config
const updateConfigRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE_MODE',
    managedRules: [{
      endScore: END_SCORE,
      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);
  });
}
```
Sostituisci quanto segue:
- ENFORCE_MODE: la modalità da impostare per l'applicazione forzata dell'autenticazione email-password con reCAPTCHA. I valori validi sono OFF, AUDIT e ENFORCE. Per attivare la protezione antibot, questo parametro deve essere impostato su AUDIT o ENFORCE. Quando attivi la protezione antibot 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 protezione dai bot di reCAPTCHA.
- END_SCORE: il valore minimo della valutazione della protezione antibot che una richiesta può avere prima di non riuscire. Puoi impostare questo punteggio compreso tra 0.0 e 1.0. Ad esempio, se imposti una soglia di 0.6, reCAPTCHA non accetterà alcuna richiesta con un valore pari o inferiore a 0.6.0.5 Pertanto, più alto è il punteggio impostato, più severe saranno le regole.
Puoi anche attivare la protezione antibot con lo stesso metodo di configurazione per un tenant utilizzando l'SDK Admin. Per ulteriori informazioni sull'aggiornamento di un tenant, consulta Aggiornare un tenant.
Se utilizzi Identity Platform su iOS o Android, devi registrare la tua app dalla Console Firebase:
- Per iOS, registra ogni ID pacchetto che utilizza Identity Platform
- Per Android, registra ogni nome del pacchetto Android che utilizza Identity Platform
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 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 protezione dai bot per assicurarti che i tuoi flussi siano protetti.

Operatore di telefonia

Per attivare la protezione dai bot di reCAPTCHA per i flussi di autenticazione basati su SMS:

Se non l'hai ancora fatto, abilita l'API reCAPTCHA Enterprise nel tuo progetto.
Per attivare la protezione antibot per un progetto, utilizza l'SDK Admin. Il supporto di reCAPTCHA è disponibile nelle versioni 12.7.0 e successive dell'SDK Admin Node.js.

Ad esempio:
```
// Update project config with reCAPTCHA config
const updateProjectConfigRequest = {
  recaptchaConfig: {
    phoneEnforcementState: 'ENFORCE_MODE',
    managedRules: [{ endScore: END_SCORE, action: 'BLOCK' }],
    useSmsBotScore: 'true',
  }
}
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 protezione antibot per i flussi basati su SMS, questo parametro deve essere impostato su AUDIT o ENFORCE e useSmsBotScore deve essere impostato su true.
  
  Quando attivi la protezione antibot 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 protezione dai bot di reCAPTCHA.
- END_SCORE: il valore minimo della valutazione della protezione antibot che una richiesta può avere prima di non riuscire. Puoi impostare questo punteggio compreso tra 0.0 e 1.0. Ad esempio, se imposti una soglia di 0.6, reCAPTCHA non accetterà alcuna richiesta con un valore pari o inferiore a 0.6.0.5 Pertanto, più alto è il punteggio impostato, più severe saranno le regole.
Puoi anche attivare la protezione antibot con lo stesso metodo di configurazione per un tenant utilizzando l'SDK Admin. Per ulteriori informazioni sull'aggiornamento di un tenant, consulta Aggiornare un tenant.

Nota: Identity Platform non supporta l'utilizzo dell'autenticazione telefonica e dell'autenticazione a più fattori tramite SMS con più tenant sulle piattaforme mobile.
Se utilizzi Identity Platform su iOS o Android, devi registrare la tua app dalla Console Firebase:
- Per iOS, registra ogni ID pacchetto che utilizza Identity Platform
- Per Android, registra ogni nome del pacchetto Android che utilizza Identity Platform
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 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 protezione dai bot per assicurarti che i tuoi flussi siano protetti.

Configurare 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.

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 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 nella 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.

Per ridurre il numero di chiamate di rete effettuate dall'SDK e per rendere più efficace la raccolta degli indicatori reCAPTCHA, ti consigliamo di configurarlo esplicitamente 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

I flussi di autenticazione telefonica su iOS non sono supportati dall'integrazione di Identity Platform con l'API reCAPTCHA Enterprise.

Esegui l'aggiornamento alla versione 10.14.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.

Per ridurre il numero di chiamate di rete effettuate dall'SDK e per rendere più efficace la raccolta degli indicatori reCAPTCHA, ti consigliamo di configurarlo esplicitamente 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 protezione dai bot

Prima di impostare l'applicazione forzata di reCAPTCHA, ti consigliamo di utilizzare la modalità di controllo e di monitorare le metriche reCAPTCHA generate dal tuo progetto per assicurarti che i flussi di autenticazione 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. Se il provisioning della chiave reCAPTCHA non va a buon fine o se non sono stati creati gli account di servizio richiesti, i tentativi di autenticazione reCAPTCHA vanno comunque 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: monitora i diversi giudizi restituiti da reCAPTCHA.
identitytoolkit.googleapis.com/recaptcha/token_count: monitora il numero e lo stato dei token reCAPTCHA ricevuti dal backend di Identity Platform.
identitytoolkit.googleapis.com/recaptcha/risk_scores: monitora la distribuzione del punteggio di protezione dai bot.

Per ulteriori informazioni, consulta Monitorare le metriche reCAPTCHA.

Applicare la protezione reCAPTCHA dai bot

Dopo aver verificato che la tua app riceve traffico utente accettabile, puoi attivare l'applicazione 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.

Provider email e password

Per attivare l'applicazione di reCAPTCHA per i flussi di autenticazione email-password in un progetto o un tenant, utilizza l'SDK Admin per eseguire quanto segue:

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE',
    }]
  }
};

Operatore di telefonia

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 quanto segue:

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

Disattivare la protezione reCAPTCHA dai bot

Provider email e password

Per disattivare la protezione antibot per i flussi di autenticazione email-password, utilizza l'SDK Admin per eseguire il seguente comando:

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

Operatore di telefonia

Per disattivare la protezione antibot per i flussi di autenticazione basati su SMS, utilizza l'SDK Admin per eseguire il seguente comando:

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

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 Estendere l'autenticazione Firebase con le funzioni di blocco di Cloud Functions.

Passaggi successivi

Attiva la protezione antifrode tariffaria SMS di reCAPTCHA per i flussi di autenticazione basati su SMS.
Scopri come utilizzare la tua chiave reCAPTCHA.
Scopri di più sul monitoraggio delle metriche reCAPTCHA.
Scopri di più su reCAPTCHA.