App Check를 사용하여 API 키 보호

Firebase 앱 체크는 합법적인 앱 이외의 소스에서 발생하는 트래픽을 차단하여 앱에서 Google Maps Platform으로의 호출을 보호합니다. reCAPTCHA Enterprise와 같은 증명 제공업체의 토큰을 확인하여 이를 실행합니다. 앱을 앱 체크와 통합하면 악의적인 요청으로부터 보호할 수 있으므로 승인되지 않은 API 호출에 대한 요금이 청구되지 않습니다.

앱 체크가 나에게 적합한가요?

대부분의 경우 앱 체크를 사용하는 것이 좋지만 다음 경우에는 앱 체크가 필요하지 않거나 지원되지 않습니다.

• 원래 Places SDK를 사용하고 있습니다. App Check는 Places SDK (신규)에서만 지원됩니다.
• 비공개 또는 실험용 앱 앱에 공개적으로 액세스할 수 없는 경우 앱 체크는 필요하지 않습니다.
• 앱이 서버 간 전용으로 사용되는 경우 앱 체크는 필요하지 않습니다. 하지만 GMP와 통신하는 서버가 공개 클라이언트 (예: 모바일 앱)에서 사용되는 경우 GMP 대신 App Check를 사용하여 해당 서버를 보호하는 것이 좋습니다.

구현 단계 개요

앱을 App Check와 통합하는 단계는 대략 다음과 같습니다.

1. 앱에 Firebase를 추가합니다.
2. 앱 체크 라이브러리를 추가하고 초기화합니다.
3. 앱에 토큰 제공자를 추가합니다.
4. Places 및 앱 체크 API를 초기화합니다.
5. 디버깅을 사용 설정합니다.
6. 앱 요청을 모니터링하고 시정 조치를 결정합니다.

App Check와 통합하면 Firebase Console에서 백엔드 트래픽 측정항목을 확인할 수 있습니다. 이 측정항목은 유효한 앱 체크 토큰이 있는지 여부에 따라 요청을 분류하여 보여줍니다. 자세한 내용은 Firebase 앱 체크 문서를 참고하세요.

대부분의 요청이 합법적인 소스에서 발생하고 사용자가 앱 체크 구현이 포함된 앱의 최신 버전으로 업데이트했음을 확신할 수 있으면 시행을 사용 설정할 수 있습니다. 적용을 사용 설정하면 앱 체크에서 유효한 앱 체크 토큰이 없는 모든 트래픽을 거부합니다.

참고: 앱 체크 시정 조치는 기본적으로 사용 설정되어 있지 않습니다.

앱 체크 통합을 계획할 때의 고려사항

통합을 계획할 때 고려해야 할 사항은 다음과 같습니다.

• 권장하는 증명 서비스 제공업체 중 하나인 reCAPTCHA Enterprise는 월별 평가 10,000회 이상에 대해 요금을 청구합니다.

  Google에서 권장하는 다른 증명 서비스인 reCAPTCHA v3에는 할당량이 있으며, 할당량을 초과하면 트래픽이 평가되지 않습니다.

  맞춤 증명 제공업체를 사용할 수도 있지만 이는 고급 사용 사례입니다. 자세한 내용은 앱 체크 문서를 참고하세요.

• 앱 사용자는 시작 시 약간의 지연을 경험하게 됩니다. 하지만 그 후에는 주기적인 재증명이 백그라운드에서 발생하므로 사용자는 더 이상 지연을 경험하지 않아도 됩니다. 시작 시 정확한 지연 시간은 선택한 증명 제공업체에 따라 다릅니다.

  앱 체크 토큰이 유효한 시간 (수명 또는 TTL)에 따라 재증명 빈도가 결정됩니다. 이 기간은 Firebase Console에서 구성할 수 있습니다. 재증명은 TTL의 약 절반이 경과하면 발생합니다. 자세한 내용은 증명 기관의 Firebase 문서를 참고하세요.

앱을 앱 체크와 통합

참고: 더 빠르게 도움을 받으세요. 이 프로세스의 Firebase 관련 부분에 관한 지원은 Firebase 지원팀을 참고하세요. Google Places API와 관련된 지원은 Google Maps Platform 지원을 참고하세요.

기본 요건

• 최신 주간 또는 분기별 버전의 Maps JS API, Core, Places 라이브러리가 로드된 앱
• Maps JS 및 Places API (신규) API가 사용 설정된 Cloud 프로젝트
• Cloud 콘솔에서 앱의 소유자여야 합니다.
• Cloud 콘솔의 앱 프로젝트 ID가 필요합니다.

1단계: 앱에 Firebase 추가

Firebase 개발자 문서의 안내에 따라 앱에 Firebase를 추가합니다.

