앱 체크를 사용하여 Android용 Navigation SDK 보안

Firebase 앱 체크는 합법적인 앱 이외의 소스에서 발생하는 트래픽을 차단하여 앱에서 Google Maps Platform으로의 호출을 보호합니다. 이를 위해 Play Integrity와 같은 증명 프로바이더에 앱 또는 기기의 신뢰성 평가를 요청합니다. 앱을 앱 체크와 통합하면 악성 및 승인되지 않은 요청으로부터 보호할 수 있으며, 이는 승인되지 않은 청구로부터 결제를 보호합니다. 또한 App Check는 차량 앱 생태계에서 실시간 중단 보고를 크게 개선하여 앱을 사용하는 모든 운전자에게 이점을 제공합니다. 자세한 내용은 중단 보고를 참고하세요.

앱 체크를 사용해야 하는 이유

App Check는 Android용 Navigation SDK의 두 가지 영역(기본 탐색 기능 및 중단 보고)을 보호합니다.

앱 체크는 악성 또는 승인되지 않은 소스의 Android용 기본 탐색 SDK 요청을 차단하는 데 도움이 됩니다. 이렇게 하면 결제 사기 및 할당량 소진으로부터 프로젝트를 보호하여 직접적인 이점을 얻을 수 있습니다.

운행 중단 신고

앱이 실시간 중단 보고 및 투표 기능을 지원하는 경우 앱 체크를 사용하는 것이 좋습니다. App Check를 사용 설정하면 모든 실시간 피드백을 고려한 가장 정확한 경로가 운전자에게 제공됩니다.

보고에 App Check가 중요한 이유:

  • 폐쇄에 대한 높은 신뢰 기준: 도로 폐쇄와 같이 경로에 영향을 미치는 이벤트는 모든 운전자의 라우팅 동작을 크게 바꿀 수 있습니다. 지도를 잠재적인 반달리즘, 스팸 또는 부정확한 신고로부터 보호하기 위해 Google의 도로 폐쇄 중단 조정 인프라는 강력한 기기 및 앱 무결성 신호를 사용합니다.
  • App Check에서 보고서를 검증하는 방법: Android용 Navigation SDK에서 전송된 사용자 보고서와 투표에는 App Check 토큰이 포함되어 있습니다. Google 백엔드에서는 이 토큰을 사용하여 의견의 적법성을 검증하고 신뢰 수준을 높여 라이브 지도에 미치는 영향을 평가할 수 있습니다.
  • 앱 체크를 생략할 경우의 영향: 유효한 앱 체크 토큰 없이 제출된 보고서는 신뢰도가 낮은 모델에 따라 평가되며 무음 신호로만 처리될 수 있습니다. 즉, 사용자는 계속 신고하고 투표할 수 있지만 신고가 지도에 표시되거나 다른 운전자의 경로에 영향을 미칠 가능성이 낮으며 추가 검증이 필요합니다.

App Check가 나에게 적합한가요?

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

  • 비공개 또는 실험용 앱: 앱에 공개적으로 액세스할 수 없는 경우 앱 확인이 필요하지 않습니다.
  • 보안 침해된 기기: 권장 증명 제공자는 루팅 또는 탈옥된 휴대전화와 같이 신뢰할 수 없는 기기에서 Android용 Navigation SDK가 실행되지 않도록 합니다. 이러한 기기를 지원하려면 맞춤 증명 프로바이더를 배포하세요.
  • 비 GMS Android 기기: Android 기기는 Play 무결성을 위해 Google 모바일 서비스 (GMS)를 실행해야 합니다. 비 GMS Android 기기를 지원하려는 경우 맞춤 증명 프로바이더를 배포하세요.

구현 단계 개요

