앱 체크를 사용하여 API 키 보호

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

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

대부분의 경우 앱 체크가 권장되지만 다음과 같은 경우에는 앱 체크가 필요하지 않거나 지원되지 않습니다.

원래 Places SDK를 사용하고 있습니다. 앱 체크는 Places SDK (신규)에서만 지원됩니다.
비공개 또는 실험용 앱. 앱에 공개적으로 액세스할 수 없는 경우 앱 체크가 필요하지 않습니다.
앱이 서버 간에만 사용되는 경우 앱 체크가 필요하지 않습니다. 하지만 GMP와 통신하는 서버가 공개 클라이언트 (예: 모바일 앱)에서 사용되는 경우 GMP 대신 앱 체크를 사용하여 해당 서버를 보호하는 것이 좋습니다.
앱 체크의 권장 증명 제공업체는 증명 제공업체에서 손상되거나 신뢰할 수 없는 것으로 간주하는 기기에서 작동하지 않습니다. 이러한 기기를 지원해야 하는 경우 커스텀 증명 서비스를 배포할 수 있습니다. 자세한 내용은 안내를 참고하세요.

구현 단계 개요

대략적으로 앱을 앱 체크와 통합하기 위해 따르는 단계는 다음과 같습니다.

앱에 Firebase를 추가합니다.
앱 체크 라이브러리를 추가하고 초기화합니다.
토큰 제공자를 추가합니다.
디버깅을 사용 설정합니다.
앱 요청을 모니터링하고 적용을 결정합니다.

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

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

앱 체크 통합 계획 시 고려사항

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

Google에서 권장하는 증명 제공업체인 Play Integrity는 표준 API 사용 등급에 대한 일일 호출 한도가 있습니다. 호출 한도에 관한 자세한 내용은 Google Play Integrity 개발자 문서의 설정 페이지를 참고하세요.

고급 사용 사례이긴 하지만 커스텀 증명 제공업체를 사용할 수도 있습니다. 자세한 내용은 커스텀 앱 체크 제공업체 구현을 참고하세요.
앱 사용자는 시작 시 약간의 지연 시간을 경험하게 됩니다. 하지만 이후에는 주기적인 재증명이 백그라운드에서 발생하며 사용자는 더 이상 지연 시간을 경험하지 않게 됩니다. 시작 시의 정확한 지연 시간은 선택한 증명 제공업체에 따라 다릅니다.

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

앱을 앱 체크와 통합

기본 요건 및 요구사항

버전 4.1 이상의 Places SDK가 통합된 앱.
앱의 SHA-256 지문.
앱의 패키지 이름.
Cloud 콘솔에서 앱의 소유자여야 합니다.
Cloud 콘솔에서 앱의 프로젝트 ID가 필요합니다.

1단계: 앱에 Firebase 추가

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

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

기본 증명 제공업체인 Play Integrity 사용에 관한 자세한 내용은 Android에서 Play Integrity로 앱 체크 사용 시작하기를 참고하세요.

아직 통합하지 않은 경우 Places SDK를 앱에 통합합니다.

다음으로 앱 체크 및 Places 클라이언트를 초기화합니다.

// Initialize App Check
FirebaseApp.initializeApp(/* context= */ this);
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
        PlayIntegrityAppCheckProviderFactory.getInstance());
  
// Initialize Places SDK
Places.initializeWithNewPlacesApiEnabled(context, API_KEY);
PlacesClient client = Places.createClient(context);.

3단계: 토큰 제공자 추가

Places API를 초기화한 후 setPlacesAppCheckTokenProvider()를 호출하여 PlacesAppCheckTokenProvider를 설정합니다.

Places.initializeWithNewPlacesApiEnabled(context, API_KEY);
Places.setPlacesAppCheckTokenProvider(new TokenProvider());
PlacesClient client = Places.createClient(context);.

다음은 토큰 가져오기 도구 인터페이스의 샘플 구현입니다.

  /** Sample client implementation of App Check token fetcher interface. */
  static class TokenProvider implements PlacesAppCheckTokenProvider {
    @Override
    public ListenableFuture<String> fetchAppCheckToken() {
      SettableFuture<String> future = SettableFuture.create();
      FirebaseAppCheck.getInstance()
          .getAppCheckToken(false)
          .addOnSuccessListener(
              appCheckToken -> {
                future.set(appCheckToken.getToken());
              })
          .addOnFailureListener(
              ex -> {
                future.setException(ex);
              });

      return future;
    }
  }

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

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

에뮬레이터 또는 테스트 기기에서 앱을 실행하려면 다음 안내를 따르세요.

build.gradle 파일에 앱 체크 라이브러리를 추가합니다.
디버그 빌드에서 디버그 제공업체 팩토리를 사용하도록 앱 체크를 구성합니다.
앱을 실행하면 로컬 디버그 토큰이 생성됩니다. 이 토큰을 Firebase Console에 추가합니다.
자세한 내용과 안내는 앱 체크 문서를 참고하세요.

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

Firebase Console에서 디버그 토큰을 만들고 CI 시스템의 보안 키 저장소에 추가합니다.
build.gradle 파일에 앱 체크 라이브러리를 추가합니다.
디버그 토큰을 사용하도록 CI 빌드 변형을 구성합니다.
앱 체크 토큰이 필요한 테스트 클래스의 코드를 DebugAppCheckTestHelper로 래핑합니다.
자세한 내용과 안내는 앱 체크 문서를 참고하세요.

5단계: 앱 요청 모니터링 및 적용 결정

적용을 시작하기 전에 앱의 적법한 사용자를 방해하지 않는지 확인해야 합니다. 이렇게 하려면 앱 체크 측정항목 화면을 방문하여 앱 트래픽의 인증된 비율, 오래된 비율 또는 적법하지 않은 비율을 확인하세요. 대부분의 트래픽이 인증된 것으로 확인되면 적용을 사용 설정할 수 있습니다.

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