App Check mit reCAPTCHA v3 in Web-Apps aktivieren

Auf dieser Seite wird gezeigt, wie Sie App Check in einer Web-App mithilfe des integrierten reCAPTCHA v3-Anbieters aktivieren. Wenn Sie App Check aktivieren, tragen Sie dazu bei, dass nur Ihre App auf die Firebase-Ressourcen Ihres Projekts zugreifen kann. Sehen Sie sich eine Übersicht über diese Funktion an.

reCAPTCHA v3 ist ein kostenloser Dienst. App Check unterstützt auch reCAPTCHA Enterprise , einen kostenpflichtigen Dienst mit einem kostenlosen Kontingent. Informationen zu den Unterschieden zwischen reCAPTCHA v3 und reCAPTCHA Enterprise finden Sie im Funktionsvergleich .

Beachten Sie, dass reCAPTCHA v3 für Benutzer unsichtbar ist. Der reCAPTCHA v3-Anbieter fordert die Benutzer zu keinem Zeitpunkt auf, eine Herausforderung zu lösen. Weitere Informationen finden Sie in der reCAPTCHA v3-Dokumentation .

Wenn Sie App Check mit Ihrem eigenen benutzerdefinierten Anbieter verwenden möchten, finden Sie weitere Informationen unter Implementieren eines benutzerdefinierten App Check-Anbieters .

1. Richten Sie Ihr Firebase-Projekt ein

  1. Fügen Sie Ihrem JavaScript-Projekt Firebase hinzu, falls Sie dies noch nicht getan haben.

  2. Registrieren Sie Ihre Website für reCAPTCHA v3 und erhalten Sie Ihren reCAPTCHA v3-Websiteschlüssel und Ihren geheimen Schlüssel.

  3. Registrieren Sie Ihre Apps für die Verwendung von App Check beim reCAPTCHA-Anbieter im App Check- Bereich der Firebase-Konsole. Sie müssen den geheimen Schlüssel angeben, den Sie im vorherigen Schritt erhalten haben.

    Normalerweise müssen Sie alle Apps Ihres Projekts registrieren, denn sobald Sie die Erzwingung für ein Firebase-Produkt aktivieren, können nur registrierte Apps auf die Back-End-Ressourcen des Produkts zugreifen.

  4. Optional : Legen Sie in den App-Registrierungseinstellungen eine benutzerdefinierte Gültigkeitsdauer (Time-to-Live, TTL) für vom Anbieter ausgestellte App Check-Token fest. Sie können die TTL auf einen beliebigen Wert zwischen 30 Minuten und 7 Tagen einstellen. Beachten Sie beim Ändern dieses Werts die folgenden Kompromisse:

    • Sicherheit: Kürzere TTLs bieten mehr Sicherheit, da sie das Fenster verkleinern, in dem ein durchgesickertes oder abgefangenes Token von einem Angreifer missbraucht werden kann.
    • Leistung: Kürzere TTLs bedeuten, dass Ihre App die Bestätigung häufiger durchführt. Da der App-Bestätigungsprozess bei jeder Ausführung Latenz für Netzwerkanforderungen hinzufügt, kann eine kurze TTL die Leistung Ihrer App beeinträchtigen.
    • Kontingent und Kosten: Kürzere TTLs und häufige Neubescheinigungen erschöpfen Ihr Kontingent schneller und kosten bei kostenpflichtigen Diensten möglicherweise mehr. Siehe Kontingente und Limits .

    Die Standard-TTL von 1 Tag ist für die meisten Apps angemessen. Beachten Sie, dass die App Check-Bibliothek Token bei etwa der Hälfte der TTL-Dauer aktualisiert.

2. Fügen Sie Ihrer App die App Check-Bibliothek hinzu

Fügen Sie Ihrer Web-App Firebase hinzu, falls Sie dies noch nicht getan haben. Stellen Sie sicher, dass Sie die App Check-Bibliothek importieren.

3. App-Check initialisieren

Fügen Sie Ihrer Anwendung den folgenden Initialisierungscode hinzu, bevor Sie auf Firebase-Dienste zugreifen. Sie müssen Ihren reCAPTCHA- Site-Schlüssel übergeben, den Sie in der reCAPTCHA-Konsole erstellt haben, um activate() zu aktivieren.

Web version 9

const { initializeApp } = require("firebase/app");
const { initializeAppCheck, ReCaptchaV3Provider } = require("firebase/app-check");

const app = initializeApp({
  // Your firebase configuration object
});

// Pass your reCAPTCHA v3 site key (public key) to activate(). Make sure this
// key is the counterpart to the secret key you set in the Firebase console.
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaV3Provider('abcdefghijklmnopqrstuvwxy-1234567890abcd'),

  // Optional argument. If true, the SDK automatically refreshes App Check
  // tokens as needed.
  isTokenAutoRefreshEnabled: true
});

Web version 8

firebase.initializeApp({
  // Your firebase configuration object
});

const appCheck = firebase.appCheck();
// Pass your reCAPTCHA v3 site key (public key) to activate(). Make sure this
// key is the counterpart to the secret key you set in the Firebase console.
appCheck.activate(
  'abcdefghijklmnopqrstuvwxy-1234567890abcd',

  // Optional argument. If true, the SDK automatically refreshes App Check
  // tokens as needed.
  true);

Sobald die App Check-Bibliothek in Ihrer App installiert ist, stellen Sie sie bereit.

Die aktualisierte Client-App beginnt mit dem Senden von App-Check-Tokens zusammen mit jeder Anfrage, die sie an Firebase sendet, aber Firebase-Produkte verlangen nicht, dass die Tokens gültig sind, bis Sie die Erzwingung im Abschnitt „App-Check“ der Firebase-Konsole aktivieren. Einzelheiten finden Sie in den nächsten beiden Abschnitten.

