reCAPTCHA Enterprise aktivieren

In diesem Dokument erfahren Sie, wie Sie mit der Einbindung von Identity Platform in reCAPTCHA die Sicherheit für Ihre Nutzer verbessern. Mit dieser Funktion wird deine App besser vor Spam, Missbrauch und anderen betrügerischen Aktivitäten geschützt.

Durch die Einbindung der Identity Platform in reCAPTCHA wird in Ihrem Namen eine reCAPTCHA-Bewertung erstellt, um Nutzeranfragen zu validieren. Preisinformationen finden Sie unter reCAPTCHA-Preise.

Wichtig :Diese Funktion unterstützt nur die Anmeldung und Registrierung mit E-Mail-Adresse und ein Passwort, das Zurücksetzen von Passwörtern und die Anmeldung über E-Mail-Links. Wenn ein legitimer Nutzer blockiert wird, findest du unter Fehlerbehebung Schritte zur Lösung des Problems.

Überblick

Wenn Sie die Einbindung von Identity Platform in reCAPTCHA konfigurieren, stellt Identity Platform in Ihrem Projekt punktzahlbasierte reCAPTCHA-Websiteschlüssel in Ihrem Projekt bereit. Wenn ein Nutzer mit einem der folgenden Vorgänge auf Ihre Anwendung oder Website zugreift, lädt das Client SDK reCAPTCHA:

Vorgang	Methode
Anmeldung mit E-Mail-Adresse und Passwort	signInWithPassword
Anmeldung mit E-Mail-Adresse und Passwort	signUpPassword
Anmeldung per E-Mail-Link	getOobCode
Passwortzurücksetzung	getOobCode

reCAPTCHA stellt der Identity Platform dann Risikosignale zur Verfügung, die das Risiko der Anfrage anhand Ihrer Konfiguration und Risikotoleranz bewerten.

Weitere Informationen finden Sie unter Übersicht über reCAPTCHA Enterprise.

Wichtig: In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

• reCAPTCHA Enterprise
• Identity Platform

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen. Neuen Google Cloud-Nutzern steht möglicherweise eine kostenlose Testversion zur Verfügung.

Hinweise

Konfigurieren Sie die E-Mail-Anmeldung für Nutzer.

Dienstkonto erstellen

Bevor Sie reCAPTCHA aktivieren, müssen Sie für jedes Projekt, das reCAPTCHA verwendet, ein Dienstkonto erstellen und jedem Dienstkonto Zugriff auf reCAPTCHA gewähren. Dadurch kann Identity Platform reCAPTCHA-Schlüssel in Ihrem Namen verwalten.

So erstellen Sie ein Dienstkonto:

1. Verwenden Sie die Google Cloud CLI, um ein Dienstkonto zu erstellen:

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

   Ersetzen Sie PROJECT_ID durch die Projekt-ID.

2. Gewähren Sie dem Dienstkonto Zugriff auf reCAPTCHA:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/identitytoolkit.serviceAgent
   

   Ersetzen Sie Folgendes:

   • PROJECT_ID: die Projekt-ID
   • PROJECT_NUMBER: die Projektkontonummer

reCAPTCHA aktivieren

reCAPTCHA bietet zwei Modi, mit denen Sie Nutzer besser schützen können:

• Prüfung: Wenn diese Option aktiviert ist, erstellt die Identity Platform einen oder mehrere reCAPTCHA-Schlüssel in Ihrem Projekt, mit denen der Traffic zu Identity Platform APIs bewertet wird, ohne Anfragen zu blockieren. Ermitteln Sie anhand der Messwerte, die im Prüfmodus ausgegeben werden, ob Sie die reCAPTCHA-Erzwingung aktivieren sollten.
• Erzwingung: Wenn diese Option aktiviert ist, erstellt die Identity Platform einen oder mehrere reCAPTCHA-Schlüssel in Ihrem Projekt, mit denen der Traffic zu Identity Platform APIs bewertet wird. API-Anfragen ohne reCAPTCHA-Token werden abgelehnt. Aktivieren Sie die Erzwingung erst, nachdem Sie alle Ihre Clients zu einem SDK mit reCAPTCHA-Unterstützung migriert haben.

Wichtig: Bearbeiten oder löschen Sie keine reCAPTCHA-Schlüssel mit dem Namen „Key for Identity Platform integration with reCAPTCHA“, es sei denn, reCAPTCHA ist deaktiviert. Andernfalls kann die Identity Platform den reCAPTCHA-Schutz nicht anwenden. Darüber hinaus können Identity Platform-SDKs keine Tokens aus reCAPTCHA-Schlüsseln generieren, die Sie selbst generieren.

