firebase-app-check

Firebase App Check 技能

此技能介绍如何在 Flutter 应用中正确实现 Firebase App Check，涵盖提供方选择、调试配置、强制执行的逐步启用，以及安全加固。

适用场景

以下情况可使用此技能：

• 在 Flutter 项目中设置并启用 Firebase App Check。
• 为各个平台选择合适的证明提供方。
• 为开发、测试和 CI 配置调试提供方。
• 启用强制执行并监控 App Check 指标。
• 实现令牌刷新处理和自定义 TTL 配置。

---

1. 设置和配置

flutter pub add firebase_app_check

import 'package:firebase_app_check/firebase_app_check.dart';

在 Firebase.initializeApp() 之后、使用任何 Firebase 服务之前初始化 App Check：

await Firebase.initializeApp();
await FirebaseAppCheck.instance.activate(
  webProvider: ReCaptchaV3Provider('recaptcha-v3-site-key'),
  androidProvider: AndroidProvider.playIntegrity,
  appleProvider: AppleProvider.deviceCheck,
);

设置检查清单

1. 在 Firebase 控制台的 Project Settings > App Check 下注册应用。
2. 对于 Web，从 Firebase 控制台获取 reCAPTCHA v3 站点密钥。
3. 确认 App Check 已完成激活，然后再调用 Firestore、Storage 或 RTDB。
4. 考虑设置自定义 TTL——TTL 越短，安全性越高，但配额消耗也越快。

Apple 平台上的原生 FirebaseApp.configure()

避免在 AppDelegate 中原生调用 FirebaseApp.configure()——Firebase.initializeApp() 已配置好原生默认应用。如果必须调用，请在 configure() 之前安装 AppCheckProviderFactory；否则，Apple SDK 会在实体设备上锁定使用 DeviceCheck，并静默忽略传递给 activate() 的 appleProvider（包括 AppleProvider.debug）。这个问题很容易被忽略，因为模拟器默认已使用调试提供方。Android 上的 activate() 不受影响。请参阅 flutterfire#18613。

---

2. 提供方选择

Android：

提供方	使用场景
AndroidProvider.playIntegrity	生产环境（默认）
AndroidProvider.debug	仅限开发 / CI

Apple（iOS / macOS）：

提供方	使用场景
AppleProvider.deviceCheck	生产环境默认选项（iOS 11+、macOS 10.15+）
AppleProvider.appAttest	增强安全性（iOS 14+、macOS 14+）
AppleProvider.appAttestWithDeviceCheckFallback	App Attest，并在需要时回退到 Device Check
AppleProvider.debug	仅限开发 / CI

Web：

提供方	使用场景
ReCaptchaV3Provider	标准 reCAPTCHA v3
ReCaptchaEnterpriseProvider	提供更多功能的增强选项

**Android 注意事项：**对于某些 Android 设备，请在 Google Play 控制台中启用“满足基本设备完整性”，以确保 App Check 正常运行。

---

3. 开发和测试

在开发期间使用调试提供方，以便在模拟器或 CI 环境中运行：

await Firebase.initializeApp();
await FirebaseAppCheck.instance.activate(
  androidProvider: AndroidProvider.debug,
  appleProvider: AppleProvider.debug,
);

平台专属调试设置

iOS：在 Xcode 的“启动时传递的参数”中添加 -FIRDebugEnabled，以启用调试日志。调试令牌会显示在控制台输出中。在实体设备上，如果 AppDelegate 原生调用了 FirebaseApp.configure()，则会忽略 AppleProvider.debug——请参阅“设置和配置”中的原生 configure() 说明。

**Android：**首次运行时，调试令牌会输出到 logcat。请按 DebugAppCheckProvider 进行筛选。

**Web：**在 Firebase 脚本加载之前，于 web/index.html 中设置 self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;。

注册调试令牌

1. 从设备 / 模拟器的控制台输出中复制调试令牌。
2. 在 Firebase 控制台中，前往 App Check > Apps > Manage debug tokens。
3. 添加令牌。该令牌会立即在对应应用中生效。

自定义后端的令牌监听器

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

• 绝不要在生产版本中使用调试提供方或分享调试令牌。
• 妥善保管调试令牌——不要将其提交到公共代码仓库。
• 如果调试令牌泄露，请立即在 Firebase 控制台中撤销。

---

4. 执行强制措施的上线步骤

按以下顺序操作，避免影响正常用户：

1. 部署 App Check 激活代码到所有应用版本。
2. 监控 Firebase 控制台中的 App Check 指标——等到大部分流量都显示有效令牌。
3. 逐步启用强制措施，从非关键 Firebase 服务开始（例如，先对 Cloud Storage 启用，再对 Firestore 启用）。
4. 验证未验证请求的比例降至接近零后，再对关键服务启用强制措施。

• 启用强制措施后，只有使用有效 App Check 令牌的应用才能访问受保护的 Firebase 资源。
• 将 App Check 与 Firebase Security Rules 结合使用，构建纵深防御。
• 针对 App Check 验证失败实现适当的错误处理——向用户显示易于理解的消息，而不是原始错误。

---

5. 安全最佳实践

• 启用 App Check 后，切勿在生产构建中将其禁用。
• 为 App Check 验证失败实现回退机制（例如，使用指数退避重试）。
• 定期查看 App Check 指标，以识别潜在的滥用模式。
• App Check 令牌会在 TTL 时长的大约一半处自动刷新。
• 对于安全性要求较高的应用，请使用实际可行的最短 TTL。
• 使用 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);

---

参考资料

• Firebase App Check Flutter 文档
• Firebase App Check 调试提供程序