iOS 인증서 및 프로비저닝 프로파일 알아보기

iOS code 서명에는 두 가지 요소가 필요합니다. 하나는 인증서 앱을 누가 빌드했는지 증명하고, provisioning profile은 어떤 앱인지, 어떤 기기에서 실행할 수 있는지, 어떤 capability를 사용할 수 있는지를 정의합니다. 인증서와 개인 키, 그리고 일치하는 프로필이 모두 갖춰지지 않으면 Xcode는 기기용 빌드를 거부하고 App Store Connect는 업로드를 거부합니다.

이 가이드에서는 각 구성 요소, 개발·ad hoc·TestFlight·App Store·enterprise 빌드에 필요한 조합, Mac 유무와 관계없이 생성하는 방법, 그리고 마주치게 될 오류를 해결하는 방법을 설명합니다.

Apple이 code 서명을 요구하는 이유

Apple은 알려진 개발자까지 추적할 수 있는 code만 iPhone에서 실행되도록 허용합니다. 서명은 Apple에 세 가지 보장을 제공합니다:

1. 신원: 특정 Apple Developer 팀의 구성원이 바이너리에 서명했음을 보장합니다.
2. 무결성: 서명 후 아무도 바이너리를 수정하지 않았음을 보장합니다. 단 1바이트만 바뀌어도 서명은 깨집니다.
3. 권한 부여: 앱이 이러한 entitlement(push, iCloud, Sign in with Apple, App Groups 등)를 갖고 이 기기에서 허용됨을 보장합니다.

인증서는 첫 두 가지를 제공합니다. 프로비저닝 프로필은 세 번째를 제공합니다.

기본 구성 요소

가장 흔한 혼동: .cer 파일만으로는 쓸모가 없습니다. 서명에는 CSR을 생성한 개인 키가 필요합니다. 해당 키를 분실했다면 새 인증서를 만들어야 합니다.

인증서 유형

Apple 개발용

개발 중 Xcode에서 자체 기기로 빌드를 실행하는 데 사용됩니다. 개발 인증서는 개별 개발자에게 속하며, Apple은 컴퓨터 이름으로 라벨링합니다. 팀의 각 개발자는 자신의 인증서를 가질 수 있습니다.

Apple Distribution

Ad Hoc 배포, TestFlight 및 App Store용 빌드 서명에 사용됩니다. 배포 인증서는 팀에 속하며, Account Holder 또는 Admin 역할만 생성할 수 있습니다. Apple은 팀이 보유할 수 있는 인증서 수를 제한하므로, 모든 개발자가 각각 생성하는 대신 보안 저장소에서 하나를 공유하세요.

아직도 iOS 개발 및 iOS 배포 구형 계정에서 볼 수 있습니다. 이는 Xcode 11 이전의 유형입니다. Apple Development와 Apple Distribution이 이를 대체하며 iOS, iPadOS, macOS, tvOS, watchOS, visionOS 전체에서 작동합니다.

그 밖에 접할 수 있는 인증서 유형

• Developer ID Application / Installer: Mac App Store 외부에서 배포되는 Mac 앱용. iOS에는 사용되지 않음.
• Apple Push Notification service SSL: 레거시 푸시 인증서. 대신 APNs 인증 키 (.p8)를 사용하세요. 매년 만료되지 않으며 팀의 모든 앱에서 작동합니다. 참고: APNs 인증서 가이드.
• Apple Pay 상인 ID, Pass Type ID, 웹사이트 Push ID: 특정 서비스용.

프로비저닝 프로파일 유형

프로파일은 하나의 App ID에바인딩됩니다. 앱에 확장 기능(위젯, 알림 서비스 확장, 공유 확장)이 있는 경우 각 타깃은 고유한 번들 ID를 가지며 자체 프로파일이 필요합니다.

구성 요소 간의 관계

Xcode 또는 빌드 서비스가 Capacitor 앱에 서명할 때 다음을 확인합니다:

