Integra 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 degli utenti. Questa funzionalità rende la tua app più resiliente contro spam, abusi e altre attività fraudolente.

L'integrazione crea un test 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, ovvero la protezione dai bot di reCAPTCHA. Con la protezione dai bot, Identity Platform esegue il provisioning delle chiavi reCAPTCHA basate sul punteggio nel tuo progetto per tuo conto. Quando un utente accede alla tua app o al tuo sito utilizzando una delle seguenti operazioni, l'SDK client carica reCAPTCHA quando il provider corrispondente è abilitato.

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

reCAPTCHA fornisce quindi a Identity Platform i punteggi che valutano il rischio della richiesta in base alla configurazione e alla tolleranza al rischio.

Per saperne di più, 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:

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

Se non hai ancora creato un account di servizio o se hai altri progetti che vuoi proteggere con reCAPTCHA, 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 al account di servizio l'accesso a reCAPTCHA:

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

    Sostituisci quanto segue:

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

Comportamento della protezione dai bot reCAPTCHA per provider

Il comportamento della protezione dai bot di reCAPTCHA dipende dal provider di identità configurato:

Provider email-password

Per i flussi di autenticazione con email e password, la protezione dai bot di reCAPTCHA supporta due modalità: audit (controllo) ed enforce (applicazione).

Modalità di controllo

Quando imposti l'applicazione di email e password in modalità di controllo, Identity Platform crea una o più chiavi reCAPTCHA nel tuo progetto che vengono utilizzate per valutare il traffico verso le API Identity Platform senza bloccare le richieste. Utilizza le metriche generate durante la modalità di controllo per determinare se attivare l'applicazione di reCAPTCHA.

Modalità di applicazione forzata

Quando imposti l'applicazione forzata di email e password in modalità di applicazione forzata, Identity Platform crea una o più chiavi reCAPTCHA nel tuo progetto che vengono utilizzate per valutare il traffico verso le API Identity Platform. Le richieste 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 supporto di reCAPTCHA.

Operatore di telefonia

Quando attivi la protezione dai bot per i flussi di autenticazione tramite numero di telefono impostando phoneEnforcementState su ENFORCE e useSmsBotScore su true, Identity Platform utilizza la protezione dai bot reCAPTCHA per verifica app. Se la richiesta di un utente supera la valutazione della protezione dai bot, viene inviato un codice di verifica via SMS. Se la richiesta di un utente non supera la valutazione della protezione dai bot, Identity Platform blocca la richiesta e non invia un SMS contenente un codice di verifica.

La verifica di riserva non è obbligatoria quando la protezione dai bot è abilitata per i flussi di autenticazione tramite numero di telefono e non è necessario 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 v2 sia disponibile se decidi di disabilitare la protezione dai bot.

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

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

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

Per i flussi di autenticazione con email e password, ti consigliamo di abilitare prima l'applicazione di reCAPTCHA in modalità Controllo e di monitorare le metriche reCAPTCHA generate dal tuo progetto per evitare di interrompere il traffico degli utenti durante la verifica della protezione dei flussi di autenticazione. Dopo aver verificato che i flussi di autenticazione sono protetti, imposta la protezione dai bot su ENFORCE. Per i flussi di autenticazione tramite telefono, attiva la protezione dai bot impostando phoneEnforcementState su ENFORCE e useSmsBotScore su true e monitora le metriche reCAPTCHA per perfezionare le soglie dei punteggi.

Abilita la protezione dai bot reCAPTCHA

Provider email-password

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

  1. Se non l'hai ancora fatto, attiva l'API reCAPTCHA Enterprise nel tuo progetto.

  2. Per attivare la protezione dai bot 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à che vuoi impostare per l'applicazione dell'autenticazione email-password di reCAPTCHA. I valori validi sono OFF, AUDIT e ENFORCE. Per attivare la protezione dai bot, questo parametro deve essere impostato su AUDIT o ENFORCE. Quando attivi la protezione dai bot 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 saperne di più sul funzionamento delle modalità, consulta Comportamento della protezione dai bot reCAPTCHA per provider.
    • END_SCORE: il punteggio di valutazione della protezione dai bot più basso che una richiesta può avere prima di non riuscire. Puoi impostare questo punteggio in modo che sia compreso tra 0.0 e 1.0. Ad esempio, se imposti una soglia di 0.6, reCAPTCHA non riuscirà a eseguire alcuna richiesta con un valore pari o inferiore a 0.5. Pertanto, più alto è il punteggio impostato, più rigide saranno le regole.

    Puoi anche attivare la protezione dai bot con lo stesso metodo di configurazione per un tenant utilizzando l'SDK Admin. Per saperne di più sull'aggiornamento di un tenant, consulta Aggiorna un tenant.

  3. Se utilizzi Identity Platform su iOS o Android, devi registrare l'app dalla console Firebase:

    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 di dominio e fai clic su Aggiungi per salvare il dominio.

    Il provisioning della chiave reCAPTCHA può richiedere diversi minuti.

  4. Se hai impostato l'applicazione in modalità di controllo, ti consigliamo di monitorare le metriche 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:

  1. Se non l'hai ancora fatto, attiva l'API reCAPTCHA Enterprise nel tuo progetto.

  2. Per attivare la protezione dai bot 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',
    managedRules: [{
      endScore: END_SCORE,
      action: 'BLOCK'
    }],
    useSmsBotScore: true,
  }
};
let projectConfig = await getAuth().projectConfigManager().updateProject(updateProjectConfigRequest);

    Sostituisci END_SCORE con il punteggio di valutazione della protezione dai bot più basso che una richiesta può avere prima di non riuscire. Puoi impostare questo punteggio in modo che sia compreso tra 0.0 e 1.0. Ad esempio, se imposti una soglia di 0.6, reCAPTCHA non accetta le richieste con un punteggio pari o inferiore a 0.5. Pertanto, più alto è il punteggio impostato, più severe sono le regole.

    Se imposti phoneEnforcementState su ENFORCE e useSmsBotScore su true, attivi l'applicazione della protezione dai bot per i flussi di autenticazione basati su SMS. Per saperne di più su come funziona l'applicazione del fornitore di servizi telefonici, consulta Comportamento della protezione dai bot reCAPTCHA per fornitore.

    Puoi anche attivare la protezione dai bot con lo stesso metodo di configurazione per un tenant utilizzando l'SDK Admin. Per saperne di più sull'aggiornamento di un tenant, consulta Aggiorna un tenant.

  3. Se utilizzi Identity Platform su iOS o Android, devi registrare la tua app dalla console Firebase:

    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 di dominio e fai clic su Aggiungi per salvare il dominio.

    Il provisioning della chiave reCAPTCHA può richiedere diversi minuti.

  4. Monitora le metriche reCAPTCHA per la protezione dai bot per assicurarti che i tuoi flussi siano protetti.

