reCAPTCHA Enterprise aktivieren

In diesem Dokument erfahren Sie, wie Sie die Identity Platform-Integration mit reCAPTCHA Enterprise verwenden, um die Sicherheit für Ihre Nutzer zu verbessern. Diese Funktion macht deine App besser vor Spam, Missbrauch und anderen betrügerischen Aktivitäten geschützt.

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

Überblick

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

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, mit denen das Risiko der Anfrage anhand Ihrer Konfiguration und Risikotoleranz bewertet wird.

Weitere Informationen finden Sie unter reCAPTCHA Enterprise – Übersicht.

Hinweise

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

Dienstkonto erstellen

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

So erstellen Sie ein Dienstkonto:

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.

Gewähren Sie dem Dienstkonto Zugriff auf reCAPTCHA Enterprise:

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

Ersetzen Sie Folgendes:

PROJECT_ID: die Projekt-ID
PROJECT_NUMBER: die Projektkontonummer

reCAPTCHA Enterprise aktivieren

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

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

So aktivieren Sie reCAPTCHA Enterprise:

Wenn Sie dies noch nicht getan haben, aktivieren Sie die reCAPTCHA Enterprise API für Ihr Projekt.

Aktivieren Sie die Identity Platform-Integration in reCAPTCHA Enterprise für ein Projekt mithilfe des Admin SDK. reCAPTCHA Enterprise-Support ist ab Node.js Admin SDK Version 11.7.0 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);
  });
}

Aktivieren Sie die Identity Platform-Integration mit reCAPTCHA Enterprise für einen Mandanten mithilfe des Admin SDK. 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

Wenn Sie Identity Platform auf Apple-Plattformen oder Android verwenden, müssen Sie Ihre Anwendung über die Firebase Console registrieren:
- Bei Apple-Plattformen jede Bundle-ID registrieren, die Identity Platform verwendet
- Für Android: Registrieren Sie jeden Android-Paketnamen, für den die Identity Platform verwendet wird.
Wenn Sie Identity Platform im Web verwenden, müssen Sie jeder 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 des Websiteschlüssels kann einige Minuten dauern. Prüfen Sie die metrics, um sicherzustellen, dass Ihre Abläufe geschützt werden.

Client SDK konfigurieren

Konfigurieren Sie das Client SDK entsprechend der Plattform Ihrer App.

Web

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

Um die Anzahl der Netzwerkaufrufe des SDK zu reduzieren und die Erfassung von reCAPTCHA-Signalen 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

Führen Sie ein Update auf Android SDK-Version 31.5.0 oder höher durch. Für den reCAPTCHA Enterprise-Support ist das 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 Ihre reCAPTCHA Enterprise-Konfiguration automatisch abgerufen und die von Ihnen konfigurierten Anbieter werden geschützt.
Fügen Sie die folgende Build-Regel im Abschnitt „Abhängigkeiten“ der Datei build.gradle auf App-Ebene hinzu:
```
implementation 'com.google.android.recaptcha:recaptcha:18.4.0'
```
Du musst die reCAPTCHA SDK-Version 18.4.0 oder höher verwenden.

Um die Anzahl der Netzwerkaufrufe des SDK zu reduzieren und die Erfassung von reCAPTCHA-Signalen 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

Aktualisieren Sie auf iOS SDK 10.14.0 oder höher. Nachdem Sie das iOS SDK in Ihre App eingebunden haben, wird Ihre reCAPTCHA Enterprise-Konfiguration automatisch abgerufen und die von Ihnen konfigurierten Anbieter werden geschützt.
Informationen zum Integrieren des reCAPTCHA iOS SDK in Ihre App finden Sie unter Umgebung vorbereiten.
Achten Sie darauf, dass -ObjC in den Verknüpfungs-Flags aufgeführt ist. Gehe zu „Ziel“ > „Build-Einstellungen“ > „Alle“ > „Verknüpfung“ und überprüfe, ob in Other Linker Flags -ObjC angezeigt wird.

Um die Anzahl der Netzwerkaufrufe des SDK zu reduzieren und die Erfassung von reCAPTCHA-Signalen effektiver zu gestalten, empfehlen wir, es explizit so 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 Enterprise-Messwerte

Nachdem Sie reCAPTCHA Enterprise aktiviert haben, überwachen Sie die reCAPTCHA-Messwerte, die Ihr Projekt ausgibt, um sicherzustellen, dass die Authentifizierungsabläufe geschützt sind. Wenn die Bereitstellung von reCAPTCHA-Websiteschlüsseln fehlschlägt oder erforderliche Dienstkonten nicht erstellt wurden, schlägt die reCAPTCHA-Authentifizierung fehl.