1. 타겟의 번들 ID(예: com.example.app)가 프로필의 App ID와 일치합니다.
2. 서명에 사용된 인증서가 프로필에 나열된 인증서 중 하나입니다.
3. 해당 인증서의 개인 키는 키체인에 있습니다.
4. 개발 및 ad hoc 빌드의 경우, 기기의 UDID는 프로파일에 있습니다.
5. Entitlements 파일(push, associated domains, App Groups)은 App ID와 프로파일이 허용하는 권한의 하위 집합입니다.

검사가 하나라도 실패하면 런타임 크래시가 아니라 서명 에러가 발생합니다. 배포 전에 문제를 알 수 있다는 점이 좋습니다.

어떤 조합이 필요한가요?

TestFlight는 App Store와 동일한 동일한 것을 공유하고 signing을 사용합니다. 별도의 TestFlight 프로필은 없습니다. 빌드를 하나 upload하고 App Store Connect에서 테스터 배포, 심사 제출 또는 둘 다로 보낼지 결정하면 됩니다.

인증서 및 프로필 생성

옵션 1: Xcode가 signing을 관리하도록 설정

로컬 개발 시 가장 간편한 방법입니다. 다음을 여세요: ios/App/App.xcworkspace (또는 .xcodeproj Capacitor 8 프로젝트가 Swift Package Manager를 사용하는 경우), 대상(target)을 선택하고 앱 열고 Signing & Capabilities, 체크하고 Signing 자동 관리 팀을 선택하세요. Xcode가 개발용 인증서를 생성하고, 연결된 기기를 등록하며, 프로파일을 생성해 줍니다.

CI에서는 자동 서명이 까다로워집니다. 빌드 머신이 팀 계정에 접근해야 하고 인증서를 직접 생성하기 때문입니다. 대부분의 팀은 릴리스 빌드에서 수동 서명으로 전환하거나, API 키 기반 서명을 지원하는 빌드 서비스를 사용합니다.

옵션 2: Mac에서 수동으로 생성하기

1. 열기 키체인 접근 > 인증서 지원 > 인증 기관에서 인증서 요청. 이메일을 입력하고, 선택하세요 디스크에 저장됨. 이렇게 하면 키체인에 개인 키가 생성되고 .certSigningRequest 다운로드됩니다.
2. Apple Developer 포털에서 다음으로 이동하세요: Certificates, Identifiers & Profiles > Certificates > +, 다음을 선택합니다: Apple Distribution (또는 Apple Development)을 선택하고 CSR을 업로드하세요.
3. 다음을 다운로드한 뒤 .cer 더블 클릭하세요. Keychain Access가 개인 키와 연결해 줍니다.
4. CI용으로 내보내려면: Keychain Access의 My Certificates에서, 인증서를 우클릭하여 내보내기를 선택하고 .p12 강력한 비밀번호로 저장하세요.

옵션 3: Mac 없이 생성하기

Linux 또는 Windows에서 OpenSSL을 사용해 전체 흐름을 수행할 수 있습니다:

# 1. Private key and CSR
openssl genrsa -out ios_distribution.key 2048
openssl req -new -key ios_distribution.key -out ios_distribution.csr \
  -subj "/emailAddress=you@example.com/CN=Example Inc/C=US"

# 2. Upload ios_distribution.csr in the Apple Developer portal,
#    download the certificate as distribution.cer

# 3. Convert the .cer (DER) to PEM
openssl x509 -in distribution.cer -inform DER -out distribution.pem -outform PEM

# 4. Build the .p12 (signing identity)
openssl pkcs12 -export -inkey ios_distribution.key -in distribution.pem \
  -out ios_distribution.p12 -legacy

이 -legacy OpenSSL 3에서는 플래그가 중요합니다. 플래그가 없으면 .p12 macOS 키체인 도구가 비밀번호가 정확해도 “비밀번호가 잘못되었습니다” 오류로 거부하는 암호화 알고리즘을 사용합니다.

