Как предотвратить злоупотребление Gemini API с помощью Проверки приложений Firebase

Если вы вызываете API напрямую из мобильного или веб-приложения, он становится уязвим для несанкционированных клиентов. Если вы хотите напрямую вызывать Gemini API из мобильного или веб-приложения, вам нужно защитить его от злоупотреблений с помощью Firebase AI Logic и принудительного использования Firebase App Check. Если вы включите правило App Check, будут разрешены только входящие запросы, которые были проверены и признаны исходящими из вашего приложения и/или с устройства, целостность которого не нарушена.

Перейти к инструкциям по настройке

Firebase AI Logic предоставляет прокси-шлюз, который позволяет интегрировать Firebase App Check и защищать Gemini API при прямом вызове из мобильных и веб-приложений. Когда для App Check применяется правило Firebase AI Logic, это помогает защитить как Gemini Developer API, так и Agent Platform Gemini API (formerly Vertex AI).

App Check для Firebase AI Logic также поддерживает защиту от повторного воспроизведения, то есть токен App Check можно использовать только один раз.


Краткое описание принципов работы App Check

С помощью App Check устройства, на которых запущено ваше приложение, используют поставщика подтверждения приложения или устройства, который проверяет одно или оба из следующих утверждений:

  • Запросы поступают из вашего настоящего приложения.
  • Запросы отправляются с немодифицированного устройства.

Подтверждение прикрепляется к каждому запросу, который ваше приложение отправляет с помощью SDK Firebase AI Logic. Если параметр App Check включен, запросы от клиентов без действительного подтверждения будут отклоняться, как и любые запросы, исходящие от приложения или платформы, которые вы не авторизовали.

При настройке App Check рекомендуем добавить защиту от повторного воспроизведения, которая делает токены App Check одноразовыми. Этот вариант обеспечивает более надежную защиту, чем базовый, и позволяет задать подходящий уровень защиты для вашего приложения и вариантов его использования.

Подробную информацию о App Check можно найти в его документации, в том числе описания поставщиков подтверждения, а также применимые квоты и ограничения.

Настроить App Check

Приведенные ниже инструкции оптимизированы для настройки Firebase App Check принудительного применения для Firebase AI Logic.

Шаг 1. Принудительное применение App Check

С начала июля 2026 года в процессе настройки в консоли Firebase Firebase автоматически будет применять Firebase App Check для Firebase AI Logic, чтобы защитить Gemini API.

Однако, если вы настроили Firebase AI Logic в проекте Firebase до начала июля 2026 г. (или если App Check не применяется по другой причине), вы можете принудительно включить App Check, следуя приведенным ниже инструкциям.

  1. Проверьте, применяется ли правило App Check к Firebase AI Logic.

    1. В консоли Firebase перейдите на вкладку Безопасность > App Check > API.

    2. Найдите строку Firebase AI Logic. Если вы видите значок Unenforced, выполните остальные инструкции.

  2. Нажмите на строку Firebase AI Logic, чтобы посмотреть графики показателей. Под графиками нажмите Настроить.

  3. На первом экране диалогового окна (Базовая защита) выберите Принудительно и нажмите Продолжить.

  4. На следующем экране (Защита от повторного воспроизведения) выберите Отключено и нажмите Продолжить.

  5. На последнем экране ознакомьтесь с рекомендациями по применению App Check , чтобы убедиться, что вы готовы к этомуApp Check. Если вы готовы, нажмите Продолжить.

    Вам не нужно регистрировать приложения, если вы хотите использовать только App Check и только поставщика отладочной информации с Firebase AI Logic в предпроизводственной версии приложения. Однако, когда вы будете готовы выпустить приложение для конечных пользователей, вам нужно будет зарегистрировать его в рамках настройки производственного поставщика информации об аттестации (например, App Attest, Play Integrity или reCAPTCHA Enterprise).

Шаг 2. Настройте поставщика отладочной информации для локальной разработки

Для локальной разработки можно настроить App Check поставщика отладки и при этом сохранить принудительное применение App Check для Firebase AI Logic.