So aktivieren Sie reCAPTCHA:

1. Falls noch nicht geschehen, aktivieren Sie die reCAPTCHA API für Ihr Projekt.

2. Aktivieren Sie die Einbindung von Identity Platform in reCAPTCHA für ein Projekt, das das Admin SDK verwendet. reCAPTCHA-Unterstützung ist ab Version 11.7.0 des Node.js Admin SDK verfügbar.

   Beispiel:

   // 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);
     });
   }
   

3. Aktivieren Sie die Integration der Identity Platform mit reCAPTCHA für einen Mandanten, der das Admin SDK verwendet. Beispiel:

   // 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);
     });
   }
   

   Ersetzen Sie Folgendes:

   • TENANT_ID: die Mandanten-ID
   Hinweis: Die Identity Platform unterstützt die Mehrmandantenfähigkeit mit reCAPTCHA auf mobilen Plattformen nicht.

4. Wenn Sie Identity Platform auf Apple-Plattformen oder Android verwenden, müssen Sie Ihre App über die Firebase Console registrieren:

   • Für Apple-Plattformen registrieren Sie jede Bundle-ID, die Identity Platform verwendet.
   • Für Android registrieren Sie jeden Android-Paketnamen, der Identity Platform verwendet.

5. Wenn Sie Identity Platform im Web verwenden, müssen Sie für jede Domain, die reCAPTCHA verwendet, eine autorisierte Domain hinzufügen. So fügen Sie autorisierte Domains hinzu:

   1. Rufen Sie in der Google Cloud Console die Seite „Identity Platform“ auf.

      Zur Identity Platform

   2. Gehen Sie zu Einstellungen > Sicherheit.

   3. Klicken Sie auf Domain hinzufügen.

   4. Geben Sie den Domainnamen ein und klicken Sie auf Hinzufügen, um die Domain zu speichern.

   Die Bereitstellung von Websiteschlüsseln kann einige Minuten dauern. Prüfen Sie die metrics, um sicherzustellen, dass Ihre Abläufe geschützt sind.

Client SDK konfigurieren

Konfigurieren Sie das Client SDK entsprechend der Plattform Ihrer App.

Web

1. Aktualisieren Sie auf die neueste Version des Web SDK. reCAPTCHA-Unterstützung ist ab Version 9.20.0 des JavaScript SDK verfügbar. Nachdem Sie das Web SDK in Ihre App eingebunden haben, wird automatisch Ihre reCAPTCHA-Konfiguration abgerufen und die von Ihnen konfigurierten Anbieter werden geschützt.

2. Um die Anzahl der vom SDK durchgeführten Netzwerkaufrufe zu reduzieren und die reCAPTCHA-Signalerfassung zu verbessern, empfehlen wir, es explizit so zu konfigurieren:

   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

1. Führen Sie ein Update auf Android SDK 31.5.0 oder höher durch. Für die reCAPTCHA-Unterstützung sind API-Level 19 (KitKat) oder höher und Android 4.4 oder höher erforderlich. Nachdem Sie das Android SDK in Ihre App eingebunden haben, wird automatisch Ihre reCAPTCHA-Konfiguration abgerufen und die von Ihnen konfigurierten Anbieter werden geschützt.

2. Fügen Sie die folgende Build-Regel in den Abschnitt „Abhängigkeiten“ der Datei build.gradle auf Anwendungsebene ein:

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

   Verwenden Sie mindestens Version 18.4.0 des reCAPTCHA SDK.

3. Um die Anzahl der vom SDK ausgeführten Netzwerkaufrufe zu reduzieren und die reCAPTCHA-Signalerfassung effektiver zu gestalten, empfehlen wir, es explizit so zu konfigurieren:

   • 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

1. Führen Sie ein Update auf Version 10.14.0 oder höher des iOS SDK durch. Nachdem Sie das iOS SDK in Ihre App eingebunden haben, wird automatisch Ihre reCAPTCHA-Konfiguration abgerufen und die von Ihnen konfigurierten Anbieter werden geschützt.

2. Informationen zum Einbinden des reCAPTCHA iOS SDK in Ihre App finden Sie unter Umgebung vorbereiten.