대략적으로 앱을 앱 확인과 통합하려면 다음 단계를 따르세요.

  1. 앱에 Firebase를 추가합니다.
  2. 앱 체크 라이브러리를 추가하고 앱 체크를 초기화합니다.
  3. 토큰 제공업체를 추가합니다. 이 단계에서는 선택한 증명 프로바이더를 호출하여 기기 또는 앱의 무결성을 확인합니다.
  4. Navigation 및 App Check API를 초기화합니다.
  5. 디버깅을 사용 설정합니다. 이는 개발 중이나 지속적 통합 (CI) 환경에서 유용합니다.
  6. 강제 시행을 사용 설정하기 전에 앱 요청을 모니터링하세요. 이렇게 하면 사용자를 방해하지 않고 원활하게 앱 확인을 시행할 수 있습니다.

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

  • 증명 제공업체 할당량: Google에서 추천하는 증명 제공업체인 Play Integrity에는 표준 API 사용 등급의 일일 호출 한도가 있습니다. 호출 한도에 관한 자세한 내용은 Google Play Integrity 개발자 문서의 설정 페이지를 참고하세요.
  • 시작 지연 시간: 대부분의 경우 앱 체크 토큰이 기기에 캐시되므로 사용자는 일반적인 사용 중에 지연 시간을 경험하지 않습니다. 시스템은 만료되기 전에 백그라운드에서 앱 체크 토큰을 자동으로 새로고침하여 원활한 성능을 유지합니다. 하지만 유효한 앱 체크 토큰이 없으면 앱 사용자가 시작 시 지연 시간을 경험하게 됩니다. 예를 들어 캐시된 토큰이 만료되었거나 누락된 콜드 스타트 중에 이 지연 시간이 발생합니다.
  • 토큰 TTL: 수명 (TTL)은 앱 체크 토큰을 새로고침해야 하기 전까지 유효한 시간을 결정합니다. Firebase Console에서 이 기간을 30분에서 7일 사이로 구성할 수 있습니다. 1시간의 기간이 안전한 기준선으로 권장되지만 SDK는 TTL 기간의 약 절반에서 백그라운드 새로고침을 자동으로 시도합니다. 단계별 콘솔 안내는 Firebase 앱 체크 문서를 참고하세요.

앱을 앱 체크와 통합

기본 요건 및 요구사항

  • Android용 Navigation SDK 버전 7.9 이상이 설치된 앱
  • 앱의 SHA-256 인증서 지문입니다.
  • 앱의 패키지 이름입니다.
  • Google Cloud 콘솔에서 앱의 소유자여야 합니다.
  • Google Cloud 콘솔의 앱 프로젝트 ID입니다.

1단계: 앱에 Firebase 추가

Firebase 개발자 문서의 안내에 따라 앱에 Firebase를 추가합니다. 프로젝트의 앱 수준 디렉터리에 google-services.json 파일을 추가합니다.

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

앱의 build.gradle 파일에 앱 체크 종속 항목을 추가합니다.

Groovy (build.gradle)

dependencies {
    // Import the Firebase BoM
    implementation platform('com.google.firebase:firebase-bom:34.17.0')
    // Add the dependency for the App Check library with Play Integrity
    implementation 'com.google.firebase:firebase-appcheck-playintegrity'
}

Application 클래스 또는 기본 활동에서 앱 체크를 초기화합니다.

자바

import com.google.firebase.FirebaseApp;
import com.google.firebase.appcheck.FirebaseAppCheck;
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory;

// Initialize Firebase App
FirebaseApp.initializeApp(/* context= */ this);

// Initialize App Check
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
    PlayIntegrityAppCheckProviderFactory.getInstance());

Kotlin

import com.google.firebase.Firebase
import com.google.firebase.appcheck.appCheck
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory
import com.google.firebase.initialize

// Initialize Firebase App
Firebase.initialize(context = this)

// Initialize App Check
Firebase.appCheck.installAppCheckProviderFactory(
    PlayIntegrityAppCheckProviderFactory.getInstance(),
)

3단계: 토큰 제공자 추가

MapsAppCheckTokenProvider 인터페이스를 구현합니다. 이 제공자는 Firebase 앱 체크에서 앱 체크 토큰을 비동기적으로 가져와 MapsAppCheckTokenCallback를 사용하여 Android 네트워크 스택용 탐색 SDK에 전달합니다.

자바

import com.google.android.gms.maps.MapsAppCheckTokenCallback;
import com.google.android.gms.maps.MapsAppCheckTokenProvider;
import com.google.firebase.appcheck.FirebaseAppCheck;