Swift

Вот как использовать поставщика данных для отладки при запуске приложения в симуляторе в интерактивном режиме (например, при локальной разработке):

  1. В проекте Xcode импортируйте FirebaseAppCheck и инициализируйте App Check с помощью фабрики поставщика отладки до настройки Firebase.

    import SwiftUI
import FirebaseCore
import FirebaseAppCheck

@main
struct YourApp: App {
  init() {
    let providerFactory = AppCheckDebugProviderFactory()
    AppCheck.setAppCheckProviderFactory(providerFactory)
    FirebaseApp.configure()
  }

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

  2. Получите токен отладки:

    1. Запустите приложение в симуляторе или на тестовом устройстве.

    2. Откройте консоль Xcode и найдите токен отладки App Check. Пример:

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.

    3. Скопируйте токен (например, 123a4567-b89c-12d3-e456-789012345678).

  3. Зарегистрируйте токен отладки в App Check:

    1. В консоли Firebase перейдите на вкладку Приложения в разделе Безопасность > App Check.

    2. Найдите приложение, нажмите на дополнительное меню () и выберите Управление токенами отладки.

    3. Следуйте инструкциям на экране, чтобы зарегистрировать токен отладки.

Подробнее о поставщике отладки (в том числе о том, как получить новый токен отладки) можно узнать в официальной документации App Check.

Kotlin

Вот как использовать поставщика данных для отладки при запуске приложения в эмуляторе в интерактивном режиме (например, при локальной разработке):

  1. В отладочной сборке настройте App Check так, чтобы он использовал фабрику поставщика отладочной версии:

    Firebase.initialize(context = this)
Firebase.appCheck.installAppCheckProviderFactory(
    DebugAppCheckProviderFactory.getInstance(),
)

  2. Получите токен отладки:

    1. Запустите приложение в эмуляторе или на тестовом устройстве.

    2. Найдите в журналах токен отладки App Check. Пример:

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. Скопируйте токен (например, 123a4567-b89c-12d3-e456-789012345678).

  3. Зарегистрируйте токен отладки в App Check:

    1. В консоли Firebase перейдите на вкладку Приложения в разделе Безопасность > App Check.

    2. Найдите приложение, нажмите на дополнительное меню () и выберите Управление токенами отладки.

    3. Следуйте инструкциям на экране, чтобы зарегистрировать токен отладки.

Подробнее о поставщике отладки (в том числе о том, как получить новый токен отладки) можно узнать в официальной документации App Check.

Java

Вот как использовать поставщика данных для отладки при запуске приложения в эмуляторе в интерактивном режиме (например, при локальной разработке):

  1. В отладочной сборке настройте App Check так, чтобы он использовал фабрику поставщика отладочной версии:

    FirebaseApp.initializeApp(/*context=*/ this);
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance());

  2. Получите токен отладки:

    1. Запустите приложение в эмуляторе или на тестовом устройстве.

    2. Найдите в журналах токен отладки App Check. Пример:

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. Скопируйте токен (например, 123a4567-b89c-12d3-e456-789012345678).

  3. Зарегистрируйте токен отладки в App Check:

    1. В консоли Firebase перейдите на вкладку Приложения в разделе Безопасность > App Check.

    2. Найдите приложение, нажмите на дополнительное меню () и выберите Управление токенами отладки.

    3. Следуйте инструкциям на экране, чтобы зарегистрировать токен отладки.

Подробнее о поставщике отладки (в том числе о том, как получить новый токен отладки) можно узнать в официальной документации App Check.

Web

Вот как использовать поставщика отладки при запуске приложения из localhost в интерактивном режиме (например, при локальной разработке):

  1. В отладочной сборке включите режим отладки, задав для параметра self.FIREBASE_APPCHECK_DEBUG_TOKEN значение true до инициализации App Check. Пример:

    self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
initializeAppCheck(app, { /* App Check options */ });

  2. Откройте веб-приложение локально и запустите инструменты разработчика в браузере. В консоли отладки появится токен отладки:

    AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
You will need to safelist it in the Firebase console for it to work.

  3. Зарегистрируйте токен отладки в App Check:

    1. В консоли Firebase перейдите на вкладку Приложения в разделе Безопасность > App Check.

    2. Найдите приложение, нажмите на дополнительное меню () и выберите Управление токенами отладки.

    3. Следуйте инструкциям на экране, чтобы зарегистрировать токен отладки.

Подробнее о поставщике отладки (в том числе о том, как получить новый токен отладки) можно узнать в официальной документации App Check.

Dart

iOS+

Вот как использовать поставщика данных для отладки при запуске приложения в симуляторе в интерактивном режиме (например, при локальной разработке):

  1. Активируйте App Check с поставщиком отладки сразу после инициализации приложения Firebase:

    import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';

// Import the firebase_app_check plugin
import 'package:firebase_app_check/firebase_app_check.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  await FirebaseAppCheck.instance.activate(
    // Set appleProvider to `AppleProvider.debug`
    appleProvider: AppleProvider.debug,
  );
  runApp(App());
}

  2. Включите ведение журнала отладки в проекте Xcode:

    1. Выберите Product (Продукт) > Scheme (Схема) > Edit scheme (Изменить схему).
    2. В меню слева выберите Run (Выполнить), а затем перейдите на вкладку Arguments (Аргументы).
    3. В разделе Arguments Passed on Launch (Аргументы, передаваемые при запуске) добавьте -FIRDebugEnabled.

  3. Получите токен отладки:

    1. Откройте файл ios/Runner.xcworkspace в Xcode и запустите приложение в симуляторе или на тестовом устройстве.

    2. Откройте консоль Xcode и найдите токен отладки App Check. Пример:

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.

    3. Скопируйте токен (например, 123a4567-b89c-12d3-e456-789012345678).

  4. Зарегистрируйте токен отладки в App Check:

    1. В консоли Firebase перейдите на вкладку Приложения в разделе Безопасность > App Check.

    2. Найдите приложение, нажмите на дополнительное меню () и выберите Управление токенами отладки.

    3. Следуйте инструкциям на экране, чтобы зарегистрировать токен отладки.

Android

Вот как использовать поставщика данных для отладки при запуске приложения в эмуляторе в интерактивном режиме (например, при локальной разработке):

  1. Активируйте App Check с помощью поставщика отладки сразу после инициализации приложения Firebase:

    import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';

// Import the firebase_app_check plugin
import 'package:firebase_app_check/firebase_app_check.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  await FirebaseAppCheck.instance.activate(
    // Set androidProvider to `AndroidProvider.debug`
    androidProvider: AndroidProvider.debug,
  );
  runApp(App());
}

  2. Получите токен отладки:

    1. Запустите приложение в эмуляторе или на тестовом устройстве.

    2. Найдите в журналах токен отладки App Check. Пример:

      D DebugAppCheckProvider: Enter this debug secret into the allow list
in the Firebase Console for your project: 123a4567-b89c-12d3-e456-789012345678

    3. Скопируйте токен (например, 123a4567-b89c-12d3-e456-789012345678).

  3. Зарегистрируйте токен отладки в App Check:

    1. В консоли Firebase перейдите на вкладку Приложения в разделе Безопасность > App Check.

    2. Найдите приложение, нажмите на дополнительное меню () и выберите Управление токенами отладки.

    3. Следуйте инструкциям на экране, чтобы зарегистрировать токен отладки.

Веб-приложение

Вот как использовать поставщика данных для отладки при запуске приложения из localhost в интерактивном режиме (например, при локальной разработке):

  1. В файле web/index.html включите режим отладки, задав для параметра self.FIREBASE_APPCHECK_DEBUG_TOKEN значение true:

    <body>
  <script>
    self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
  </script>

  ...

</body>

  2. Запустите веб-приложение локально и откройте инструменты разработчика в браузере. В консоли отладки появится токен отладки:

    AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
You will need to safelist it in the Firebase console for it to work.

    Этот токен хранится локально в вашем браузере и будет использоваться всякий раз, когда вы запускаете приложение в том же браузере на том же компьютере. Если вы хотите использовать токен в другом браузере или на другом компьютере, задайте для параметра self.FIREBASE_APPCHECK_DEBUG_TOKEN строку токена вместо true.

  3. Зарегистрируйте токен отладки в App Check:

    1. В консоли Firebase перейдите на вкладку Приложения в разделе Безопасность > App Check.

    2. Найдите приложение, нажмите на дополнительное меню () и выберите Управление токенами отладки.

    3. Следуйте инструкциям на экране, чтобы зарегистрировать токен отладки.

Подробнее о поставщике отладки (в том числе о том, как получить новый токен отладки) можно узнать в официальной документации App Check.

Unity

Вот как использовать поставщика данных для отладки при запуске приложения в эмуляторе в интерактивном режиме (например, при локальной разработке):

  1. В консоли Firebase создайте токен отладки:

    1. В консоли Firebase перейдите на вкладку Безопасность > App Check > Приложения.

    2. Найдите приложение, нажмите на дополнительное меню () и выберите Управление токенами отладки.

    3. Следуйте инструкциям на экране, чтобы создать новый токен отладки.

  2. В код инициализации приложения добавьте следующее:

    using Firebase.AppCheck;

void InitializeFirebase() {
  // Configure the Debug Provider factory with your debug token.
  DebugAppCheckProviderFactory.Instance.SetDebugToken("YOUR_DEBUG_TOKEN");

  // Set App Check to use the debug provider factory
  FirebaseAppCheck.SetAppCheckProviderFactory(
    DebugAppCheckProviderFactory.Instance);

  // Proceed to initialize Firebase as normal
}

Подробнее о поставщике отладки (в том числе о том, как получить новый токен отладки) можно узнать в официальной документации App Check.

Шаг 3. Настройте App Check для конечных пользователей и производственной среды

Когда вы будете готовы выпустить приложение для конечных пользователей, вам нужно будет зарегистрировать его и настроить поставщика подтверждения целостности для рабочей версии (например, App Attest, Play Integrity или reCAPTCHA Enterprise).

  1. Выберите поставщика подтверждений для рабочей среды и следуйте инструкциям по реализации по ссылкам ниже:

    Если ни один из этих поставщиков не соответствует вашим потребностям, вы можете реализовать собственного поставщика, который использует стороннего поставщика или ваши собственные методы аттестации.

  2. (Рекомендуется) Добавьте защиту от повторного воспроизведения, чтобы токен App Check можно было использовать только один раз.

Как повысить уровень защиты, добавив защиту от повторных атак

Мы рекомендуем использовать последние версии SDK, но для защиты от повторного воспроизведения вам понадобится хотя бы одна из следующих версий:
Apple platforms v12.2.0+ | Android BoM v34.14.0+ (App Check v19.1.0+) | Web v12.14.0+ | Flutter v4.15.0+ (App Check v4.10.0+) | Unity v13.12.0+

По умолчанию в App Check используются токены сеанса, время жизни которых можно настроить в диапазоне от 30 минут до 7 дней. Эти токены сеанса кешируются в SDK App Check, отправляются вместе с запросами из вашего приложения и могут использоваться повторно, пока не истечет срок их действия. Использование токенов сеанса считается основной защитой.

Однако вы можете повысить уровень защиты, включив защиту от повторного воспроизведения, которая использует токены с ограниченным сроком действия. Если защита от повторного воспроизведения включена, происходит следующее:

  • App Check будет блокировать запросы к Firebase AI Logic, в которых используются токены сеансов. Вместо этого App Check будет разрешать запрос к Firebase AI Logic, только если в нем используется новый токен с ограниченным сроком действия.

  • После проверки токен с ограниченным сроком действия становится недействительным, поэтому его можно использовать только один раз. Это предотвращает атаки повторного воспроизведения.

  • SDK App Check создает новый токен с ограниченным использованием для каждого запроса. Обратите внимание, что этот процесс может повлиять на ваши запросы, добавив некоторую задержку и иногда стоимость (в зависимости от поставщика подтверждения).

Как настроить и применить защиту от повторного воспроизведения

Нажмите на поставщика Gemini API, чтобы посмотреть контент и код, относящиеся к нему.

Чтобы настроить защиту от повторного воспроизведения, выполните следующие действия:

  1. Если вы ещё не сделали этого, настройте App Check, следуя инструкциям выше.

  2. Включить использование одноразовых токенов.

    В приложении при создании экземпляра задайте для параметра useLimitedUseAppCheckTokens значение true:

    Swift 

    
// ...

// During instantiation, enable usage of limited-use tokens.
let ai = FirebaseAI.firebaseAI(
  backend: .googleAI(),
  useLimitedUseAppCheckTokens: true
)

// ...

    Kotlin 

    
// ...

// During instantiation, enable usage of limited-use tokens.
val ai = Firebase.ai(
  backend = GenerativeBackend.googleAI(),
  useLimitedUseAppCheckTokens = true
)

// ...

    Java 

    
// ...

// During instantiation, enable usage of limited-use tokens.
FirebaseAI ai = FirebaseAI.getInstance(
  /* backend: */ GenerativeBackend.googleAI(),
  /* useLimitedUseAppCheckTokens: */ true
);

// ...

    Web 

    
// ...

// During instantiation, enable usage of limited-use tokens.
const ai = getAI(firebaseApp, {
  backend: new GoogleAIBackend(),
  useLimitedUseAppCheckTokens: true
});

// ...

    Dart 

    
// ...

// During instantiation, enable usage of limited-use tokens
final ai = await FirebaseAI.googleAI(
  useLimitedUseAppCheckTokens: true,
);

// ...

    Unity 

    // ...

// During instantiation, enable usage of limited-use tokens
var ai = FirebaseAI.GetInstance(
  useLimitedUseAppCheckTokens: true
);

// ...

  3. Включите защиту от повторного воспроизведения.

    1. В базе кода приложения убедитесь, что включено использование одноразовых токенов (см. предыдущий шаг).

    2. В консоли Firebase выберите Безопасность > Проверка приложений.

    3. Разверните представление показателей для Firebase AI Logic.

    4. Убедитесь, что для параметра Базовая защита задано значение Принудительно, а затем нажмите Продолжить.

    5. Чтобы включить защиту от повторного воспроизведения, выберите Необязательная (только мониторинг) или Обязательная.

      Принимая решение о том, когда следует применять защиту от повторного воспроизведения, учитывайте следующее:

      • Рекомендуем отслеживать запросы, если значительная часть ваших пользователей, вероятно, использует более ранние версии приложения без включенных токенов ограниченного использования. Если вы включите защиту от повторного воспроизведения немедленно, запросы от этих пользователей будут блокироваться.

      • Вы можете отслеживать показатель Не подтверждено: повторно использованный токен, который представляет собой количество запросов с токеном, уже использованным в предыдущем запросе. Отслеживайте этот показатель в консоли Firebase (перейдите на вкладку Безопасность > Проверка приложений > API).

        Если значительная часть недавних запросов относится к этой категории, вы можете не беспокоить пользователей и отложить принудительное применение защиты от повторного воспроизведения до тех пор, пока больше пользователей не перейдут на версию приложения, в которой используются токены с ограниченным сроком действия.

Как Firebase AI Logic интегрируется с App Check

Чтобы использовать Firebase AI Logic SDK, в проекте Firebase должен быть включен Firebase AI Logic API (firebasevertexai.googleapis.com). Это связано с тем, что запросы, созданные с помощью SDK Firebase AI Logic, сначала отправляются на сервер Firebase AI Logic, который действует как прокси-шлюз, где выполняется проверка Firebase App Check до того, как запрос будет разрешено перенаправить на сервер Gemini API и получить доступ к моделям Gemini.

Часто задаваемые вопросы и устранение неполадок

Ознакомьтесь с часто задаваемыми вопросами и инструкциями по устранению неполадок или кодами ошибок, связанных с Firebase AI Logic.