3. Achten Sie darauf, dass -ObjC in den Verknüpfungs-Flags aufgeführt ist. Rufen Sie „Ziel“ > „Build-Einstellungen“ > „Alle“ > „Verknüpfung“ auf und prüfen Sie, ob für Other Linker Flags -ObjC angezeigt wird.

4. Um die Anzahl der vom SDK ausgeführten Netzwerkaufrufe zu reduzieren und die Erfassung von reCAPTCHA-Signalen effektiver zu gestalten, empfehlen wir, sie explizit zu konfigurieren:

   • Swift:

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

   • Objective-C:

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

reCAPTCHA-Messwerte

Überwachen Sie nach dem Aktivieren von reCAPTCHA die reCAPTCHA-Messwerte, die Ihr Projekt ausgibt, um sicherzustellen, dass Authentifizierungsabläufe geschützt sind. Wenn die Bereitstellung des reCAPTCHA-Websiteschlüssels fehlschlägt oder die erforderlichen Dienstkonten nicht erstellt wurden, schlägt die reCAPTCHA-Authentifizierung fehl.

Sorgen Sie dafür, dass die reCAPTCHA-Authentifizierung funktioniert. Prüfen Sie dazu die folgenden Messwerte, die Ihr Projekt an Cloud Monitoring sendet:

identitytoolkit.googleapis.com/recaptcha/verdict_count

Verfolgt die verschiedenen von reCAPTCHA zurückgegebenen Ergebnisse. Ein Ergebnis wird generiert, wenn ein Token vorhanden ist. Du kannst nach den folgenden Ergebnissen filtern:

• PASSED: Gibt an, dass eine bestimmte Anfrage zulässig ist, wenn die Erzwingung aktiviert ist.
• FAILED_AUDIT: Gibt an, dass eine bestimmte Anfrage abgelehnt wird, wenn der reCAPTCHA-Auditmodus aktiviert ist.
• FAILED_ENFORCE: Gibt an, dass eine bestimmte Anfrage abgelehnt wird, wenn der reCAPTCHA-Erzwingungsmodus aktiviert ist.
• CLIENT_TYPE_MISSING: Gibt an, dass bei einer bestimmten Anfrage ein Clienttyp fehlt, wenn die reCAPTCHA-Erzwingung aktiviert ist. Dies tritt normalerweise auf, wenn eine Anfrage mit einer veralteten Client SDK-Version gesendet wurde, die reCAPTCHA nicht unterstützt.
• KEYS_MISSING: Gibt an, dass eine bestimmte Anfrage nicht verifiziert werden kann, da keine gültigen reCAPTCHA-Schlüssel abgerufen oder generiert werden können, wenn die reCAPTCHA-Erzwingung aktiviert ist.

Informationen zum Ändern der Punktzahlbereiche, um das Verhältnis zwischen bestandenen und nicht bestandenen Ergebnissen zu ändern, finden Sie unter reCAPTCHA Enterprise aktivieren.

identitytoolkit.googleapis.com/recaptcha/token_count

Verfolgt die Anzahl und den Status der vom Identity Platform-Back-End empfangenen reCAPTCHA-Tokens. Sie können nach folgenden Status filtern:

• VALID: Gibt an, dass das übergebene reCAPTCHA-Token gültig ist.
• EXPIRED: Das übergebene reCAPTCHA-Token ist abgelaufen. Ein abgelaufenes Token kann auf Probleme mit dem Clientnetzwerk oder Missbrauch hinweisen.
• DUPLICATE: Gibt an, dass das übergebene reCAPTCHA-Token ein Duplikat ist. Ein doppeltes Token kann auf Probleme mit dem Clientnetzwerk oder Missbrauch hinweisen.
• INVALID: Gibt an, dass das übergebene reCAPTCHA-Token ungültig ist. Ein ungültiges Token kann auf Missbrauch hinweisen.
• MISSING: Gibt an, dass das reCAPTCHA-Token in der angegebenen Anfrage nicht vorhanden ist. Fehlende Tokens können auf eine veraltete Client-App hinweisen.
• UNCHECKED: Gibt an, dass das reCAPTCHA-Token aufgrund von CLIENT_TYPE_MISSING- oder KEYS_MISSING-Ergebnissen nicht geprüft wurde.

Wenn Ihre App erfolgreich für Nutzer eingeführt wurde, sehen Sie Traffic mit gültigen Tokens. Die Anzahl der gültigen Tokens ist wahrscheinlich proportional zur Anzahl der Nutzer, die Ihre aktualisierte App verwenden.

