Identity Platform in die reCAPTCHA Enterprise API einbinden

In diesem Dokument wird beschrieben, wie Sie die Identity Platform-Integration mit der reCAPTCHA Enterprise API verwenden, um die Sicherheit für Ihre Nutzer zu erhöhen. Diese Funktion macht Ihre App widerstandsfähiger gegen Spam, Missbrauch und andere betrügerische Aktivitäten.

Die Integration erstellt in Ihrem Namen eine reCAPTCHA Enterprise-Bewertung, um Nutzeranfragen zu validieren. Preisinformationen finden Sie unter reCAPTCHA-Preise.

Übersicht

Wenn Sie die Identity Platform-Integration mit der reCAPTCHA Enterprise API einrichten, aktivieren Sie die Standard-Schutzfunktion von reCAPTCHA – den reCAPTCHA-Bot-Schutz. Mit dem Bot-Schutz stellt die Identity Platform in Ihrem Namen punktbasierte reCAPTCHA-Schlüssel in Ihrem Projekt bereit. Wenn ein Nutzer über einen der folgenden Vorgänge auf Ihre App oder Website zugreift, lädt das Client-SDK reCAPTCHA, wenn der entsprechende Anbieter aktiviert ist.

Anbieter Vorgang Methode
passwordProvider Anmeldung mit E‑Mail-Adresse und Passwort signInWithPassword
Registrierung mit E‑Mail-Adresse und Passwort signUpPassword
Anmeldung per E‑Mail-Link getOobCode
Passwortzurücksetzung getOobCode
phoneProvider Registrierung oder Anmeldung mit Telefonnummer sendVerificationCode
Registrierung der Telefonnummer für die MFA mfaSmsEnrollment
Anmeldung mit Telefonnummer für die MFA mfaSmsSignIn

reCAPTCHA stellt der Identity Platform dann Werte zur Verfügung, mit denen das Risiko der Anfrage basierend auf Ihrer Konfiguration und Risikotoleranz bewertet wird.

Weitere Informationen finden Sie unter Übersicht über reCAPTCHA.

Hinweis

Je nachdem, welchen Authentifizierungsablauf Sie mit reCAPTCHA schützen möchten, müssen Sie Folgendes einrichten:

Dienstkonto erstellen

Für die Integration der Identity Platform in die reCAPTCHA Enterprise API ist für jedes Projekt, in dem reCAPTCHA verwendet wird, ein Identity Platform-Dienstkonto erforderlich. Dadurch kann Identity Platform reCAPTCHA-Schlüssel in Ihrem Namen verwalten. Wenn Sie bereits ein Dienstkonto erstellt haben, gewähren Sie ihm Zugriff auf reCAPTCHA.

Wenn Sie noch kein Dienstkonto erstellt haben oder zusätzliche Projekte haben, die Sie mit reCAPTCHA schützen möchten, gehen Sie so vor:

  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:service-PROJECT_NUMBER@gcp-sa-identitytoolkit. \
    --role=roles/identitytoolkit.serviceAgent

    Ersetzen Sie Folgendes:

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

reCAPTCHA-Bot-Schutzverhalten nach Anbieter

Das Verhalten des reCAPTCHA-Botschutzes hängt vom konfigurierten Identitätsanbieter ab:

E‑Mail-Passwort-Anbieter

Für Authentifizierungsabläufe mit E-Mail-Adresse und Passwort unterstützt der reCAPTCHA-Bot-Schutz zwei Modi: Prüfen und Erzwingen.

Auditmodus

Wenn Sie die Erzwingung von E-Mail-Passwörtern auf den Prüfmodus festlegen, erstellt 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. Anhand der Messwerte, die im Prüfmodus ausgegeben werden, können Sie feststellen, ob Sie die reCAPTCHA-Erzwingung aktivieren sollten.

Erzwingungsmodus

Wenn Sie die E-Mail-Passwort-Erzwingung auf den erzwungenen Modus festlegen, erstellt die Identity Platform einen oder mehrere reCAPTCHA-Schlüssel in Ihrem Projekt, die zur Bewertung des Traffics zu Identity Platform APIs verwendet werden. API-Anfragen, die kein reCAPTCHA-Token enthalten, werden abgelehnt. Aktivieren Sie die Erzwingung erst, wenn Sie alle Ihre Clients zu einem SDK mit reCAPTCHA-Unterstützung migriert haben.

Bereitstellung der Smartphones