2단계: 앱 체크 라이브러리 추가 및 앱 체크 초기화

Firebase에서는 각 기본 증명 공급자에 대한 안내를 제공합니다. 이 안내에서는 Firebase 프로젝트를 설정하고 앱에 App Check 라이브러리를 추가하는 방법을 설명합니다. 제공된 코드 샘플에 따라 App Check를 초기화합니다.

• reCAPTCHA Enterprise 안내

• reCAPTCHA v3 안내

  Cloud 콘솔에서 API를 사용 설정하기 전에 reCAPTCHA v3에 사이트를 등록하고 reCAPTCHA 사이트 등록 도구를 사용하여 reCAPTCHA v3 사이트 키와 보안 비밀 키를 가져와야 합니다. 자세한 내용과 안내는 reCAPTCHA v3 문서를 참고하세요.

3단계: Maps JS API 라이브러리 로드

1. 다음 스니펫과 같이 핵심, 지도, 장소 라이브러리를 로드합니다. 자세한 내용과 안내는 Maps JavaScript API 장소 클래스 문서를 참고하세요.

   async function init() {
     const {Settings} = await google.maps.importLibrary('core');
     const {Map} = await google.maps.importLibrary('maps');
     const {Place} = await google.maps.importLibrary('places');
   }  

4단계: 장소 및 앱 확인 API 초기화

1. Firebase Console에서 제공한 구성을 사용하여 앱 체크를 초기화합니다.
   • reCAPTCHA v3 안내
   • reCAPTCHA Enterprise 안내
2. Maps JS API에 대한 요청에 앱 체크 토큰이 포함되어 있는지 확인합니다.

     async function init() {
       const {Settings} = await google.maps.importLibrary('core');
       const {Map} = await google.maps.importLibrary('maps');
       const {Place} = await google.maps.importLibrary('places');
     
       const app = initializeApp({
         // Your firebase configuration object
       });
     
       // Pass your reCAPTCHA Enterprise site key to initializeAppCheck().
       const appCheck = initializeAppCheck(app, {
         provider: new ReCaptchaEnterpriseProvider(
           'abcdefghijklmnopqrstuvwxy-1234567890abcd',
         ),
     
         // Optional argument. If true, the SDK automatically refreshes App Check
         // tokens as needed.
         isTokenAutoRefreshEnabled: true,
       });
     
       Settings.getInstance().fetchAppCheckToken = () =>
           getToken(appCheck, /* forceRefresh = */ false);
     
       // Make a Places JS request
       const place = new Place({id: 'ChIJN5Nz71W3j4ARhx5bwpTQEGg'});
       await place.fetchFields({fields: ['*']});
     
       // Load a map
       map = new Map(document.getElementById("map"), {
         center: { lat: 37.4161493, lng: -122.0812166 },
         zoom: 8,
       });
     }  
     

5단계: 디버깅 사용 설정 (선택사항)

로컬에서 앱을 개발 및 테스트하거나 지속적 통합 (CI) 환경에서 실행하려면 디버그 비밀을 사용하여 유효한 앱 체크 토큰을 가져오는 앱의 디버그 빌드를 만들면 됩니다. 이렇게 하면 디버그 빌드에서 실제 증명 제공업체를 사용하지 않아도 됩니다.

로컬에서 앱을 테스트하려면 다음 단계를 따르세요.

• 개발 목적으로 디버그 제공자를 활성화합니다.
• SDK의 디버그 로그에서 자동으로 생성된 임의의 UUID4 (앱 체크 문서에서는 _디버그 토큰_이라고 함)를 받게 됩니다. 이 토큰을 Firebase Console에 추가합니다.
• 자세한 내용과 안내는 앱 체크 문서를 참고하세요.

CI 환경에서 앱을 실행하려면 다음 안내를 따르세요.

• Firebase Console에서 임의의 UUID4를 생성합니다.
• UUID4를 디버그 토큰으로 추가한 다음 CI 테스트가 테스트 실행당 액세스할 시크릿 저장소에 복사합니다.
• 자세한 내용과 안내는 앱 체크 문서를 참고하세요.

6단계: 앱 요청 모니터링 및 시정 조치 결정

시정 조치를 시작하기 전에 앱의 적법한 사용자가 방해받지 않도록 해야 합니다. 이렇게 하려면 앱 체크 측정항목 화면으로 이동하여 앱 트래픽 중 확인된 트래픽, 오래된 트래픽, 잘못된 트래픽의 비율을 확인하세요. 트래픽의 대부분이 인증되면 시행을 사용 설정할 수 있습니다.

자세한 내용과 안내는 Firebase 앱 체크 문서를 참고하세요.

App Check를 적용하기 전에 Cloud 프로젝트의 모든 웹 서비스 호출이 OAuth를 사용해야 합니다.