Firexport / Blog

Jeder App Check-Fehler entsteht in einem von zwei Schritten: wenn Ihre App bei ihrem Attestierungsanbieter (Play Integrity, App Attest, reCAPTCHA) ein Token abruft oder wenn ein Firebase-Dienst dieses Token prüft. Scheitert der erste Schritt, scheitert auch der zweite. Bleiben Sie deshalb nicht beim Fehler des Dienstes stehen: Suchen Sie zuerst den Fehler beim Token-Austausch und korrigieren Sie die registrierten Werte Ihrer Plattform. Emulatoren, Simulatoren und localhost können die Attestierung grundsätzlich nicht bestehen und verwenden deshalb ein Debug-Token.

Den fehlgeschlagenen Schritt an der Meldung erkennen

Wird kein Token abgerufen, tragen die Anfragen an den Dienst kein gültiges Token (das Web-SDK hängt stattdessen ein Platzhalter-Token an). Prüfen Sie deshalb auch bei einem Fehler auf der Seite des Dienstes zuerst, ob im Log zusätzlich ein Fehler beim Abrufen des Tokens steht. Nach einem Fehler schiebt das SDK neue Versuche auf: im Web 24 Stunden nach einem 403 oder 404, unter Android und Apple 24 Stunden nach einem 400 oder 404, bei anderen Fehlern bis zu 4 Stunden. Dieser Zustand liegt nur im Speicher. Starten Sie die App nach dem Korrigieren der Einrichtung deshalb neu oder laden Sie die Seite neu, bevor Sie prüfen.

Debug-Token während der Entwicklung

Emulatoren und Simulatoren gelten nicht als gültige Geräte, und Debug-Builds, die nicht zu Google Play hochgeladen wurden, bestehen Play Integrity nicht. Grundsätzlich gehört localhost nicht in einen reCAPTCHA-Schlüssel. In diesen Umgebungen schalten Sie den Debug-Anbieter ein und registrieren das Token, das im Log erscheint, in der Console.

1. Schalten Sie den Debug-Anbieter nur in Entwicklungs-Builds ein.

   // Android (Kotlin): com.google.firebase:firebase-appcheck-debug
   Firebase.appCheck.installAppCheckProviderFactory(
       if (BuildConfig.DEBUG) DebugAppCheckProviderFactory.getInstance()
       else PlayIntegrityAppCheckProviderFactory.getInstance(),
   )
   
   // iOS (Swift): before FirebaseApp.configure()
   #if DEBUG
   AppCheck.setAppCheckProviderFactory(AppCheckDebugProviderFactory())
   #endif
   
   // Web: before initializeAppCheck(), in development builds only
   self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   
   // Flutter (firebase_app_check 0.5+)
   await FirebaseAppCheck.instance.activate(
     providerAndroid: kDebugMode
         ? const AndroidDebugProvider()
         : const AndroidPlayIntegrityProvider(),
     providerApple: kDebugMode
         ? const AppleDebugProvider()
         : const AppleAppAttestWithDeviceCheckFallbackProvider(),
   );

2. Starten Sie die App und suchen Sie das Debug-Token im Log. Aktuelle SDKs geben es im Format Firebase App Check debug token: <UUID> aus (unter Android in logcat, bei Apple in der Xcode-Konsole, im Web in der Browserkonsole).
3. Registrieren Sie das Token. Öffnen Sie in der Firebase Console App Check, wechseln Sie zum Tab „Apps“ und wählen Sie im ⋮-Menü der App „Debug-Tokens verwalten“ (Manage debug tokens). Pro App lassen sich bis zu 20 registrieren.

• Tokens ändern sich. Ein neues entsteht, wenn Sie unter Android die App-Daten löschen oder die App neu installieren, bei Apple die App neu installieren und im Web ein anderes Browserprofil verwenden oder die Websitedaten löschen. Das neue Token müssen Sie erneut registrieren.
• Übergeben Sie in CI ein bereits registriertes Token. Im Web ist das der Token-String in self.FIREBASE_APPCHECK_DEBUG_TOKEN, unter Android das Instrumentierungsargument firebaseAppCheckDebugSecret, bei Apple die Umgebungsvariable AppCheckDebugToken im Schema und in Flutter der Parameter debugToken.
• Behandeln Sie das Token wie ein Passwort. Übertragen Sie es nicht ins Repository, und halten Sie den Debug-Anbieter und das Token aus Produktions-Builds heraus.

Ursachen nach Plattform

Android (Play Integrity)