Wenn Sie den Bot-Schutz für Telefonauthentifizierungsabläufe aktivieren, indem Sie phoneEnforcementState auf ENFORCE und useSmsBotScore auf true setzen, verwendet die Identity Platform den reCAPTCHA-Bot-Schutz für die App-Überprüfung. Wenn die Anfrage eines Nutzers die Bot-Schutzprüfung besteht, wird ein SMS-Bestätigungscode gesendet. Wenn die Anfrage eines Nutzers die Bot-Schutzprüfung nicht besteht, blockiert Identity Platform die Anfrage und sendet keine SMS mit einem Bestätigungscode.

Eine Fallback-Bestätigung ist nicht erforderlich, wenn der Botschutz für Telefonauthentifizierungsabläufe aktiviert ist. Sie müssen keine zusätzlichen Bestätigungsmethoden für Ihre App einrichten. Wir empfehlen jedoch, die reCAPTCHA-Bestätigung für Web-Apps einzurichten, damit reCAPTCHA V2 verfügbar ist, wenn Sie den Botschutz deaktivieren.

Identity Platform-Integration mit der reCAPTCHA Enterprise API einrichten

So richten Sie die Identity Platform-Integration in die reCAPTCHA Enterprise API ein:

  • Verwenden Sie das Admin SDK, um den reCAPTCHA-Erzwingungsstatus festzulegen und den Bot-Schutz zu aktivieren.
  • Konfigurieren Sie das Client-SDK für die Plattform Ihrer App.

Für Authentifizierungsabläufe mit E-Mail-Adresse und Passwort empfehlen wir, zuerst die reCAPTCHA-Erzwingung im Prüfmodus zu aktivieren und die von Ihrem Projekt ausgegebenen reCAPTCHA-Messwerte zu beobachten. So vermeiden Sie Unterbrechungen des Nutzertraffics, während Sie prüfen, ob die Authentifizierungsabläufe geschützt sind. Nachdem Sie überprüft haben, ob Ihre Authentifizierungsabläufe geschützt sind, legen Sie den Botschutz auf ENFORCE fest. Aktivieren Sie für die Telefonauthentifizierung den Botschutz, indem Sie phoneEnforcementState auf ENFORCE und useSmsBotScore auf true setzen. Behalten Sie die reCAPTCHA-Messwerte im Auge, um die Grenzwerte für die Punktzahl anzupassen.

reCAPTCHA-Bot-Schutz aktivieren

E‑Mail-Passwort-Anbieter

So aktivieren Sie den reCAPTCHA-Botschutz für E-Mail-Passwort-Authentifizierungsabläufe:

  1. Aktivieren Sie die reCAPTCHA Enterprise API für Ihr Projekt, falls noch nicht geschehen.

  2. Verwenden Sie das Admin SDK, um den Botschutz für ein Projekt zu aktivieren. Die reCAPTCHA-Unterstützung ist in den Node.js Admin SDK-Versionen 11.7.0 und höher verfügbar.

    Beispiel:

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

    Ersetzen Sie Folgendes:

    • ENFORCE_MODE: Der Modus, den Sie für die Erzwingung der reCAPTCHA-E-Mail-Passwort-Authentifizierung festlegen möchten. Gültige Werte sind OFF, AUDIT und ENFORCE. Wenn Sie den Botschutz aktivieren möchten, muss dieser Parameter auf AUDIT oder ENFORCE festgelegt sein. Wenn Sie den Botschutz zum ersten Mal aktivieren, empfehlen wir, diesen Parameter auf AUDIT zu setzen und dafür zu sorgen, dass Ihre Authentifizierungsabläufe geschützt sind, bevor Sie ihn auf ENFORCE setzen. Weitere Informationen zur Funktionsweise der Modi finden Sie unter reCAPTCHA-Bot-Schutzverhalten nach Anbieter.
    • END_SCORE: Der niedrigste Bot-Schutz-Bewertungswert, den eine Anfrage haben kann, bevor sie fehlschlägt. Sie können diesen Wert auf einen Wert zwischen 0.0 und 1.0 festlegen. Wenn Sie beispielsweise einen Schwellenwert von 0.6 festlegen, schlägt reCAPTCHA bei allen Anfragen mit einem Wert von 0.5 oder niedriger fehl. Je höher Sie den Wert festlegen, desto strenger sind die Regeln.

    Sie können den Botschutz auch mit derselben Konfigurationsmethode für einen Mandanten über das Admin SDK aktivieren. Weitere Informationen zum Aktualisieren eines Mandanten finden Sie unter Mandanten aktualisieren.

  3. Wenn Sie Identity Platform unter iOS oder Android verwenden, müssen Sie Ihre App über die Firebase Console registrieren:

    Wenn Sie die 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.

      Zu Identity Platform

    2. Gehe zu den 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 reCAPTCHA-Schlüssels kann einige Minuten dauern.

  4. Wenn Sie die Erzwingung auf den Prüfmodus festgelegt haben, empfehlen wir, die reCAPTCHA-Messwerte für den Botschutz zu beobachten, um sicherzustellen, dass Ihre Abläufe geschützt sind.

