Abilita reCAPTCHA Enterprise
Questo documento mostra come utilizzare l'integrazione di Identity Platform con reCAPTCHA 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 crea una test reCAPTCHA per tuo conto per convalidare le richieste degli utenti. Per informazioni sui prezzi, vedi i prezzi di reCAPTCHA.
Panoramica
Quando configuri l'integrazione di Identity Platform con reCAPTCHA, Identity Platform esegue il provisioning chiavi sito reCAPTCHA basate sul punteggio nel progetto. Quando un utente accede alla tua app o al tuo sito utilizzando una delle seguenti operazioni: l'SDK del client carica reCAPTCHA:
Operazione | Metodo |
---|---|
Accesso con email e password | signInWithPassword |
Registrazione con email e password | signUpPassword |
Accesso via email tramite link | getOobCode |
Reimpostazione password | getOobCode |
reCAPTCHA fornisce quindi a Identity Platform gli indicatori di rischio 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 Enterprise.
Prima di iniziare
Configura l'accesso via email per gli utenti.
Crea un account di servizio
Prima di abilitare reCAPTCHA, devi creare un account di servizio per ogni progetto che utilizzerà reCAPTCHA e concederà a ciascun account di servizio e l'accesso a reCAPTCHA. Consente a Identity Platform di gestire le chiavi reCAPTCHA per tuo conto.
Per creare un account di servizio:
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
: ID progettoPROJECT_NUMBER
: il numero di account del progetto
Abilita reCAPTCHA
reCAPTCHA prevede due modalità che ti aiutano a proteggere gli utenti:
- Controllo: se abilitato, Identity Platform crea uno o più reCAPTCHA Chiavi del progetto utilizzate per valutare il traffico verso le API Identity Platform senza bloccare le richieste. Utilizza le metriche emesse durante la modalità di controllo per determinare se è necessario abilitare l'applicazione forzata di reCAPTCHA.
- Applicazione forzata: se abilitata, Identity Platform crea uno o più reCAPTCHA chiave del progetto utilizzate per valutare il traffico verso le API Identity Platform. Le richieste API che non includono un token reCAPTCHA vengono rifiutate. Abilita l'applicazione forzata solo dopo aver eseguito la migrazione di tutti i tuoi client a un SDK con Supporto reCAPTCHA.
Per abilitare reCAPTCHA, segui questi passaggi:
- Se non lo hai già fatto, abilita l'API reCAPTCHA nel tuo progetto.
Abilita l'integrazione di Identity Platform con reCAPTCHA per un progetto utilizzando l'SDK Admin. reCAPTCHA Il supporto è disponibile per l'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); }); }
Abilita l'integrazione di Identity Platform con reCAPTCHA 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
: ID tenant
Se utilizzi Identity Platform su piattaforme Apple o Android, devi registrarti per 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
Se utilizzi Identity Platform sul web, devi aggiungere un dominio autorizzato per ogni dominio che utilizza reCAPTCHA. Per aggiungere domini autorizzati, segui questi passaggi:
Nella console Google Cloud, vai alla pagina Identity Platform.
Vai a Impostazioni > Sicurezza.
Fai clic su Aggiungi dominio.
Inserisci il nome del dominio e fai clic su Aggiungi per salvare il dominio.
Il completamento del provisioning delle chiavi del sito può richiedere diversi minuti. Per assicurarti che che i flussi siano protetti, controlla le metriche.
Configura l'SDK client
Configura l'SDK client in base alla piattaforma della tua app.
Web
Esegui l'aggiornamento all'ultima versione dell'SDK web. Il supporto per reCAPTCHA è disponibile nell'SDK JavaScript versione 9.20.0 e successive. Dopo aver integrato l'SDK web con la tua app, questa recupera automaticamente la configurazione reCAPTCHA e protegge i provider che hai configurato.
Per ridurre il numero di chiamate di rete effettuate dall'SDK e migliorare Raccolta di indicatori reCAPTCHA, ti consigliamo di configurarla 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
Esegui l'aggiornamento all'SDK per Android versione 31.5.0 o successive. Il supporto di reCAPTCHA richiede il livello API 19 (KitKat) o versioni successive e Android 4.4 o versioni successive. Dopo aver integrato l'SDK Android con la tua app, questa recupera automaticamente la configurazione reCAPTCHA e protegge i provider che hai configurato.
Aggiungi la seguente regola di build alla sezione delle dipendenze a livello di app File
build.gradle
:implementation 'com.google.android.recaptcha:recaptcha:18.4.0'
Assicurati di utilizzare l'SDK reCAPTCHA versione 18.4.0 o successive.
Ridurre il numero di chiamate di rete effettuate dall'SDK e rendere reCAPTCHA una raccolta degli indicatori più efficace, ti consigliamo di configurarla esplicitamente come segue:
- 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
Esegui l'aggiornamento all'SDK per iOS versione 10.14.0 o successive. Dopo aver integrato l'SDK per iOS con la tua app, l'app recupera automaticamente la configurazione reCAPTCHA e protegge i provider che hai configurato.
Per integrare l'SDK reCAPTCHA per iOS nella tua app, vedi Preparare l'ambiente.
Assicurati che
-ObjC
sia elencato nei flag del linker. Vai a Target > Impostazioni build > Tutti > Collegamento e verifica cheOther Linker Flags
mostri-ObjC
.Ridurre il numero di chiamate di rete effettuate dall'SDK e rendere reCAPTCHA una raccolta degli indicatori più efficace, ti consigliamo di configurarla in modo esplicito, come segue:
- 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 reCAPTCHA
Dopo aver abilitato reCAPTCHA, monitora le metriche reCAPTCHA emessi dal progetto per garantire che i flussi di autenticazione siano protetti. Se il provisioning della chiave di sito reCAPTCHA non va a buon fine o se viene richiesto il servizio account non creati, autenticazione reCAPTCHA non riuscita.
Assicurati che l'autenticazione reCAPTCHA funzioni esaminando le metriche seguenti inviate dal progetto a Cloud Monitoring:
identitytoolkit.googleapis.com/recaptcha/verdict_count
Tiene traccia dei diversi esiti restituiti da reCAPTCHA. Se è presente un token, viene generato un esito. Puoi filtrare in base ai seguenti esiti:
PASSED
: indica che una determinata richiesta è consentita quando è attiva l'applicazione forzata.FAILED_AUDIT
: indica che una determinata richiesta viene rifiutata quando reCAPTCHA sia abilitata.FAILED_ENFORCE
: indica che una determinata richiesta viene rifiutata quando reCAPTCHA la modalità di applicazione forzata è abilitata.CLIENT_TYPE_MISSING
: indica che per una determinata richiesta manca un client quando è abilitata l'applicazione forzata di reCAPTCHA. Questo si verifica in genere se una richiesta è stata inviata utilizzando una versione obsoleta dell'SDK del client che non dispone Supporto reCAPTCHA.KEYS_MISSING
: indica che una determinata richiesta non può essere verificata a causa del impossibilità di recuperare o generare chiavi reCAPTCHA valide L'applicazione forzata di reCAPTCHA è abilitata.
Per modificare gli intervalli di punteggi e cambiare il rapporto tra esiti positivi e non superati, consulta Abilitare reCAPTCHA Enterprise.
identitytoolkit.googleapis.com/recaptcha/token_count
Tiene traccia del numero e dello stato dei token reCAPTCHA ricevuti dalla il backend di Identity Platform. Puoi applicare un filtro 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 di rete del client.DUPLICATE
: indica che il token reCAPTCHA trasmesso è un duplicati. Un token duplicato potrebbe indicare problemi o comportamenti illeciti di 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 in per la richiesta specificata. I token mancanti potrebbero indicare un'app client obsoleta.UNCHECKED
: indica che il token reCAPTCHA non è stato verificato a causa degli esitiCLIENT_TYPE_MISSING
oKEYS_MISSING
.
Se la tua 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 l'app aggiornata.
identitytoolkit.googleapis.com/recaptcha/risk_scores
Tiene traccia della distribuzione del punteggio reCAPTCHA. Questo può aiutarti a definire gli intervalli di punteggi ottimali per la tua configurazione.
Utilizza queste metriche per determinare se puoi abilitare l'applicazione forzata. Prima di attivare l'applicazione, considera quanto segue:
- Se la maggior parte delle richieste recenti contiene token validi e il rapporto è pari a
PASSED
aFAILED_AUDIT
oFAILED_ENFORCE
è accettabile per la tua attività ti consigliamo di abilitare l'applicazione forzata. - Se la maggior parte delle richieste recenti proviene probabilmente da client obsoleti, prendi in considerazione attendere che altri utenti aggiornino l'app prima di abilitare l'applicazione forzata. L'applicazione dell'integrazione di Identity Platform con reCAPTCHA interrompe le versioni precedenti dell'app che non sono integrate con reCAPTCHA.
Per visualizzare queste metriche:
Nella console Google Cloud, vai alla pagina Esplora metriche.
In Seleziona una metrica, inserisci Identity Toolkit Tenant. Se utilizzi la multitenancy, puoi visualizzare le metriche per ogni tenant, oltre al progetto principale, lasciando vuoto il campo
tenant_name
.
Abilita applicazione forzata
Dopo aver verificato che la tua app riceve traffico di utenti accettabile, puoi abilitare l'applicazione forzata di reCAPTCHA per proteggere i tuoi utenti. Assicurati di non disturbare gli utenti esistenti, inclusi quelli che potrebbero utilizzare un la versione precedente dell'app.
Per abilitare l'applicazione forzata di reCAPTCHA per un progetto o un tenant, utilizza l'SDK Admin per eseguire quanto segue:
const enforceRequest = {
recaptchaConfig: {
emailPasswordEnforcementState: 'ENFORCE',
managedRules: [{
endScore: 0.3,
action: 'BLOCK'
}]
}
};
Disabilita reCAPTCHA
Per disattivare reCAPTCHA, utilizza l'SDK Admin per eseguire questo comando:
const disableRequest = {
recaptchaConfig: {
emailPasswordEnforcementState: 'OFF',
}
};
Override degli esiti reCAPTCHA con Cloud Functions
Oltre a configurare le soglie di punteggio, puoi eseguire l'override Esito di reCAPTCHA per un determinato token utilizzando una funzione di blocco di Cloud Functions personalizzata. Ciò è utile nei casi in cui un punteggio reCAPTCHA per un determinato utente potrebbe essere basso, ma l'utente è attendibile o verificato tramite altri significa ed è quindi autorizzato a completare l'accesso.
Per scoprire di più sulla configurazione delle funzioni di blocco con reCAPTCHA, consulta Estendi Firebase Authentication 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 dell'app che utilizza l'SDK client, disattiva immediatamente la modalità di applicazione forzata. In caso contrario, chiedi agli utenti di aggiornare la loro app.
In alternativa, gli utenti potrebbero essere bloccati in base alla tua configurazione attuale. Prova a procedere come segue:
- Considera una configurazione più permissiva tramite le modifiche. Punteggi delle chiavi reCAPTCHA.
- Chiedi all'utente di provare con un altro dispositivo, browser o rete.
- Ripristina la modalità di controllo e monitora le metriche prima di riattivare la modalità di applicazione forzata.