OpenSSL을 설치하지 않으려면 iOS 인증서 생성기 CSR과 개인 키를 대신 생성해 줍니다. 이 값들은 저장하지 않는 무상태 Capgo 엔드포인트에서 생성되며, 해당 엔드포인트의 .cer 대상 .p12 변환기는 브라우저 내에서 완전히 실행됩니다. 보안 정책상 키를 로컬 머신에서 생성해야 한다면, 위의 OpenSSL 명령어를 사용하세요.

프로파일 생성하기

1. Identifiers > +: 정확한 bundle ID로 App ID를 등록하고, 사용하는 기능(Push Notifications, Sign in with Apple, Associated Domains 등)을 활성화합니다.
2. Devices > +: 개발 및 ad hoc 프로파일의 경우 각 테스터의 UDID를 등록합니다. 테스터는 휴대폰에서 바로 iOS UDID 찾기를 통해 UDID를 확인할 수 있으며, Mac이나 케이블은 필요 없습니다.
3. Profiles > +: 프로파일 유형, App ID, 인증서, 디바이스를 선택합니다. 이름은 예를 들어 다음과 같이 명확하게 지정하세요. com.example.app AppStore 2026.
4. 다음을 다운로드한 뒤 .mobileprovision 다운로드됩니다.

나중에 디바이스나 기능을 추가하면 프로필을 재생성하고 다시 다운로드해야 합니다. 기존 프로필은 자동으로 업데이트되지 않습니다.

프로필 검사

어떤 .mobileprovision 파일은 서명된 plist입니다. macOS에서는 이렇게 읽을 수 있습니다:

security cms -D -i App_Store.mobileprovision > profile.plist
/usr/libexec/PlistBuddy -c "Print :Name" profile.plist
/usr/libexec/PlistBuddy -c "Print :ExpirationDate" profile.plist
/usr/libexec/PlistBuddy -c "Print :Entitlements" profile.plist
/usr/libexec/PlistBuddy -c "Print :ProvisionedDevices" profile.plist

Linux에서는 openssl smime -inform der -verify -noverify -in App_Store.mobileprovision plist를 출력합니다.

빌드된 .ipa 에 어떤 서명이 적용되었는지 확인하려면:

unzip -q App.ipa -d ipa
codesign -dvv ipa/Payload/App.app
codesign -d --entitlements :- ipa/Payload/App.app

만료 및 갱신

• 인증서 생성일로부터 1년간 유효합니다.
• Provisioning 프로파일 1년 후 만료되며, 포함된 인증서가 만료되거나 폐기되면 그보다 일찍 만료될 수 있습니다.
• App Store 앱은 계속 작동합니다 배포 인증서가 만료된 후에도. Apple은 App Store 다운로드를 재서명합니다. 새 빌드를 업로드할 때만 새 인증서가 필요합니다.
• Ad Hoc 및 개발 빌드는 실행을 중단합니다 프로파일이 만료된 후. 테스터는 앱이 시작 시 충돌하는 것을 확인합니다.
• TestFlight 빌드 업로드 후 90일 후 만료되며, 인증서와 무관합니다.
• Enterprise 앱은 작동을 중단합니다 기업 인증서가 만료되거나 폐기되면 모든 기기에서 발생합니다. 만료 전에 갱신하세요.
• 기기 슬롯 멤버십 연도당 1회 리셋됩니다. 기기를 제거해도 다음 멤버십 연도가 시작될 때까지 슬롯이 해제되지 않습니다.

인증서 만료일을 공유 캘린더에 등록하세요. 저희 인증서 관리 가이드 에서 모니터링 및 로테이션을 더 자세히 다룹니다.

자주 발생하는 오류 및 해결 방법

“서명 인증서 ‘iOS Distribution’을 찾을 수 없음” 또는 “서명 인증서가 유효하지 않습니다”: 개인 키가 이 키체인에 없습니다. 다음을 가져오세요. .p12, 또는 아무도 키를 가지고 있지 않다면 새 인증서를 생성하세요.

