Firebase 앱 체크로 Gemini API 악용 방지

모바일 또는 웹 앱에서 직접 API를 호출하면 승인되지 않은 클라이언트가 API를 악용할 수 있습니다. 모바일 또는 웹 앱에서 Gemini API를 직접 호출하려면 Firebase AI Logic를 사용하여 악용으로부터 보호하고 Firebase App Check를 적용해야 합니다. App Check를 적용하면 실제 앱 또는 변조되지 않은 기기에서 온 것으로 확인된 수신 요청만 허용됩니다.

설정 안내로 이동

Firebase AI Logic은 Firebase App Check와 통합하고 모바일 및 웹 앱에서 직접 호출될 때 Gemini API을 보호할 수 있는 프록시 게이트웨이를 제공합니다. Firebase AI Logic에 App Check가 적용되면 Gemini Developer API와 Agent Platform Gemini API (formerly Vertex AI)를 모두 보호할 수 있습니다.

Firebase AI Logic용 App Check도 재생 보호를 지원하므로 App Check 토큰은 한 번만 사용할 수 있습니다.


App Check 작동 방식에 관한 대략적인 요약

App Check를 사용하면 앱을 실행하는 기기는 다음 중 하나 또는 둘 모두를 확인하는 앱 또는 기기 증명 제공자를 사용합니다.

  • 요청이 인증된 앱에서 발생함
  • 요청이 변조되지 않은 인증된 기기에서 발생함

이 증명은 앱이 Firebase AI Logic SDK를 사용하여 수행하는 모든 요청에 연결됩니다. App Check이 적용되면 유효한 증명이 없는 클라이언트의 요청이 거부되며 승인하지 않은 앱이나 플랫폼에서 발생한 요청도 거부됩니다.

App Check을 설정할 때 재생 보호를 추가하는 것이 좋습니다. 이렇게 하면 App Check 토큰이 일회용이 됩니다. 이 옵션은 기준 보호 이상의 강화된 보호를 제공하며 앱 및 사용 사례에 적합한 보호 수준을 설정할 수 있습니다.

증명 제공업체에 대한 설명과 적용 가능한 할당량 및 한도를 비롯한 App Check에 대한 자세한 정보는 설명서에서 확인할 수 있습니다.

App Check 설정

다음 안내는 Firebase AI Logic에 대한 Firebase App Check 시정 조치를 설정하는 데 최적화되어 있습니다.

1단계: App Check 시행

2026년 7월 초부터 Firebase 콘솔의 안내 설정 워크플로 중에 Firebase는 Gemini API를 보호하기 위해 Firebase AI Logic에 Firebase App Check를 자동으로 적용합니다.

하지만 2026년 7월 초 이전에 Firebase 프로젝트에서 이미 Firebase AI Logic를 설정한 경우 (또는 다른 이유로 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 디버그 제공자를 설정하면서도 Firebase AI Logic에 App Check를 적용된 상태로 유지할 수 있습니다.

Swift

시뮬레이터에서 대화형으로 앱을 실행하는 동안 (예: 로컬 개발 중에) 디버그 제공자를 사용하는 방법은 다음과 같습니다.

  1. Xcode 프로젝트에서 FirebaseAppCheck를 가져오고 Firebase를 구성하기 전에 디버그 제공자 팩토리로 App Check를 초기화합니다.

    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. 디버그 빌드에서 App Check를 초기화하기 전에 self.FIREBASE_APPCHECK_DEBUG_TOKEN을 true로 설정하여 디버그 모드를 사용 설정합니다. 예를 들면 다음과 같습니다.

    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. Firebase 앱을 초기화한 직후 디버그 제공자로 App Check을 활성화합니다.

    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. Xcode로 ios/Runner.xcworkspace를 열고 시뮬레이터나 테스트 기기에서 앱을 실행합니다.

    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. Firebase 앱을 초기화한 직후 디버그 제공자로 App Check을 활성화합니다.

    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 플랫폼 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는 30분에서 7일 사이로 구성 가능한 수명 (TTL)이 있는 세션 토큰을 사용합니다. 이러한 세션 토큰은 App Check SDK에 의해 캐시되고, 앱의 요청과 함께 전송되며, TTL이 만료될 때까지 재사용할 수 있습니다. 세션 토큰을 사용하는 것은 기준 보호로 간주됩니다.

하지만 대신 제한된 사용 토큰을 사용하는 재생 보호를 적용하여 이 기준 보호를 넘어 보호를 강화할 수 있습니다. 재생 보호가 적용되면 다음과 같은 결과가 발생합니다.

  • App Check는 세션 토큰을 사용하는 Firebase AI Logic에 대한 요청을 차단합니다. 대신 App Check는 새로 생성된 제한된 사용 토큰을 사용하는 경우에만 Firebase AI Logic에 대한 요청을 허용합니다.

  • 제한된 사용 토큰이 확인되면 토큰이 소비되어 한 번만 사용할 수 있으므로 재생 공격이 방지됩니다.

  • App Check SDK는 각 요청에 대해 새로운 제한된 사용 토큰을 생성합니다. 이 프로세스는 지연 시간을 추가하고 증명 제공업체에 따라 비용을 발생시켜 요청에 영향을 줄 수 있습니다.

리플레이 보호 설정 및 시행

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 콘솔에서 보안 > App Check으로 이동합니다.

    3. Firebase AI Logic의 측정항목 뷰를 펼칩니다.

    4. 기본 보호가 강제로 설정되어 있는지 확인한 다음 계속을 클릭합니다.

    5. 리플레이 보호의 경우 강제 적용 안 함 (모니터링만 해당) 또는 강제 적용을 선택합니다.

      재생 보호를 적용할 시기를 결정하려면 다음을 고려하세요.

      • 상당수의 사용자가 사용 제한 토큰을 사용 설정하지 않고 이전 버전의 앱을 사용하고 있는 경우 요청을 모니터링하는 것이 좋습니다. 즉시 리플레이 보호를 시행하면 해당 사용자의 요청이 차단됩니다.

      • Unverified: Reused token 측정항목을 구체적으로 모니터링할 수 있습니다. 이 측정항목은 이전 요청에서 이미 사용된 토큰이 있는 요청의 수입니다. Firebase 콘솔에서 이 측정항목을 모니터링합니다 (보안 > App Check > API 탭으로 이동).

        최근 요청의 상당 부분이 이 카테고리에 속하는 경우 사용자를 방해하지 않으려면 더 많은 사용자가 제한된 사용 토큰을 사용하는 앱 버전으로 업데이트할 때까지 기다린 후에 리플레이 보호를 적용하는 것이 좋습니다.

Firebase AI Logic이 App Check과 통합되는 방식 이해하기

Firebase AI Logic SDK를 사용하려면 Firebase 프로젝트에서 Firebase AI Logic API (firebasevertexai.googleapis.com)를 사용 설정해야 합니다. 이는 Firebase AI Logic SDK에서 전송된 요청이 먼저 Firebase AI Logic 서버로 전송되기 때문입니다. 이 서버는 요청이 선택한 'Gemini API' 제공업체의 백엔드와 Gemini 및 Imagen 모델에 액세스하는 API로 진행되기 전에 Firebase App Check 확인이 이루어지는 프록시 게이트웨이 역할을 합니다.

FAQ 및 문제 해결

Firebase AI Logic와 관련된 추가 FAQ 및 문제 해결 또는 오류 코드를 확인하세요.