Apple (App Attest, DeviceCheck)

Web (reCAPTCHA)

AI Logic: automatische Erzwingung seit dem 2. November 2026

Seit dem 2. November 2026 erzwingt Firebase App Check für Firebase AI Logic automatisch in den Projekten, die es bisher nicht erzwungen haben. Anfragen ohne gültiges Token werden blockiert, ebenso die von App-Versionen, die ohne App Check veröffentlicht wurden. Zwei Fehler von AI Logic nennen App Check.

403 PERMISSION_DENIED: To access this model, you must enforce
Firebase App Check.

403 PERMISSION_DENIED: Firebase AI Logic has been deactivated in this
project. To resume using Firebase AI Logic, you must enforce Firebase
App Check.

• Der erste bedeutet, dass ohne gültiges App Check-Token ein häufig missbrauchtes Modell aufgerufen wurde. Richten Sie App Check ein und erzwingen Sie es. In der Entwicklung verwenden Sie den Debug-Anbieter.
• Der zweite bedeutet, dass das Projekt als inaktiv eingestuft wurde und App Check nicht erzwingt. Erzwingen Sie es bereits und erscheint der Fehler trotzdem, prüfen Sie den Replay-Schutz (replay protection): Ist er eingeschaltet, auch im Modus „Monitor only“, werden nur Tokens mit eingeschränkter Nutzung (limited-use tokens) anerkannt.

Sind Versionen ohne App Check noch bei Nutzern im Einsatz, können Sie die Erzwingung aufschieben. Dazu ändern Sie auf dem Tab „APIs“ von App Check in der Zeile von Firebase AI Logic das Datum bei „Erzwingt“ (Enforces); der 21. Januar 2027 ist der letztmögliche Termin. Steht in der Zeile bereits „Erzwungen“ (Enforced), ändern Sie das Datum und setzen danach unter „Einrichten“ (Set up) in dieser Zeile den „Basisschutz“ (Baseline protection) auf „Unenforced (monitoring only)“ und den Replay-Schutz auf „Disabled“; erst dann ist die Erzwingung aufgehoben. Google rät davon ab. Veröffentlichen Sie deshalb vor diesem Termin eine Version mit App Check.

Bevor Sie es für andere Dienste erzwingen

• Sehen Sie sich zuerst die Messwerte an. Der Tab „APIs“ von App Check teilt die Anfragen jedes Dienstes in bestätigte Anfragen (Verified), veraltete Clientanfragen (Outdated client, ohne Token), Anfragen unbekannten Ursprungs (Unknown origin) und ungültige Anfragen (Invalid) auf. Ist App Check erzwungen, kommen nur bestätigte Anfragen durch. Erzwingen Sie es also, wenn fast alle aktuellen Anfragen bestätigt sind.
• Alte App-Versionen werden blockiert. Bei Versionen ohne das App Check SDK werden die Anfragen abgewiesen, sobald Sie die Erzwingung einschalten.
• Bis zur Wirkung vergehen bis zu 15 Minuten. Beurteilen Sie das Ergebnis nicht direkt nach dem Einschalten.
• In Cloud Functions lässt sich App Check nur für aufrufbare Funktionen erzwingen. Wirksam wird es erst, wenn Sie enforceAppCheck: true ergänzen und die Funktion neu bereitstellen. onRequest-Funktionen fallen nicht unter die Erzwingung von App Check, deshalb müssen Sie das Token dort selbst mit dem Admin SDK prüfen.

Quellen

• Überblick über App Check, Erzwingung aktivieren, Messwerte überwachen, Limit für Debug-Tokens (REST)
• Play Integrity-Anbieter, Play Integrity-Kontingent, Debug-Anbieter für Android
• App Attest-Anbieter, DeviceCheck-Anbieter, Debug-Anbieter für Apple, App Attest-Umgebung (Apple), wo App Attest verfügbar ist (Apple)
• reCAPTCHA Enterprise-Anbieter, reCAPTCHA v3-Anbieter, reCAPTCHA-Schlüssel erstellen, Debug-Anbieter für das Web
• Debug-Anbieter für Flutter, activate() in firebase_app_check
• App Check für AI Logic, Fehlercodes von AI Logic, App Check für Cloud Functions, Tokens im eigenen Backend prüfen
• SDK-Quellcode: Drosselung im Web, Platzhalter-Token im Web, Ablehnung durch Storage, Android-Fehlermeldung, Wiederholungen unter Android, Wiederholungen bei Apple, Ablehnung durch aufrufbare Funktionen