public class NavigationTokenProvider implements MapsAppCheckTokenProvider {
  @Override
  public void fetchToken(MapsAppCheckTokenCallback callback) {
    FirebaseAppCheck.getInstance()
        .getAppCheckToken(false) // forcingRefresh = false
        .addOnSuccessListener(
            tokenResult -> {
              String token = tokenResult.getToken();
              callback.onSuccess(token);
            })
        .addOnFailureListener(
            e -> {
              callback.onFailure();
            });
  }
}

Kotlin

import com.google.android.gms.maps.MapsAppCheckTokenCallback
import com.google.android.gms.maps.MapsAppCheckTokenProvider
import com.google.firebase.appcheck.FirebaseAppCheck

class NavigationTokenProvider : MapsAppCheckTokenProvider {
    override fun fetchToken(callback: MapsAppCheckTokenCallback) {
        FirebaseAppCheck.getInstance()
            .getAppCheckToken(false)
            .addOnSuccessListener { tokenResult ->
                callback.onSuccess(tokenResult.token)
            }
            .addOnFailureListener {
                callback.onFailure()
            }
    }
}

4단계: Navigation 및 App Check API 초기화

Android용 Navigation SDK를 초기화하고 MapsApiSettings.setAppCheckTokenProvider()를 사용하여 통합 토큰 제공업체 인스턴스를 등록합니다.

자바

import com.google.android.gms.maps.MapsApiSettings;

// Register your App Check token provider before initializing Navigation SDK for Android
MapsApiSettings.setAppCheckTokenProvider(context, new NavigationTokenProvider());

Kotlin

import com.google.android.gms.maps.MapsApiSettings

// Register your App Check token provider before initializing Navigation SDK for Android
MapsApiSettings.setAppCheckTokenProvider(context, NavigationTokenProvider())

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

Android용 Navigation SDK에 앱 체크가 적용되면 시뮬레이터나 지속적 통합 (CI) 환경에서 Android용 Navigation SDK에 종속된 앱의 기능이 실행되지 않습니다. 이러한 환경은 유효한 기기로 인정되지 않기 때문입니다. 개발 및 테스트 중에 이러한 환경에서 앱을 실행하려면 프로덕션 증명 제공자 대신 앱 체크 디버그 제공자를 사용하는 앱의 디버그 빌드를 만들어야 합니다.

  1. 앱의 build.gradle 파일에 디버그 제공자 종속 항목을 추가합니다.

    Groovy (build.gradle)

    dependencies {
    implementation 'com.google.firebase:firebase-appcheck-debug'
}
  2. 디버그 빌드에서 디버그 제공자 팩토리를 사용하도록 앱 체크를 구성합니다.

    자바

    import com.google.firebase.appcheck.debug.DebugAppCheckProviderFactory;
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory;

if (BuildConfig.DEBUG) {
    firebaseAppCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance()
    );
} else {
    firebaseAppCheck.installAppCheckProviderFactory(
        PlayIntegrityAppCheckProviderFactory.getInstance()
    );
}

    Kotlin

    import com.google.firebase.Firebase
import com.google.firebase.appcheck.appCheck
import com.google.firebase.appcheck.debug.DebugAppCheckProviderFactory
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory

if (BuildConfig.DEBUG) {
    Firebase.appCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance(),
    )
} else {
    Firebase.appCheck.installAppCheckProviderFactory(
        PlayIntegrityAppCheckProviderFactory.getInstance(),
    )
}
  3. 에뮬레이터 또는 디버그 기기에서 앱을 실행합니다. 앱 체크에서 로컬 디버그 토큰을 Logcat 출력에 출력합니다.
  4. 이 디버그 토큰을 복사하여 Firebase Console에 등록합니다. 자세한 내용은 Firebase 앱 체크 디버그 제공업체 문서를 참고하세요.

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

적용을 사용 설정하기 전에 앱 요청을 모니터링하여 정당한 사용자를 방해하지 않는지 확인하세요.

  1. Firebase Console의 앱 체크 측정항목 화면에서 인증된 트래픽과 인증되지 않은 트래픽의 비율을 확인하세요.
  2. 대부분의 트래픽이 인증되고 적법한 사용자가 앱 체크 구현이 포함된 앱 버전으로 업데이트되었는지 확인한 후 시행을 사용 설정하세요.
  3. 적용이 사용 설정되면 앱 체크에서 유효한 앱 체크 토큰이 없는 모든 트래픽을 거부합니다.