Предотвратите злоупотребление API Gemini с помощью Firebase App Check.

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

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

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

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


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

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

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

Это подтверждение добавляется к каждому запросу, который ваше приложение отправляет с помощью Firebase AI Logic SDK. При включении 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 , чтобы защитить API Gemini .

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

  1. Проверьте, включена ли уже App Check для Firebase AI Logic .

    1. В консоли Firebase перейдите в раздел Безопасность > Проверка приложений > вкладка 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 .

Быстрый

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

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

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

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

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

    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. Откройте Продукт > Схема > Редактировать схему .
    2. В левом меню выберите пункт «Выполнить» , а затем вкладку «Аргументы» .
    3. В разделе «Аргументы, передаваемые при запуске» добавьте -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 перейдите в раздел Безопасность > Проверка приложений > вкладка Приложения .

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

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

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

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

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

Единство

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

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

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

    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 v12.2.0+ | Android BoM v34.14.0+ ( App Check v19.1.0+) | Веб v12.14.0+ | Flutter v4.15.0+ ( App Check v4.10.0+) | Unity v13.12.0+

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

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

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

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

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

Настройте и обеспечьте защиту от повторного воспроизведения.

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

Agent

Вот как настроить и обеспечить защиту от повторного воспроизведения:

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

  2. Разрешить использование токенов с ограниченным сроком действия.

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

    Быстрый 

    
// ...

// 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,
);

// ...

    Единство 

    // ...

// 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

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

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

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