identitytoolkit.googleapis.com/recaptcha/risk_scores

Erfasst die reCAPTCHA-Wertverteilung. Dies kann Ihnen helfen, die optimalen Punktzahlbereiche für Ihre Konfiguration zu definieren.

Anhand dieser Messwerte können Sie ermitteln, ob Sie die Erzwingung aktivieren können. Beachten Sie Folgendes, bevor Sie die Erzwingung aktivieren:

• Wenn die Mehrzahl der letzten Anfragen gültige Tokens enthält und das Verhältnis von PASSED- zu FAILED_AUDIT- oder FAILED_ENFORCE-Ergebnissen für Ihren Business Case akzeptabel ist, sollten Sie die Erzwingung aktivieren.
• Wenn ein Großteil der letzten Anfragen wahrscheinlich von veralteten Clients stammt, sollten Sie warten, bis mehr Nutzer ihre Anwendung aktualisiert haben, bevor Sie die Erzwingung aktivieren. Wenn Sie die Einbindung der Identity Platform mit reCAPTCHA erzwingen, funktionieren ältere Anwendungsversionen, die nicht in reCAPTCHA eingebunden sind, nicht mehr.

So rufen Sie diese Messwerte auf:

1. Rufen Sie in der Google Cloud Console die Seite Metrics Explorer auf.

   Zum Metrics Explorer

2. Geben Sie unter Messwert auswählen den Wert Identity Toolkit-Mandant ein. Wenn Sie die Mehrmandantenfähigkeit verwenden, können Sie Messwerte für jeden Mandanten sowie für das übergeordnete Projekt aufrufen, indem Sie tenant_name leer lassen.

Erzwingung aktivieren

Nachdem Sie überprüft haben, ob Ihre Anwendung akzeptablen Nutzertraffic empfängt, können Sie die Erzwingung von reCAPTCHA aktivieren, um Ihre Nutzer zu schützen. Sorgen Sie dafür, dass bestehende Nutzer nicht beeinträchtigt werden. Dies schließt auch Nutzer ein, die möglicherweise eine ältere Version Ihrer App verwenden.

Um die reCAPTCHA-Erzwingung für ein Projekt oder einen Mandanten zu aktivieren, verwenden Sie das Admin SDK, um Folgendes auszuführen:

const enforceRequest = {
  recaptchaConfig: {
    emailPasswordEnforcementState:  'ENFORCE',
    managedRules: [{
      endScore: 0.3,
      action: 'BLOCK'
    }]
  }
};

reCAPTCHA deaktivieren

Verwenden Sie zum Deaktivieren von reCAPTCHA das Admin SDK, um Folgendes auszuführen:

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

reCAPTCHA-Ergebnisse mit Cloud Functions überschreiben

Sie können nicht nur Punktzahl-Schwellenwerte konfigurieren, sondern auch ein reCAPTCHA-Ergebnis für ein bestimmtes Token überschreiben. Dazu verwenden Sie eine benutzerdefinierte Cloud Functions-Blockierfunktion. Dies ist hilfreich, wenn ein reCAPTCHA-Wert für eine bestimmte Nutzeranmeldung niedrig sein kann, der Nutzer aber vertrauenswürdig ist oder auf andere Weise bestätigt wurde und daher die Anmeldung abschließen darf.

Weitere Informationen zum Konfigurieren von Blockierfunktionen mit reCAPTCHA finden Sie unter Firebase-Authentifizierung mit blockierenden Cloud Functions-Funktionen erweitern.

Fehlerbehebung

Nutzer können sich nicht anmelden, registrieren oder ihr Passwort nicht zurücksetzen

Nutzer verwenden möglicherweise eine veraltete Version der App. Wenn Sie keine aktualisierte Version Ihrer App bereitgestellt haben, die das Client SDK verwendet, deaktivieren Sie den Erzwingungsmodus sofort. Bitten Sie andernfalls die Nutzer, ihre App zu aktualisieren.

Es ist auch möglich, dass Nutzer aufgrund Ihrer aktuellen Konfiguration blockiert werden. Geben Sie Folgendes ein:

• Ziehen Sie eine großzügigere Konfiguration in Betracht, indem Sie die reCAPTCHA-Key-Scores anpassen.
• Bitten Sie den Nutzer, es mit einem anderen Gerät, Browser oder Netzwerk zu versuchen.
• Kehren Sie zum Prüfmodus zurück und beobachten Sie die Messwerte, bevor Sie den Erzwingungsmodus wieder aktivieren.