Bereitstellung der Smartphones

So aktivieren Sie den reCAPTCHA-Bot-Schutz für SMS-basierte Authentifizierungsabläufe:

  1. Aktivieren Sie die reCAPTCHA Enterprise API für Ihr Projekt, falls noch nicht geschehen.

  2. Wenn Sie den Botschutz für ein Projekt aktivieren möchten, verwenden Sie das Admin SDK. Die reCAPTCHA-Unterstützung ist in den Node.js Admin SDK-Versionen 12.7.0 und höher verfügbar.

    Beispiel:

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

    Ersetzen Sie END_SCORE durch den niedrigsten Bot-Schutz-Bewertungswert, den eine Anfrage haben kann, bevor sie fehlschlägt. Sie können diesen Wert auf einen Wert zwischen 0.0 und 1.0 festlegen. Wenn Sie beispielsweise einen Schwellenwert von 0.6 festlegen, schlägt reCAPTCHA bei jeder Anfrage mit einem Wert von 0.5 oder niedriger fehl. Je höher Sie den Wert festlegen, desto strenger sind die Regeln.

    Wenn Sie phoneEnforcementState auf ENFORCE und useSmsBotScore auf true setzen, wird der Bot-Schutz für SMS-basierte Authentifizierungsabläufe aktiviert. Weitere Informationen zur Funktionsweise der Erzwingung durch Telefonanbieter finden Sie unter reCAPTCHA-Bot-Schutzverhalten nach Anbieter.

    Sie können den Botschutz auch mit derselben Konfigurationsmethode für einen Mandanten über das Admin SDK aktivieren. Weitere Informationen zum Aktualisieren eines Mandanten finden Sie unter Mandanten aktualisieren.

  3. Wenn Sie Identity Platform unter iOS oder Android verwenden, müssen Sie Ihre App über die Firebase Console registrieren:

    Wenn Sie die 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.

      Zu Identity Platform

    2. Gehe zu den 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 reCAPTCHA-Schlüssels kann einige Minuten dauern.

  4. Behalten Sie die reCAPTCHA-Messwerte für den Botschutz im Blick, 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 aktuelle Version des Web SDK.

    • Die reCAPTCHA-Unterstützung für die E-Mail- und Passwortauthentifizierung in Web-Apps ist in JavaScript SDK-Versionen ab 9.20.0 verfügbar.
    • Die reCAPTCHA-Unterstützung für die Telefonauthentifizierung in Web-Apps ist in JavaScript SDK-Versionen ab 11 verfügbar.

    Nachdem Sie das Web-SDK in Ihre App eingebunden haben, ruft das SDK automatisch Ihre reCAPTCHA-Konfiguration ab und aktiviert den Schutz für die von Ihnen konfigurierten Anbieter.

  2. Bei Bedarf können Sie das reCAPTCHA-Signal so abrufen:

    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. Aktualisieren Sie auf die aktuelle Version des Android SDK. Die reCAPTCHA-Unterstützung für die E-Mail- und Passwortauthentifizierung sowie die Telefonauthentifizierung in Android-Apps ist ab Android SDK-Version 23.1.0 verfügbar.

    Außerdem ist für die reCAPTCHA-Unterstützung API-Level 23 (Marshmallow) oder höher und Android 6 oder höher erforderlich.

    Nachdem Sie das Android SDK in Ihre App eingebunden haben, ruft das SDK automatisch Ihre reCAPTCHA-Konfiguration ab und aktiviert den Schutz für die von Ihnen konfigurierten Anbieter.

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

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

    Verwenden Sie die reCAPTCHA SDK-Version 18.5.1 oder höher.

  3. Bei Bedarf können Sie das reCAPTCHA-Signal so abrufen:

    • 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. Aktualisieren Sie auf die iOS SDK-Version 11.6.0 oder höher. Nachdem Sie das iOS SDK in Ihre App eingebunden haben, ruft das SDK automatisch Ihre reCAPTCHA-Konfiguration ab und aktiviert den Schutz für die von Ihnen konfigurierten Anbieter.

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

  3. Achten Sie darauf, dass -ObjC in Ihren Linker-Flags aufgeführt ist. Gehen Sie zu Target > Build Settings > All > Linking und prüfen Sie, ob für Other Linker Flags der Wert -ObjC angezeigt wird.

  4. Bei Bedarf können Sie das reCAPTCHA-Signal so abrufen:

    • Swift:
    // Initialize Firebase Authentication
