기존에 사용하던 구글 FCM Legacy HTTP API가 지원 종료되면서 푸시 알림 발송이 전면 중단되는 에러를 경험해봤을 것이다.
다만 단순 API 키(Server Key) 방식에서 Google OAuth 2.0 액세스 토큰 인증 기반으로의 전환 과정에서 HTTP v1 REST API 규격을 제대로 이해하지 못해 헤매는 경우가 많다.
이번에는 FCM HTTP v1 API의 인증 구조부터 비동기 푸시 발송 cURL 모듈 구현까지 실무 코드로 완벽하게 정리해서 소개하겠다.
구글은 기존 서버 키(Server Key) 방식의 Legacy HTTP API를 폐지하고 OAuth 2.0 보안 메커니즘을 적용한 HTTP v1 API 사용을 강력히 권장하고 있다.
Legacy API는 단일 헤더 키 정보만으로 동작하여 간편했지만, 키 유출 시 시스템 전체 전송 권한이 노출되는 심각한 보안상 문제점이 존재했다.
반면 HTTP v1 API는 서비스 계정(Service Account)을 활용해 1시간 동안만 유효한 OAuth 2.0 Access Token을 발급받아 전송하므로 훨씬 안전하다.
또한 메시지 요청 페이로드 구조가 완전히 변경되었다.
모든 전송 정보가 message 최상위 객체 내부로 캡슐화되었으며, 플랫폼별(Android, APNs, Web) 세부 옵션을 독립적으로 정의할 수 있도록 유연하게 설계되었다.
| 구분 | FCM Legacy HTTP API | FCM HTTP v1 API |
|---|---|---|
| 인증 방식 | 고정 Server Key (Header: key=...) | OAuth 2.0 Access Token (Header: Bearer ...) |
| 보안 수준 | 키 노출 시 전면 권한 탈취 위험 | 1시간 유효 단기 토큰 발급으로 안전함 |
| 엔드포인트 URL | https://fcm.googleapis.com/fcm/send | https://fcm.googleapis.com/v1/projects/{project_id}/messages:send |
| 요청 페이로드 | { "to": "...", "notification": {...} } | { "message": { "token": "...", "notification": {...} } } |
FCM HTTP v1 API를 통해 메시지를 전송하려면 아래 5가지 프로세스를 순차적으로 진행해야 한다.
- 1단계: Firebase 콘솔의 프로젝트 설정 > 서비스 계정 탭으로 이동한다.
- 2단계: [새 비공개 키 생성] 버튼을 클릭하여 JSON 형태의 인증 키 파일을 다운로드한다.
- 3단계: 서버 환경에서 JSON 키에 포함된
client_email과private_key정보를 읽어온다. - 4단계: RS256(SHA-256 with RSA) 알고리즘으로 JWT(JSON Web Token)를 생성하고 서명한다.
- 5단계: Google OAuth 2.0 엔드포인트(
https://oauth2.googleapis.com/token)에 JWT를 전송하여 Access Token을 발급받은 뒤 FCM API를 호출한다.
외부 묵직한 SDK 라이브러리를 의존성에 추가하지 않고, PHP 내장 OpenSSL과 cURL 기능만 활용해 깔끔하게 구현하는 실무 예제다.
기존 Legacy 방식 코드와 신규 v1 API 방식 코드의 페이로드 구성을 비교해보자.
✗ 잘못된 코드(Legacy API 방식 - 현재는 호출 시 실패 또는 오류 발생)
$headers = [
'Authorization: key=' . $legacyServerKey,
'Content-Type: application/json'
];
$body = json_encode([
'to' => $deviceToken,
'notification' => [
'title' => '공지사항',
'body' => '새로운 업데이트가 있습니다.'
]
]);왜 안 되는가: Legacy API 엔드포인트와 인증 방식은 서비스가 종료되었으므로 401 Unauthorized 오류나 권한 거부 에러가 발생한다.
✓ 올바른 코드(FCM HTTP v1 API 규격 적용)
$headers = [
'Authorization: Bearer ' . $accessToken,
'Content-Type: application/json; charset=UTF-8'
];
$body = json_encode([
'message' => [
'token' => $deviceToken,
'notification' => [
'title' => '공지사항',
'body' => '새로운 업데이트가 있습니다.'
],
'data' => [
'type' => 'notice',
'link_id' => '1042'
]
]
]);왜 이게 맞는가: v1 API 규격에 따라 페이로드를 message 객체로 감싸고 OAuth 2.0 Bearer 토큰을 인증 헤더에 전송하므로 정상 처리된다.
결과/출력값:
{
"name": "projects/my-firebase-project/messages/0:1711234567890123%abcdef123456789"
}
서비스 계정 JSON 키 파일로부터 Access Token을 동적으로 생성하는 PHP 모듈 코드다.
✗ 잘못된 코드(OAuth 인증 시 일반 client_credentials를 요청하는 잘못된 접근)
// 구글 서비스 계정은 단순 client_credentials 방식을 지원하지 않음
$ch = curl_init('https://oauth2.googleapis.com/token');
curl_setopt($ch, CURLOPT_POSTFIELDS, [
'grant_type' => 'client_credentials',
'client_id' => $serviceAccount['client_id']
]);
// 결과: unsupported_grant_type 또는 invalid_request 에러 발생왜 안 되는가: Google 인증 서버는 개인키로 서명된 RS256 JWT assertion 토큰을 필수 요구한다.
✓ 올바른 코드(OpenSSL 기반 JWT 서명 및 Access Token 발급)
function getFcmAccessToken(string $jsonKeyPath): string {
if (!file_exists($jsonKeyPath)) {
throw new Exception('FCM 서비스 계정 키 파일을 찾을 수 없습니다.');
}
$authConfig = json_decode(file_get_contents($jsonKeyPath), true);
$header = base64UrlEncode(json_encode(['alg' => 'RS256', 'typ' => 'JWT']));
$now = time();
$claims = base64UrlEncode(json_encode([
'iss' => $authConfig['client_email'],
'scope' => 'https://www.googleapis.com/auth/firebase.messaging',
'aud' => 'https://oauth2.googleapis.com/token',
'exp' => $now + 3600,
'iat' => $now
]));
$signatureInput = $header . '.' . $claims;
openssl_sign($signatureInput, $signature, $authConfig['private_key'], 'SHA256');
$jwt = $signatureInput . '.' . base64UrlEncode($signature);
$ch = curl_init('https://oauth2.googleapis.com/token');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query([
'grant_type' => 'urn:ietf:params:oauth:grant-type:jwt-bearer',
'assertion' => $jwt
])
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
return $response['access_token'] ?? '';
}
function base64UrlEncode(string $data): string {
return str_replace(['+', '/', '='], ['-', '_', ''], base64_encode($data));
}왜 이게 맞는가: Google OAuth 2.0 명세인 JWT Bearer Grant 규격을 정확히 준수하여 1시간 유효한 Access Token을 정상 획득한다.
결과/출력값:
ya29.c.c0ASRK0G... (정상 발급된 Google OAuth 2.0 Access Token 문자열 반환)
실제 운영 환경에 적용할 때 흔히 발생하는 예외 상황과 대처법이다.
✗ 서비스 계정 비공개 키 JSON 파일을 웹 루트(public_html) 폴더에 위치시키는 경우.
✓ 외부 사용자가 직접 URL로 접근할 수 없도록 웹 루트 상위 디렉토리나 접근이 차단된 안전한 폴더에 보관해야 한다.
✗ 푸시 메시지를 1건 전송할 때마다 매번 OAuth 2.0 토큰 발급 API를 호출하는 경우.
✓ 구글 API 서비스의 처리량 제한(Rate Limit)에 걸릴 수 있다. 발급받은 토큰은 Redis나 세션, 로컬 파일 캐시에 저장하여 50분 동안 재사용하는 캐싱 구조를 적용해야 한다.
✗ 발급받은 디바이스 토큰이 유효하지 않은 경우 예외 처리를 누락하는 경우.
✓ FCM API 응답에서 UNREGISTERED 또는 INVALID_ARGUMENT 에러 코드가 반환되면 해당 토큰을 데이터베이스에서 즉시 삭제하거나 비활성화 처리해야 한다.
FCM HTTP v1 API 마이그레이션은 모바일 앱 푸시 서비스의 안정성과 보안을 지속하기 위한 필수 작업이다. 액세스 토큰 캐싱과 안전한 서비스 계정 관리라는 작은 습관이 모여서 서버 부하 경감과 자산 보호라는 큰 효과를 만든다는 점을 잊지 말자. 이 글의 JWT 생성 모듈과 cURL 요청 코드를 참고해 기존 Legacy 코드 구조를 신규 v1 규격으로 전환하면, 중단 없는 안정적인 푸시 알림 환경을 구축할 수 있을 것이다.