Firebase Installations 403(API_KEY_ANDROID_APP_BLOCKED) 해결. flavor별 google-services.json 분리 정리

Android에서 FCM을 dev/uat/prod 로 운영했다. 특정 variant에서 FCM 토큰 발급이 실패했다. 앱 실행은 정상인데 토큰만 실패했다. 로그에 API_KEY_ANDROID_APP_BLOCKED가 출력됐다. 원인은 API Key의 Android 제한(패키지명/SHA-1) 불일치 또는 google-services.json 혼용이었다. flavor별로 설정을 분리해서 해결함.

— -

1. 증상

로그가 반복 출력됐다.

• Failed to get FIS auth token
• Firebase Installations can not communicate with Firebase server APIs due to invalid configuration
• HTTP 403 Forbidden
• reason: API_KEY_ANDROID_APP_BLOCKED
• Requests from this Android client application <package> are blocked.

— -

2. 이유

FCM은 내부적으로 Firebase Installations(FIS)를 사용한다.

1. 앱 설치 단위 ID(FID)를 생성한다.
2. Firebase Installations API로 통신한다.
3. FIS auth token을 발급받는다.
4. 이후 FCM 토큰 발급/갱신이 진행된다.

FIS 단계에서 403이 발생하면 FCM도 토큰 발급에 실패함.

— -

3. API_KEY_ANDROID_APP_BLOCKED 의미

요청은 서버에 도착했다. 그러나 API Key가 해당 Android 앱 요청을 허용하지 않는다. 패키지명 또는 SHA-1이 제한 조건과 불일치하면 차단된다. 결과로 403이 반환된다.

— -

4. Don’t restrict key 관련 정리

API Key 제한은 두 가지다.

• Application restrictions: 어떤 클라이언트가 키를 쓸 수 있는지 제한한다(Android apps 등).
• API restrictions: 어떤 API 호출을 허용할지 제한한다.

API restrictions가 Don’t restrict key여도 Application restrictions가 Android apps로 설정돼 있으면 패키지명/SHA-1 불일치 시 차단된다. Don’t restrict key는 fingerprint를 무력화하지 않는다.

— -

5. SHA-1 불일치 확인

• debug/release keystore가 다르다.
• 로컬 빌드와 CI 빌드 서명키가 다르다.
• 배포용/스토어용 키가 다르다.

확인 방법은 signingReport를 사용한다.

• ./gradlew signingReport

문제 variant의 SHA-1을 확인하고, GCP Console의 API Key(Android 제한)에 등록된 SHA-1과 일치 여부를 확인한다.

— -

6. app/google-services.json 하나만 둘 때의 문제

app 레벨에서 app/google-services.json 하나만 두면 모든 variant가 동일 설정을 공유한다. dev/prod를 분리 운영하면 설정 혼용이 발생한다. 환경별로 google-services.json을 분리한다.

— -

7. flavor/buildType별 google-services.json 분리

7.1) flavor별 분리

app/
 src/
 dev/
 google-services.json
 prod/
 google-services.json

기존 app/google-services.json은 제거했다.

7.2) 조합별 분리

app/
 src/
 devDebug/
 google-services.json
 devRelease/
 google-services.json
 prodDebug/
 google-services.json
 prodRelease/
 google-services.json

조합 소스셋이 우선 적용

— -

8. applicationId(패키지명) 일치가 핵심.

Firebase는 패키지명(applicationId) 기준으로 Android 앱을 구분한다. flavor에서 applicationIdSuffix를 사용하면 패키지명이 달라진다. 패키지명이 다르면 Firebase 콘솔에서 Android 앱을 각각 등록한다. 각 앱에 맞는 google-services.json을 내려받아 소스셋에 배치한다.

— -

9. 체크리스트

1. 문제 재현 build variant를 확인한다.
2. ./gradlew signingReport로 해당 variant SHA-1을 확인한다.
3. GCP Console → Credentials → API key에서 Android apps 제한의 패키지명/SHA-1 등록을 확인한다.
4. Firebase 콘솔에서 환경에 맞는 google-services.json을 다시 다운로드한다.
5. app/src/<flavor>/ 또는 app/src/<flavor><BuildType>/로 파일을 분리한다.
6. 빌드 후 403이 해소됐는지 확인한다.