4. Überwachen Sie Anforderungsmetriken

Jetzt, da Ihre aktualisierte App in den Händen der Benutzer ist, können Sie die Erzwingung von App Check für die von Ihnen verwendeten Firebase-Produkte aktivieren. Bevor Sie dies tun, sollten Sie jedoch sicherstellen, dass dadurch Ihre bestehenden legitimen Benutzer nicht gestört werden.

Echtzeitdatenbank, Cloud Firestore und Cloud Storage

Ein wichtiges Tool, das Sie verwenden können, um diese Entscheidung für Realtime Database, Cloud Firestore und Cloud Storage zu treffen, ist der Bildschirm „App Check Request Metrics“.

Um die App Check-Anfragemetriken für ein Produkt anzuzeigen, öffnen Sie den App Check- Abschnitt der Firebase-Konsole. Zum Beispiel:

Screenshot der Seite „App Check-Metriken“.

Die Anforderungsmetriken für jedes Produkt sind in vier Kategorien unterteilt:

  • Verifizierte Anfragen sind solche, die über ein gültiges App Check-Token verfügen. Nachdem Sie die App Check-Erzwingung aktiviert haben, sind nur Anfragen in dieser Kategorie erfolgreich.

  • Veraltete Clientanforderungen sind solche, denen ein App Check-Token fehlt. Diese Anfragen stammen möglicherweise von einer älteren Version des Firebase SDK, bevor App Check in die App aufgenommen wurde.

  • Unbekannte Ursprungsanfragen sind solche, denen ein App Check-Token fehlt und die nicht so aussehen, als kämen sie vom Firebase SDK. Diese können von Anfragen stammen, die mit gestohlenen API-Schlüsseln oder gefälschten Anfragen ohne das Firebase SDK gestellt wurden.

  • Ungültige Anforderungen sind solche mit einem ungültigen App Check-Token, das möglicherweise von einem nicht authentischen Client stammt, der versucht, sich als Ihre App auszugeben, oder von emulierten Umgebungen.

Die Verteilung dieser Kategorien für Ihre App sollte Aufschluss darüber geben, wann Sie sich entscheiden, die Erzwingung zu aktivieren. Hier sind einige Richtlinien:

  • Wenn fast alle der letzten Anfragen von verifizierten Clients stammen, sollten Sie erwägen, die Erzwingung zu aktivieren, um mit dem Schutz Ihrer Back-End-Ressourcen zu beginnen.

  • Wenn ein erheblicher Teil der letzten Anfragen von wahrscheinlich veralteten Clients stammt, sollten Sie warten, bis mehr Benutzer Ihre App aktualisieren, bevor Sie die Erzwingung aktivieren, um Benutzer nicht zu stören. Durch das Erzwingen von App Check für eine veröffentlichte App werden frühere App-Versionen beschädigt, die nicht in das App Check SDK integriert sind.

  • Wenn Ihre App noch nicht gestartet wurde, sollten Sie die App-Check-Erzwingung sofort aktivieren, da keine veralteten Clients verwendet werden.

Cloud-Funktionen

Für Cloud Functions können Sie App Check-Metriken abrufen, indem Sie die Protokolle Ihrer Funktionen untersuchen. Jeder Aufruf einer aufrufbaren Funktion gibt einen strukturierten Protokolleintrag wie im folgenden Beispiel aus:

{
  "severity": "INFO",    // INFO, WARNING, or ERROR
  "logging.googleapis.com/labels": {"firebase-log-type": "callable-request-verification"},
  "jsonPayload": {
    "message": "Callable header verifications passed.",
    "verifications": {
      // ...
      "app": "MISSING",  // VALID, INVALID, or MISSING
    }
  }
}

Sie können diese Messwerte in der Google Cloud Console analysieren, indem Sie einen protokollbasierten Zählermesswert mit dem folgenden Messwertfilter erstellen:

resource.type="cloud_function"
resource.labels.function_name="YOUR_CLOUD_FUNCTION"
resource.labels.region="us-central1"
labels.firebase-log-type="callable-request-verification"

Beschriften Sie die Metrik mit dem Feld jsonPayload.verifications.appCheck .

5. Erzwingung aktivieren

Befolgen Sie zum Aktivieren der Erzwingung die nachstehenden Anweisungen für jedes Produkt. Sobald Sie die Erzwingung für ein Produkt aktivieren, werden alle unbestätigten Anfragen an dieses Produkt abgelehnt.

Echtzeitdatenbank, Cloud Firestore und Cloud Storage

So aktivieren Sie die Erzwingung für Realtime Database, Cloud Firestore (iOS und Android) und Cloud Storage:

  1. Öffnen Sie den App Check- Bereich der Firebase-Konsole.

  2. Erweitern Sie die Metrikansicht des Produkts, für das Sie die Erzwingung aktivieren möchten.

  3. Klicken Sie auf Erzwingen und bestätigen Sie Ihre Auswahl.

Beachten Sie, dass es bis zu 15 Minuten dauern kann, nachdem Sie die Erzwingung aktiviert haben, bis sie wirksam wird.

Cloud-Funktionen

Siehe Durchsetzung der App-Prüfung für Cloud Functions aktivieren .

Nächste Schritte

Wenn Sie Ihre App nach der Registrierung für App Check in einer Umgebung ausführen möchten, die App Check normalerweise nicht als gültig einstufen würde, z. B. lokal während der Entwicklung oder in einer Continuous Integration (CI)-Umgebung, können Sie diese erstellen ein Debugbuild Ihrer App, der den App Check-Debuganbieter anstelle eines echten Nachweisanbieters verwendet.

Siehe Verwenden von App Check mit dem Debug-Anbieter in Web-Apps .