Apple Push Notification service 인증서는 유효 기간이 1년이며, 기기 통신 중단을 방지하려면 매년 Apple Developer Portal에서 갱신해야 합니다. Capacitor 앱을 관리하고 있다면, 인증서가 만료되거나 취소될 경우 앱 자체는 정상이어도 알림 전송이 중단될 수 있습니다.
이러한 문제는 대개 최악의 타이밍에 발생합니다. 앱을 출시하거나 캠페인을 예약했는데 갑자기 알림 전송이 끊기는 식입니다. 애플리케이션 서버는 여전히 작업을 수락할 수 있지만, APNs는 메시지가 기기에 도달하기 전 TLS 연결을 거부할 수 있습니다. 단순히 새 인증서를 만드는 것이 해결책은 아닙니다. 시스템이 어떤 APNs 인증을 사용하는지 파악하고, 개인 키를 보존하며, 갱신 계획을 세우고, 적절한 워크로드를 토큰 기반 인증으로 전환해야 합니다.
목차
- 푸시 알림이 작동하지 않는 이유
- APNs 인증서 생성 및 다운로드 방법
- 인증서를 Private Key로 내보내기
- 새로운 토큰 기반 인증 방식으로 마이그레이션
- 인증서 수명 주기 갱신 및 관리
- 문제 해결 및 인증 정보 분실 대응
푸시 알림이 작동하지 않는 이유
APNs는 서비스 제공자 서버와 사용자의 Apple 기기 사이에서 중개 역할을 합니다. 서버가 Apple에 인증을 거쳐 알림을 제출하면, APNs가 이를 등록된 앱과 기기로 전달합니다. 만약 인증서가 만료되었거나, 취소되었거나, 잘못된 ID와 연결되었거나, 잘못 설치되었다면 알림 전달이 시작되기도 전에 요청이 실패할 수 있습니다.
Apple은 APNs가 취소된 인증서 목록을 관리하며, 해당 목록에 포함된 인증서를 사용하는 서버의 TLS 연결을 거부한다고 밝히고 있습니다. 즉, 인증서 관리는 단순한 관리적 선택 사항이 아니라 알림 전달을 위한 필수 요건입니다. 이 경우 서버는 로컬에서 알림 작업을 계속 처리할 수 있지만, Apple 측에서 제공자 연결을 거부하게 됩니다.
앱 푸시와 MDM 푸시 구분하기
가장 먼저 확인해야 할 진단 질문은 간단합니다: 어떤 서비스를 운영하려고 하시나요?
| 인증 경로 | 기능 | 일반적인 관리 주체 |
|---|---|---|
| 앱 푸시 | 최종 사용자 기기에 알림 및 기타 앱 알림을 전송합니다 | 모바일 또는 백엔드 엔지니어링 |
| MDM Push | 기기 관리 플랫폼이 관리 대상 Apple 기기와 통신할 수 있게 합니다 | IT, 엔드포인트 또는 엔터프라이즈 모빌리티 관리 |
이 인증서들은 서로 호환되지 않습니다. MDM push 인증서가 만료되면 MDM 플랫폼이 등록된 기기와의 연결을 잃을 수 있고, App Push 인증서가 유효하지 않으면 애플리케이션 백엔드에서 알림 전송이 실패할 수 있습니다. 이 둘을 모두 하나의 “Apple push certificate” 문제로 취급하면 잘못된 방향으로 트러블슈팅을 하게 됩니다.
Capacitor 및 Ionic 팀의 경우, 사용자에게 표시되는 알림과 관련된 경로는 일반적으로 앱 푸시입니다. 앱에는 여전히 Push Notifications 권한, 올바른 서명, 기기 등록, 그리고 적절한 APNs 환경으로 전송하는 백엔드가 필요합니다. 만약 팀에서 OTA 방식으로 웹 에셋을 배포하고 있다면, 해당 릴리스 워크플로우를 push 인증과 분리하여 관리하세요. Capacitor notifications 플러그인 문서 에서는 애플리케이션 측 통합을 다루며, APNs 인증서는 프로바이더 설정에 포함됩니다.
UI가 아닌 거절 사유부터 확인하세요
알림 문구를 수정하거나 앱을 다시 빌드하기 전에, 프로바이더 서버에서 받은 APNs 응답을 먼저 확인하세요. 그다음 bundle identifier, 인증서 ID, 환경 및 인증서 상태를 검증해야 합니다. 알림 권한 문제는 사용자가 알림을 보는 기능에 영향을 주지만, APNs의 TLS 거절(rejection) 문제를 설명해주지는 않습니다.
릴리스 후 오류가 발생했다면 새 빌드의 서명(signing)과 권한(entitlements)을 이전 빌드와 비교해 보세요. 앱 변경 없이 오류가 발생했다면 인증서 만료, 폐기, 신뢰 저장소(trust-store) 변경 및 배포용 secret을 먼저 점검해야 합니다. 더 자세한 구현 방법은 다음 가이드를 참고하세요: Expo 푸시 알림 설정.
APNs 인증서 생성 및 다운로드
인증서가 잘못된 App ID로 발급되었거나 개인 키(private key)가 다른 Mac에 남아 있는 경우, 첫 알림을 보내기도 전에 푸시 배포가 실패할 수 있습니다. Apple의 워크플로우는 두 단계로 나뉩니다. 먼저 사용자의 기기에서 인증서 서명 요청 (CSR)(CSR)를 생성하면, Apple이 선택된 App ID에 대해 이를 서명합니다. CSR은 서버 자격 증명이 아닙니다. 이는 발급된 인증서를 로컬에서 생성한 개인 키와 연결하는 역할을 합니다.
App ID 준비하기
Apple Developer 포털에 로그인한 후 Certificates, Identifiers & Profiles. Select Identifiers에서 앱의 bundle identifier를 선택하고 설정 화면을 엽니다. 다음 사항을 확인하세요: 푸시 알림 무엇을 발급하기 전에 활성화되어야 합니다.
APNs 인증서는 애플리케이션 ID와 연결됩니다. 이름이 비슷한 다른 번들 ID를 선택하지 마세요. 각 애플리케이션을 독립적으로 구성하고 그에 맞는 인증서를 발급해야 합니다.
키를 보관할 Mac에서 다음을 실행하세요. 키체인 접근 를 열어 CSR을 생성하거나 조직에서 승인한 인증서 도구를 사용하세요. 요청 파일과 개인 키는 동일한 관리 권한 하에 두어야 합니다. 다른 관리자가 CSR을 생성하면, 나중에 서버 번들 사용에 필요한 개인 키를 해당 관리자가 보유하게 될 수 있습니다.
서명된 인증서를 발급합니다.
의 Certificates 메뉴에서 Apple Push Notification service 인증서 옵션을 선택하세요. App ID를 선택하고 CSR을 upload한 뒤 요청을 제출합니다. Apple에서 발급한 인증서를 download하세요.
개인 키를 보유한 Mac에서 download한 파일을 더블 클릭하세요. 그러면 다음 위치에 설치됩니다. 키체인 접근에서 인증서와 그에 매칭되는 개인 키를 확인할 수 있습니다. 해당 키 없이 인증서만 가져오면 백엔드에 필요한 완전한 인증 정보를 제공할 수 없습니다.
애플리케이션 식별 정보, 환경, 소유자 및 만료 상세 정보를 기록하는 명명 규칙을 사용하세요. 원본 인증서, CSR 소유 정보, 포털 계정 상세 정보를 팀의 자격 증명 시스템에 저장해야 합니다. 개발자의 Downloads 폴더나 개인 노트북은 운영 백업 수단이 될 수 없습니다.
이 인증서는 전송 과정의 한 부분만 지원합니다. 앱은 원격 알림(remote notifications)을 등록해야 하고, 서버는 생성된 디바이스 토큰을 보관해야 하며, 프로바이더는 매칭되는 토픽과 환경을 사용하여 전송해야 합니다. 이러한 의존 관계를 동일한 런북(runbook)에 함께 관리하세요. 클라이언트 측 설정은 다음을 참조하세요: Capacitor notifications 통합 가이드. 이 인증서를 일회성 다운로드 파일이 아닌 관리형 자격 증명으로 취급해야 합니다. 나중에 인증서를 내보내거나, 토큰을 마이그레이션하거나, 갱신 및 복구할 때 키를 누가 제어하는지 아는 것이 중요하기 때문입니다.
인증서를 개인 키로 내보내기
다운로드한 Apple 인증서는 Node.js 서비스나 관리형 푸시 프로바이더에서 즉시 사용할 수 있는 상태가 아닙니다. 서버에는 인증서와 그에 대응하는 개인 키가 필요하며, 보통 다음과 같은 형식으로 패키징됩니다: PKCS#12 .p12 파일.
열고 키체인 접근 인증서를 설치한 Mac에서 APNs 인증서를 검색하여 확장하거나 검사한 뒤, 일치하는 identity 및 만료 정보가 포함된 private key를 찾습니다. 인증서와 private key를 함께 선택한 후, export 기능을 사용하여 .p12 파일로 저장하세요.
배포 전 bundle 검증하기
export에 강력한 비밀번호를 설정하세요. 이 비밀번호는 bundle 내부의 private key를 보호하므로, repository, 티켓, 채팅 메시지, build log에 저장하지 마세요. 파일과 비밀번호는 secret-management 시스템을 통해 upload하고, 알림을 전송하는 서비스에만 접근 권한을 부여하세요.
실무 원칙: 일치하는
.p12private key가 없는 file은 완전한 provider 자격 증명이 아닙니다.
운영 환경에 적용하기 전, 통제된 환경에서 bundle을 테스트하세요. 백엔드가 파일을 로드하고, APNs 연결을 설정하며, Apple이 요청을 거부했을 때 구조화된 에러를 반환하는지 확인해야 합니다. Capgo와 같은 provider가 iOS push 자격 증명을 요청한다면 파일을 .p12 비밀번호와 함께 지정된 secret 설정을 통해 upload하고, 두 값을 애플리케이션 code에 직접 포함하지 마세요.
이 형식은 레거시 워크플로우의 취약점도 드러냅니다. 원본 private key를 보관하고, 수동 export를 반복하며, 파일을 보호하고, 갱신 시점에 deployment secret을 교체해야 합니다. 여러 앱을 운영하는 팀은 어떤 bundle이 어떤 App ID에 속하는지 놓치기 쉽습니다.
사용하세요: CI/CD pipeline에서의 안전한 secret management 자격 증명을 읽거나 교체할 수 있는 사람을 제어하세요. 업로드 및 교체에 대한 감사 추적은 유지하되, 개인 키나 .p12 password.
새 백엔드 작업에서는 인증서 인증이 여전히 적절한지 검토하세요. 기존 통합에는 인증서 인증이 필요할 수 있습니다. .p12하지만 토큰 인증을 사용하면 보통 프로바이더 연결에서 매년 인증서를 교체할 필요가 없어집니다. 다만 자격 증명 관리가 사라지는 것은 아니며, 보호하고 교체할 대상이 달라질 뿐입니다.
새 토큰 기반 인증으로 마이그레이션
Apple은 APNs 인증을 프로바이더 토큰 방식으로 전환했으며, 이는 흔히 p8 워크플로우라고 불립니다. 장기 TLS ID를 위해 인증서와 개인 키를 제시하는 대신, 프로바이더가 Apple Push Notification service Authentication Key로 인증 토큰에 서명합니다.
Apple Developer 포털의 Certificates, Identifiers & Profiles 섹션에서 키를 생성하세요., 그런 다음 열고 Keys 에서 APNs 인증 키를 등록하세요. 다운로드한 .p8 파일과 관련 Key ID 및 Team ID를 보안 저장소에 기록해 두세요. 다운로드한 파일은 매우 중요한 서명 비밀값으로 취급해야 합니다.
마이그레이션을 신중하게 진행하세요
테스트되지 않은 환경에서 파일만 교체하여 운영 트래픽을 전환하지 마세요. 기존 인증서 경로와 병행하여 토큰 인증을 구축하고, sandbox 및 production 동작을 검증하며 APNs 응답을 비교하세요. 그 후 통제된 배포 과정에서 프로바이더 설정을 변경하세요.
마이그레이션을 통해 전송 경로에서 인증서 갱신 및 Keychain 내보내기 단계가 제거되지만, 팀 내에 명확한 관리 모델은 여전히 필요합니다. 누가 키를 생성, 취소 및 배포할 수 있는지 결정하세요. 프로바이더 토큰에 서명하는 백엔드 서비스에 대한 액세스를 제한하고, 현재 키를 사용할 수 없게 되기 전에 비상 교체 프로세스가 마련되어 있는지 확인하세요.
Capacitor 앱의 경우, 클라이언트에는 여전히 올바른 알림 등록 및 entitlements가 필요합니다. 이번 마이그레이션은 주로 서버-APNs 인증 방식을 변경하는 것이며, 디바이스 토큰 등록 code 방식은 변경되지 않습니다. 백엔드에서는 토큰을 올바른 애플리케이션 및 환경과 계속 연결해야 합니다.
인증서가 여전히 필요한 경우를 파악하세요
일부 엔터프라이즈 도구와 기존 통합 방식은 여전히 인증서 기반 설정을 사용합니다. 수신 시스템이 이를 지원하고 팀에서 전체 경로를 테스트하기 전까지는 p8 마이그레이션을 강제하지 마세요. 전환 기간 동안 기존 인증 정보를 안전하게 보호하되, 토큰 인증이 가능한 상황이라면 새로운 의존성을 만들지 마세요.
주변 애플리케이션 흐름을 파악해야 한다면 다음을 검토하세요: Ionic 및 Capacitor Firebase 푸시 알림. Firebase가 애플리케이션 전달 레이어를 제공할 수 있지만, Apple 인증 정보, entitlements, 등록 및 APNs 응답은 여전히 세심한 설정이 필요합니다.
인증서 수명 주기 갱신 및 관리
APNs 인증서는 생성된 날부터 만료되는 프로덕션 의존성으로 취급해야 합니다. Apple에 따르면 이 인증서의 유효 기간은 생성일로부터 1년이며 기기 통신을 유지하려면 만료 전에 반드시 갱신해야 합니다. 또한 Apple은 갱신에 실패할 경우 사용자가 iOS, iPadOS, Mac 기기를 APNs에 다시 등록해야 할 수 있으며 서비스 중단이 발생할 수 있다고 경고합니다. Apple의 푸시 알림 인증서 갱신 문서.
갱신 절차는 다음과 같습니다:
- 새로운 CSR 생성: 승인된 워크플로우를 통해 요청을 생성하고 관련 키 자료를 보관하세요.
- 기존 Apple ID 사용: 기존 인증서 생성 시 사용했던 것과 동일한 Apple ID로 로그인하세요.
- 만료 예정인 인증서 선택: 선택 전 App ID, Subject DN, UID 및 만료 정보를 확인하세요. Renew.
- CSR 업로드: Apple Push Certificates Portal에서 새 요청을 제출하세요.
- 다운로드 및 재설치: 갱신된 인증서를 가져와서
.pem개인 키가 있는 곳에 설치하고, 교체용 파일을.p12서비스 제공업체가 요구하는 경우 내보내세요. - 배포 및 테스트: 서버 secret을 업데이트하고, 제어된 알림을 전송하며, APNs 응답을 확인하세요.
제공자별 포맷 비교
| 요구 사항 | 인증서 워크플로우 | 토큰 워크플로우 |
|---|---|---|
| 기본 secret | 인증서 및 개인 키 | .p8 인증 키 |
| 갱신 관련 이슈 | 인증서 만료 시 주기적인 교체 필요 | 매년 인증서를 교체할 필요 없음 |
| 배포 작업 | 설치, 페어링, 내보내기 및 업로드 | 서명 키 저장 및 토큰 생성 설정 |
| 주요 실패 위험 요소 | 잘못된 인증서, 개인 키 누락, 만료 또는 폐기 | 분실, 노출 또는 폐기된 인증 키 |
Apple의 인증서 생태계는 정기적인 신뢰 체인 업데이트가 필요합니다. Apple은 다음과 같이 APNs 서버 인증서 업데이트를 발표했습니다: sandbox는 2025년 1월 20일 및 production은 2025년 2월 24일이며, 이에 따라 신뢰 저장소에 다음 인증서가 포함되어야 합니다: SHA-2 Root USERTrust RSA Certification Authority 자세한 내용은 다음을 읽어보세요: Apple APNs 서버 인증서 관련 공지 플랫폼 체크리스트에 신뢰 저장소(trust-store) 소유권 관리를 포함하세요.
공유 갱신 캘린더, 담당자 지정, 배포 런북을 활용하세요. Capgo 인증서 관리 문서 iOS 배포 자격 증명을 모바일 릴리스 프로세스와 함께 관리하는 팀은 해당 런북과 함께 이 문서를 참고할 수 있습니다.
문제 해결 및 자격 증명 분실 시 대응 방법
가장 까다로운 상황은 만료 경고가 뜨는 때가 아닙니다. 인증서를 생성한 관리자가 퇴사했거나, 개인 키가 오래된 Mac에만 있거나, 정리 작업 중 인증서가 폐기(revoked)된 아침이 진짜 문제입니다. 표준 갱신 프로세스는 원래의 Apple ID와 정확한 인증서 식별 정보에 의존하므로, 파일 자체만큼이나 접근 권한과 출처가 중요합니다.
먼저 장애 유형을 분류하세요:
- 인증서 만료: 기존 계정을 통해 교체 인증서를 생성하고, 일치하는 개인 키로 재설치한 뒤, 프로바이더를 업데이트하고 전송 테스트를 진행하세요. 이미 기기 통신이 중단되었다면, 서버 측 교체만으로 모든 기기가 즉시 복구될 것이라 가정하지 말고 Apple의 복구 가이드를 따르세요.
- 인증서 폐기(Revoked): 기존 자격 증명을 복구 가능한 것으로 간주하지 마세요. Apple은 폐기된 인증서를 사용하는 서버의 TLS 연결을 거부하므로, 유효한 교체 인증서를 생성하고 활성 배포 환경에서 폐기된 secret을 제거해야 합니다. 누가 폐기했는지, 그리고 다른 시스템에서도 동일한 자격 증명을 복사해 사용 중인지 확인하세요.
- 분실됨
.p12비밀번호: 사용 가능한 비밀번호가 없는 인증서 파일은 운영 환경에서 사용할 수 없습니다. 보안 통제를 약화시키는 대신, 승인된 백업을 복구하거나 새 인증서를 발급받으세요. - 개인 키(Private Key) 분실: 공개 인증서를 다시 다운로드해도 개인 키는 복구되지 않습니다. 제어 가능한 환경에서 새로운 CSR을 생성하고 교체용 자격 증명을 발급받으세요.
- Apple ID 액세스 권한 분실: 조직의 신원 확인 및 배포 프로세스를 통해 계정 복구가 가능한지 확인하세요. 관련 포털을 통해 생성된 APNs 인증서에 대한 지원은 다음으로 문의해야 합니다: 배포 프로그램 지원.
복구에는 파일명이 아닌 신원 확인이 필요합니다. 사고가 발생하기 전에 Apple ID 소유자, App ID, 인증서 식별 정보, 개인 키 위치, 프로바이더 설정 및 교체 절차를 기록해 두세요.
운영 안전망 구축하기
인증서와 .p8 공유된 액세스 제어 금고에 키를 보관하세요. 또한 .p12 비밀번호는 파일과 분리하여 저장하고, 운영 환경의 접근 권한을 제한하며, 갱신에 사용된 포털 계정을 정확히 기록해야 합니다. CI/CD 시스템은 배포 시점에 시크릿을 주입해야 하며, 사용자가 알림 누락을 보고하기 전에 인증 실패를 감지할 수 있는 헬스 체크를 실행해야 합니다.
플랫폼에서 허용하는 경우, 제어된 교체 작업 동안 기존 자격 증명을 유지하되, 오래된 시크릿을 무기한 활성 상태로 두지 마세요. 프로바이더 환경, bundle identifier, device-token 저장소를 포함하여 운영 환경과 동일한 백엔드 경로에서 교체 테스트를 진행하세요.
장애가 이미 발생했다면, APNs 응답 본문과 타임스탬프를 보존하고, 최초로 거부된 요청을 식별한 뒤, 장애 발생 전후의 배포 시크릿을 비교하세요. 유효하지 않은 자격 증명에 대해 무한히 재시도하지 마세요. 먼저 식별 또는 인증 문제를 해결한 다음, 알려진 테스트 기기로 작은 확인용 알림을 보내세요.
Capgo는 Capacitor 알림 워크플로의 일부로 iOS 푸시 자격 증명을 저장하고 구성할 수 있습니다. 단, Apple 계정 액세스, 시크릿 관리 및 갱신 결정에 대한 책임은 팀에 있습니다. 자세한 내용은 Capgo 를 방문하여 모바일 배포 도구가 APNs 자격 증명 라이프사이클 및 릴리스 프로세스와 어떻게 조화를 이룰 수 있는지 확인해 보세요.
