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. ウェブでは、Firebase コンソールから reCAPTCHA v3 サイトキーを取得します。
3. 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	Device Check にフォールバックする App Attest
AppleProvider.debug	開発／CI 専用

ウェブ：

プロバイダー	用途
ReCaptchaV3Provider	標準の reCAPTCHA v3
ReCaptchaEnterpriseProvider	追加機能を備えた強化版

Android に関する注意： 一部の Android デバイスでは、App Check が適切に機能するよう、Google Play コンソールで「基本的なデバイスの整合性を満たす」を有効にしてください。

---

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 で絞り込んでください。

ウェブ： 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 サービス（例：Firestore より先に Cloud Storage）から始め、段階的に有効化します。
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 デバッグプロバイダー