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