“프로비저닝 프로필에 서명 인증서가 포함되어 있지 않음”: 프로필이 다른 인증서로 생성되었습니다. 포털에서 프로필을 편집하고 현재 인증서에 체크한 후 재생성하여 다운로드하세요.

프로비저닝 프로필에 현재 선택된 디바이스가 포함되어 있지 않습니다: UDID를 등록한 후 프로필을 재생성하세요. TestFlight 또는 App Store에는 필요하지 않습니다.

“Provisioning profile이 Push Notifications 기능을 지원하지 않습니다”: App ID에서 해당 capability를 활성화한 후 프로필을 재생성하세요. 프로필은 스냅샷입니다.

“이 실행 파일에 대한 유효한 프로비저닝 프로필을 찾을 수 없습니다” : 설치 시: 디바이스가 ad hoc 프로필에 없거나, 프로필이 만료된 경우.

앱이 설치된 후 즉시 종료됨: iOS 16 이상에서 개발 및 ad hoc 빌드는 디바이스에서 Developer Mode가 필요합니다. 참고: iOS에서 Developer Mode 활성화 방법.

Extensions 서명 실패: 각 extension target에는 고유한 App ID와 profile이 필요합니다. App뿐 아니라 Signing & Capabilities의 모든 target을 확인하세요.

Linux에서 만든 .p12를 가져올 때 “Invalid password” 오류: 다음 명령으로 다시 빌드하세요 openssl pkcs12 -export ... -legacy.

SDK 버전 업로드 거부됨: 2026년 4월부터 App Store Connect는 Xcode 26 및 iOS 26 SDK로 빌드된 빌드를 요구합니다. Xcode 또는 CI 이미지를 업데이트하세요. Capacitor 8은 이미 Xcode 26이 필요합니다.

팀을 위한 권장 사항

• 팀당 Apple Distribution 인증서 하나를 다음 위치에 저장하세요: .p12 비밀번호 관리자나 secrets store에 저장하고, 비밀번호는 따로 보관하세요.
• 절대로 이메일로 .p12 파일을 보내거나 git에 커밋하지 마세요.
• App Store Connect API 키 (.p8)를 Apple ID 비밀번호 대신 업로드에 사용하세요.
• 프로파일 이름에는 bundle ID, 유형, 연도를 포함하세요.
• 팀을 떠나는 인원의 인증서는 폐기(Revoke)하세요.
• 앱이 사용하는 모든 bundle ID, extension, capability 목록을 문서로 관리하세요.

Capacitor 앱용 클라우드 서명

모든 개발자 데스크에 Mac이 없어도 iOS 빌드를 배포할 수 있습니다. Capgo 빌드 Capacitor는 Capgo의 macOS 머신을 사용하여 Capacitor 앱을 빌드합니다. 사용 방법은 .p12 및 제공한 프로필을 사용합니다. 자격 증명은 빌드에만 사용되며 Capgo 서버에 저장되지 않습니다. CLI에서 한 번만 저장하세요:

bunx @capgo/cli@latest build credentials save --appId com.example.app --platform ios
bunx @capgo/cli@latest build request com.example.app --platform ios --path .

이 Capgo Build iOS 문서 TestFlight 업로드용 App Store Connect API 키를 포함한 정확한 자격 증명 옵션을 ad_hoc 테스터 빌드용 모드를 나열합니다.

첫 번째 빌드가 TestFlight에 올라가면, JavaScript와 에셋 변경 사항을 Capgo Live Update 사용하기 모든 수정마다 새 바이너리를 다시 서명할 필요 없이 배포할 수 있습니다. 네이티브 code 변경 사항 및 새로운 기능은 여전히 스토어를 통한 서명된 빌드가 필요합니다.

다음 단계

• 먼저 계정이 필요하신가요? Apple 및 Google Play 개발자 계정 만들기.
• 테스터에게 빌드를 전달할 준비가 되셨나요? 테스터에게 iOS 및 Android 앱을 배포하는 방법.
• 제출을 앞두고 계신가요? 우리의 iOS 앱 제출 가이드를 읽어보세요.