Configura l'SDK client

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

Web

  1. Esegui l'aggiornamento all'ultima versione dell'SDK web.

    • Il supporto di reCAPTCHA per l'autenticazione con email e password nelle app web è disponibile nelle versioni 9.20.0 e successive dell'SDK JavaScript.
    • Il supporto di reCAPTCHA per l'autenticazione tramite numero di telefono 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.

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

  1. Esegui l'aggiornamento all'ultima versione dell'SDK Android. Il supporto di reCAPTCHA per l'autenticazione con 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 attiva la protezione per 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.5.1'

    Assicurati di utilizzare l'SDK reCAPTCHA versione 18.5.1 o successive.

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

  1. Esegui l'aggiornamento all'SDK per iOS versione 11.6.0 o successive. 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 provider che hai configurato.

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

  3. Assicurati che -ObjC sia elencato nei flag del linker. Vai a Target > Build Settings > All > Linking e verifica che Other Linker Flags mostri -ObjC.

  4. 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
}];

Monitora le metriche reCAPTCHA per la protezione dai bot

Monitora le metriche reCAPTCHA generate dal tuo progetto per assicurarti che i flussi di autenticazione siano protetti. Per i flussi di autenticazione con email e password, ti consigliamo di monitorare le metriche in modalità di controllo prima di impostare l'applicazione in modalità di applicazione forzata. 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. Se il provisioning della chiave reCAPTCHA non va a buon fine o se i service account richiesti non sono stati creati, i tentativi di autenticazione reCAPTCHA vengono comunque eseguiti normalmente.

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

Per saperne di più, consulta Monitora le metriche reCAPTCHA.

Forza l'applicazione della protezione dai bot reCAPTCHA per i flussi email-password

Per i flussi di autenticazione con email e password inizialmente configurati in modalità AUDIT, dopo aver verificato che la tua app riceve un traffico di utenti accettabile, puoi passare da emailPasswordEnforcementState a ENFORCE per bloccare le richieste che non superano il test reCAPTCHA. Assicurati di non causare interruzioni per gli utenti esistenti, inclusi quelli che potrebbero utilizzare una versione precedente della tua app.

Per abilitare l'applicazione di reCAPTCHA per i flussi di autenticazione email-password su un progetto o un tenant, utilizza l'SDK Admin per eseguire il seguente codice:

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

Disabilita la protezione dai bot reCAPTCHA

Provider email-password

Per disattivare la protezione dai bot per i flussi di autenticazione con email e password, utilizza l'SDK Admin per eseguire il seguente comando:

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

Operatore di telefonia

Per disattivare tutte le protezioni reCAPTCHA per smartphone, inclusa la protezione dai bot, per i flussi di autenticazione basati su SMS, utilizza l'SDK Admin per eseguire il seguente comando:

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

Se utilizzi anche reCAPTCHA SMS defense e vuoi mantenerlo abilitato mentre disabiliti la protezione dai bot, imposta useSmsBotScore su false e lascia phoneEnforcementState impostato su ENFORCE:

const disableBotScoreOnlyRequest = {
  recaptchaConfig: {
    phoneEnforcementState: 'ENFORCE',
    useSmsBotScore: false,
    useSmsTollFraudProtection: true
  }
};

Esegui l'override dei verdetti reCAPTCHA con Cloud Run Functions

Oltre a configurare le soglie dei punteggi, puoi eseguire l'override di un verdetto reCAPTCHA per un determinato token utilizzando le funzioni di blocco per consentire o bloccare i flussi in base a fattori personalizzati. Questo è utile nei casi in cui un punteggio reCAPTCHA per un determinato accesso utente potrebbe essere basso, ma l'utente è attendibile o è stato verificato tramite altri mezzi ed è quindi autorizzato a completare l'accesso.

L'esempio seguente mostra come eseguire l'override di un verdetto reCAPTCHA utilizzando le funzioni di blocco:

Node.js 

  const functions = require("firebase-functions/v1");
  exports.beforesmsv1 = functions.auth.user().beforeSms((context) => {
    if (
      context.smsType === "SIGN_IN_OR_SIGN_UP" &&
      context.additionalUserInfo.phoneNumber.includes('+91')
    ) {
      return {
        recaptchaActionOverride: "ALLOW",
      };
    }

    // Allow users to sign in with recaptcha score greater than 0.5
    if (event.additionalUserInfo.recaptchaScore > 0.5) {
      return {
        recaptchaActionOverride: 'ALLOW',
      };
    }

    // Block all others.
    return  {
      recaptchaActionOverride: 'BLOCK',
    }
  });

Passaggi successivi