Skip to content

evanca/flutter-ai-rules / skills/firebase-app-check

firebase-app-check

Verified

Use when implementing app attestation, configuring App Check providers, setting up debug tokens, enabling backend enforcement, or managing token refresh.

FileKindSize
SKILL.mdskill md6.5 KB
---
name: firebase-app-check
description: "Use when implementing app attestation, configuring App Check providers, setting up debug tokens, enabling backend enforcement, or managing token refresh."
license: MIT
---

# Firebase App Check Skill

This skill defines how to correctly implement Firebase App Check in Flutter applications, covering provider selection, debug configuration, enforcement rollout, and security hardening.

## When to Use

Use this skill when:

* Setting up and activating Firebase App Check in a Flutter project.
* Selecting the right attestation provider for each platform.
* Configuring debug providers for development, testing, and CI.
* Enabling enforcement and monitoring App Check metrics.
* Implementing token refresh handling and custom TTL configuration.

---

## 1. Setup and Configuration

```
flutter pub add firebase_app_check
```

```dart
import 'package:firebase_app_check/firebase_app_check.dart';
```

Initialize App Check **after** `Firebase.initializeApp()` and **before** using any Firebase services:

```dart
await Firebase.initializeApp();
await FirebaseAppCheck.instance.activate(
  providerWeb: ReCaptchaV3Provider('recaptcha-v3-site-key'),
  providerAndroid: AndroidPlayIntegrityProvider(),
  providerApple: AppleDeviceCheckProvider(),
);
```

### Setup Checklist

1. Register apps in the Firebase console under **Project Settings > App Check**.
2. For web, obtain a reCAPTCHA v3 site key from the Firebase console.
3. Confirm activation completes before any Firestore, Storage, or RTDB calls.
4. Consider setting a custom **TTL** — shorter TTLs are more secure but consume quota faster.

### Native `FirebaseApp.configure()` on Apple Platforms

Avoid calling `FirebaseApp.configure()` natively in your `AppDelegate` — `Firebase.initializeApp()` already configures the native default app. If you must call it, install your `AppCheckProviderFactory` **before** `configure()`; otherwise the Apple SDK locks in `DeviceCheck` on physical devices and the `providerApple` passed to `activate()` (including `AppleDebugProvider`) is silently ignored. This is easiest to miss because simulators already default to the debug provider. `activate()` on Android is unaffected. See [flutterfire#18613](https://github.com/firebase/flutterfire/issues/18613).

---

## 2. Provider Selection

**Android:**
| Provider | Use case |
|---|---|
| `AndroidPlayIntegrityProvider()` | Production (default) |
| `AndroidDebugProvider()` | Development / CI only |

**Apple (iOS / macOS):**
| Provider | Use case |
|---|---|
| `AppleDeviceCheckProvider()` | Production default (iOS 11+, macOS 10.15+) |
| `AppleAppAttestProvider()` | Enhanced security (iOS 14+, macOS 14+) |
| `AppleAppAttestWithDeviceCheckFallbackProvider()` | App Attest with Device Check fallback |
| `AppleDebugProvider()` | Development / CI only |

**Web:**
| Provider | Use case |
|---|---|
| `ReCaptchaV3Provider` | Standard reCAPTCHA v3 |
| `ReCaptchaEnterpriseProvider` | Enhanced with additional features |

> **Android note:** For certain Android devices, enable "Meets basic device integrity" in the Google Play console to ensure proper App Check functionality.

---

## 3. Development and Testing

Use debug providers during development to run in emulators or CI environments:

```dart
await Firebase.initializeApp();
await FirebaseAppCheck.instance.activate(
  providerAndroid: AndroidDebugProvider(),
  providerApple: AppleDebugProvider(),
);
```

To use a registered debug token (for example in CI), pass it by name:

```dart
providerAndroid: AndroidDebugProvider(debugToken: 'your-debug-token'),
providerApple: AppleDebugProvider(debugToken: 'your-debug-token'),
```

### Platform-Specific Debug Setup

**iOS:** Enable debug logging by adding `-FIRDebugEnabled` to Arguments Passed on Launch in Xcode. The debug token appears in the console output. On **physical devices**, `AppleDebugProvider` is ignored if your `AppDelegate` calls `FirebaseApp.configure()` natively — see the native `configure()` note in Setup and Configuration.

**Android:** The debug token prints to logcat on first run. Filter by `DebugAppCheckProvider`.

**Web:** Set `self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;` in `web/index.html` before Firebase scripts load.

### Register Debug Tokens

1. Copy the debug token from the device/emulator console output.
2. In the Firebase console, navigate to **App Check > Apps > Manage debug tokens**.
3. Add the token. It is immediately active for that app.

### Token Listener for Custom Backends

```dart
FirebaseAppCheck.instance.onTokenChange.listen((token) {
  // Attach token to custom backend requests
  // e.g., set as Authorization header
});
```

- **Never** use debug providers or share debug tokens in production builds.
- Keep debug tokens private — do not commit them to public repositories.
- Revoke compromised debug tokens immediately from the Firebase console.

---

## 4. Enforcement Rollout

Follow this sequence to avoid disrupting legitimate users:

1. **Deploy** App Check activation code to all app versions.
2. **Monitor** App Check metrics in the Firebase console — wait until most traffic shows valid tokens.
3. **Enable enforcement** gradually, starting with non-critical Firebase services (e.g., Cloud Storage before Firestore).
4. **Verify** that unverified request percentage drops to near zero before enforcing on critical services.

- Once enforcement is enabled, only apps with valid App Check tokens can access protected Firebase resources.
- Use App Check **in combination with** Firebase Security Rules for defense in depth.
- Implement proper error handling for App Check verification failures — surface a user-friendly message rather than a raw error.

---

## 5. Security Best Practices

- Never disable App Check in production builds once enabled.
- Implement a fallback mechanism for App Check verification failures (e.g., retry with exponential backoff).
- Regularly review App Check metrics to identify potential abuse patterns.
- App Check tokens are **automatically refreshed** at approximately half the TTL duration.
- For high-security applications, use the shortest practical TTL.
- Implement server-side verification for critical operations using the Firebase Admin SDK:

```
// Node.js Admin SDK example for verifying App Check tokens
const appCheckToken = req.header('X-Firebase-AppCheck');
const appCheckClaims = await getAppCheck().verifyToken(appCheckToken);
```

---

## References

- [Firebase App Check Flutter documentation](https://firebase.google.com/docs/app-check/flutter/default-providers)
- [Firebase App Check debug provider](https://firebase.google.com/docs/app-check/flutter/debug-provider)
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall