Как предотвратить злоупотребление 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 перейдите в раздел Security (Безопасность) > App Check (Проверка приложений) > APIs (API).

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

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

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

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

  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 перейдите в раздел Security (Безопасность) > App Check (Проверка приложений) > Apps (Приложения).

    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 перейдите в раздел Security (Безопасность) > App Check (Проверка приложений) > Apps (Приложения).

    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 перейдите в раздел Security (Безопасность) > App Check (Проверка приложений) > Apps (Приложения).

    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 перейдите в раздел Security (Безопасность) > App Check (Проверка приложений) > Apps (Приложения).

    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 перейдите в раздел Security (Безопасность) > App Check (Проверка приложений) > Apps (Приложения).

    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 перейдите в раздел Security (Безопасность) > App Check (Проверка приложений) > Apps (Приложения).

    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 перейдите в раздел Security (Безопасность) > App Check (Проверка приложений) > Apps (Приложения).

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

    3. Зарегистрируйте токен отладки, следуя инструкциям на экране.

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

Unity

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

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

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

    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: 12.2.0+ | Android BoM: 34.14.0+ (App Check: 19.1.0+) | Веб: 12.14.0+ | Flutter: 4.15.0+ (App Check: 4.10.0+) | Unity: 13.12.0+

По умолчанию App Check использует токены сеанса, для которых можно настроить время жизни (TTL) в диапазоне от 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 выберите Security (Безопасность) > App Check (Проверка приложений).

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

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

    5. Для защиты от повторного воспроизведения выберите Не применяется (только мониторинг) или Применяется.

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

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

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

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

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

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

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

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