Prüfen Sie die folgenden Messwerte, die Ihr Projekt an Cloud Monitoring sendet, um sicherzustellen, dass die reCAPTCHA-Authentifizierung funktioniert:

`identitytoolkit.googleapis.com/recaptcha/verdict_count`

Verfolgt die verschiedenen von reCAPTCHA Enterprise zurückgegebenen Ergebnisse. Wenn ein Token vorhanden ist, wird ein Ergebnis generiert. 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-Audit-Modus 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. Dieses Problem tritt in der Regel 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 überprüft werden kann, weil 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 der übergebenen zu fehlerhaften Ergebnisse zu ändern, finden Sie unter reCAPTCHA Enterprise aktivieren.

`identitytoolkit.googleapis.com/recaptcha/token_count`

Verfolgt die Anzahl und den Status von reCAPTCHA Enterprise-Tokens, die vom Identity Platform-Backend empfangen wurden. Sie können nach den folgenden Status filtern:

VALID: Gibt an, dass das übergebene reCAPTCHA-Token gültig ist.
EXPIRED: gibt an, dass das übergebene reCAPTCHA-Token abgelaufen ist. Ein abgelaufenes Token kann auf Probleme mit dem Clientnetzwerk oder Missbrauch hindeuten.
DUPLICATE: Gibt an, dass das übergebene reCAPTCHA-Token ein Duplikat ist. Ein doppeltes Token kann auf Probleme mit dem Clientnetzwerk oder Missbrauch hindeuten.
INVALID: Gibt an, dass das übergebene reCAPTCHA-Token ungültig ist. Ein ungültiges Token kann auf Missbrauch hindeuten.
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 die Einführung Ihrer App für Nutzer erfolgreich war, sehen Sie Traffic mit gültigen Tokens. Die Anzahl gültiger Tokens ist wahrscheinlich proportional zur Anzahl der Nutzer, die deine aktualisierte App verwenden.

`identitytoolkit.googleapis.com/recaptcha/risk_scores`

Erfasst die reCAPTCHA-Punktzahlverteilung. Auf diese Weise können Sie die optimalen Punktzahlbereiche für Ihre Konfiguration definieren.

Anhand dieser Messwerte können Sie feststellen, ob Sie die Erzwingung aktivieren können. Bevor Sie die Erzwingung aktivieren, sollten Sie Folgendes beachten:

Wenn die meisten aktuellen Anfragen gültige Tokens haben und das Verhältnis von PASSED zu FAILED_AUDIT- oder FAILED_ENFORCE-Ergebnissen für Ihren Anwendungsfall akzeptabel ist, sollten Sie die Erzwingung aktivieren.
Wenn die meisten der aktuellen Anfragen wahrscheinlich von veralteten Clients stammen, sollten Sie warten, bis weitere Nutzer ihre App aktualisiert haben, bevor Sie die Erzwingung aktivieren. Wenn Sie die Einbindung der Identity Platform in reCAPTCHA Enterprise erzwingen, funktionieren ältere App-Versionen, die nicht in reCAPTCHA Enterprise eingebunden sind, nicht.

So rufen Sie diese Messwerte auf:

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

Zum Metrics Explorer
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 reCAPTCHA-Erzwingung aktivieren, um Ihre Nutzer zu schützen. Sorgen Sie dafür, dass Sie bestehende Nutzer nicht unterbrechen, einschließlich Nutzern, die möglicherweise eine ältere Version Ihrer App verwenden.

Um die reCAPTCHA-Erzwingung für ein Projekt oder einen Mandanten zu aktivieren, führen Sie mit dem Admin SDK Folgendes aus:

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

reCAPTCHA Enterprise deaktivieren

Verwenden Sie zum Deaktivieren von reCAPTCHA Enterprise das Admin SDK und führen Sie Folgendes aus:

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

reCAPTCHA Enterprise-Ergebnisse mit Cloud Functions überschreiben

Neben dem Konfigurieren von Punktzahl-Schwellenwerten können Sie ein reCAPTCHA Enterprise-Ergebnis für ein bestimmtes Token überschreiben, indem Sie eine benutzerdefinierte Cloud Functions-Blockierfunktion verwenden. Dies ist hilfreich, wenn der reCAPTCHA-Wert für eine bestimmte Nutzeranmeldung niedrig sein kann, der Nutzer aber vertrauenswürdig ist oder auf andere Weise verifiziert wurde und die Anmeldung daher abschließen darf.

Weitere Informationen zum Konfigurieren von Blockierfunktionen mit reCAPTCHA Enterprise finden Sie unter Firebase Authentication durch blockierende Cloud Functions-Funktionen erweitern.

Fehlerbehebung

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

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

Alternativ können Nutzer auf Grundlage Ihrer aktuellen Konfiguration blockiert werden. Geben Sie Folgendes ein:

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