try await Auth.auth().initializeRecaptchaConfig()
    • Objective-C:
    // Initialize Firebase Authentication
[[FIRAuth auth] initializeRecaptchaConfigWithCompletion:^(NSError * _Nullable error) {
  // Firebase Authentication initialization finished
}];

reCAPTCHA-Messwerte für den Bot-Schutz überwachen

Überwachen Sie die reCAPTCHA-Messwerte, die Ihr Projekt ausgibt, um sicherzustellen, dass die Authentifizierungsabläufe geschützt sind. Bei Authentifizierungsabläufen mit E‑Mail-Adresse und Passwort empfehlen wir, die Messwerte im Auditmodus zu beobachten, bevor Sie den Erzwingungsmodus aktivieren. Anhand dieser Messwerte können Sie beispielsweise feststellen, ob Sie die Identity Platform-Integration mit der reCAPTCHA Enterprise API richtig eingerichtet haben. Sie können Ihnen auch dabei helfen, den Schwellenwert für Ihren Nutzertraffic zu optimieren. Wenn die Bereitstellung des reCAPTCHA-Schlüssels fehlschlägt oder die erforderlichen Dienstkonten nicht erstellt wurden, sind reCAPTCHA-Authentifizierungsversuche weiterhin erfolgreich.

Prüfen Sie, ob die reCAPTCHA-Authentifizierung funktioniert. Sehen Sie sich dazu die folgenden Messwerte an, die Ihr Projekt an Cloud Monitoring sendet:

Weitere Informationen finden Sie unter reCAPTCHA-Messwerte überwachen.

reCAPTCHA-Bot-Schutz für E-Mail-Passwort-Abläufe erzwingen

Für Authentifizierungsabläufe mit E‑Mail-Adresse und Passwort, die Sie ursprünglich im Modus AUDIT konfiguriert haben, können Sie, nachdem Sie bestätigt haben, dass Ihre App akzeptablen Nutzertraffic empfängt, emailPasswordEnforcementState auf ENFORCE umstellen, um Anfragen zu blockieren, die die reCAPTCHA-Bewertung nicht bestehen. Achten Sie darauf, dass Sie bestehende Nutzer nicht beeinträchtigen, einschließlich Nutzer, die möglicherweise eine ältere Version Ihrer App verwenden.

Wenn Sie die reCAPTCHA-Erzwingung für E-Mail-Passwort-Authentifizierungsabläufe in einem Projekt oder Mandanten aktivieren möchten, führen Sie mit dem Admin SDK den folgenden Code aus:

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

reCAPTCHA-Bot-Schutz deaktivieren

E‑Mail-Passwort-Anbieter

Führen Sie den folgenden Befehl mit dem Admin SDK aus, um den Botschutz für Authentifizierungsabläufe mit E-Mail-Adresse und Passwort zu deaktivieren:

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

Bereitstellung der Smartphones

Wenn Sie den gesamten reCAPTCHA-Schutz für Smartphones, einschließlich des Bot-Schutzes, für SMS-basierte Authentifizierungsabläufe deaktivieren möchten, führen Sie mit dem Admin SDK den folgenden Befehl aus:

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

Wenn Sie auch reCAPTCHA SMS Defense verwenden und es aktiviert lassen möchten, während Sie den Bot-Schutz deaktivieren, setzen Sie useSmsBotScore auf false und lassen Sie phoneEnforcementState auf ENFORCE gesetzt:

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

reCAPTCHA-Bewertungen mit Cloud Run-Funktionen überschreiben

Zusätzlich zur Konfiguration von Bewertungsschwellenwerten können Sie ein reCAPTCHA-Urteil für ein bestimmtes Token überschreiben, indem Sie Blockierfunktionen verwenden, um Abläufe basierend auf benutzerdefinierten Faktoren zuzulassen oder zu blockieren. Das ist hilfreich, wenn die reCAPTCHA-Punktzahl für eine bestimmte Nutzeranmeldung niedrig ist, der Nutzer aber vertrauenswürdig ist oder auf andere Weise verifiziert wurde und sich daher anmelden darf.

Im folgenden Beispiel wird gezeigt, wie Sie ein reCAPTCHA-Urteil mithilfe von Blockierfunktionen überschreiben:

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',
    }
  });

Nächste Schritte