Penjelasan iOS Certificates dan Provisioning Profiles

Signing iOS code menggunakan dua komponen. Sebuah certificate membuktikan siapa yang membuat aplikasi, dan sebuah provisioning profile menentukan aplikasi mana itu, perangkat mana yang boleh menjalankannya, dan kapabilitas apa yang bisa dipakai. Xcode menolak build untuk perangkat, dan App Store Connect menolak upload, kecuali sertifikat, private key, dan profile yang cocok semuanya selaras.

Panduan ini menjelaskan setiap bagian, kombinasi apa yang Anda butuhkan untuk build development, ad hoc, TestFlight, App Store, dan enterprise, cara membuatnya dengan atau tanpa Mac, serta cara memperbaiki error yang akan Anda temui.

Mengapa Apple mewajibkan signing code

Apple hanya mengizinkan iPhone menjalankan code yang bisa dilacak kembali ke developer yang dikenal. Signing memberi Apple tiga jaminan:

1. Identitas: biner tersebut ditandatangani oleh anggota dari tim Apple Developer tertentu.
2. Integritas: tidak ada yang memodifikasi binary setelah signing. Mengubah satu byte saja akan merusak signature.
3. Authorization: aplikasi diizinkan berjalan di perangkat ini, dengan entitlements tertentu (push, iCloud, Sign in with Apple, App Groups, dan sebagainya).

Sertifikat menyediakan dua yang pertama. Provisioning profile menyediakan yang ketiga.

Komponen penyusun

Kebingungan yang paling umum: sebuah .cer file tidak berguna jika berdiri sendiri. Signing butuh private key yang membuat CSR. Jika key tersebut hilang, buatlah sertifikat baru.

Tipe sertifikat

Apple Development

Digunakan untuk menjalankan build di perangkat sendiri dari Xcode selama development. Sertifikat Development milik developer individu, dan Apple melabelinya dengan nama komputer. Setiap developer dalam tim bisa punya milik sendiri.

Distribusi Apple

Digunakan untuk menandatangani build untuk distribusi Ad Hoc, TestFlight, dan App Store. Sertifikat Distribution milik tim, dan hanya peran Account Holder atau Admin yang bisa membuatnya. Apple membatasi jumlah sertifikat yang bisa dimiliki satu tim, jadi bagikan satu sertifikat lewat penyimpanan aman daripada membiarkan setiap developer membuat sendiri.

Anda mungkin masih melihat Pengembangan iOS dan Distribusi iOS pada akun lama. Itu tipe dari sebelum Xcode 11. Apple Development dan Apple Distribution menggantikannya dan berfungsi di iOS, iPadOS, macOS, tvOS, watchOS, dan visionOS.

Tipe sertifikat lain yang mungkin Anda temui

• Developer ID Application / Installer: untuk aplikasi Mac yang didistribusikan di luar Mac App Store. Tidak digunakan untuk iOS.
• SSL Apple Push Notification service: sertifikat push lama. Sebaiknya gunakan Kunci Autentikasi APNs (.p8), yang tidak kedaluwarsa setiap tahun dan berlaku untuk semua aplikasi dalam tim. Lihat panduan sertifikat APNs kami.
• Identitas Merchant Apple Pay, Pass Type ID, ID Push Website: layanan spesifik.

Tipe provisioning profile

Sebuah profil terikat pada satu App ID. Jika aplikasi Anda memiliki ekstensi (widget, notification service extension, share extension), setiap target punya bundle ID sendiri dan butuh profil sendiri.

Cara semua komponen bekerja

Saat Xcode atau layanan build menandatangani aplikasi Capacitor Anda, ia akan memeriksa:

1. Bundle ID pada target Anda (misalnya com.example.app) cocok dengan App ID di dalam profil.
2. Sertifikat yang digunakan untuk tanda tangan adalah salah satu sertifikat yang terdaftar di profil.
3. Private key untuk sertifikat tersebut tersedia di keychain.
4. Untuk build development dan ad hoc, UDID perangkat sudah ada di dalam profile.
5. File entitlements (push, associated domains, App Groups) adalah subset dari apa yang diizinkan oleh App ID dan profile.

Jika ada pengecekan yang gagal, Anda akan mendapat error signing, bukan runtime crash. Ini bagus karena Anda mengetahuinya sebelum rilis.

Kombinasi mana yang saya butuhkan?

TestFlight menggunakan sama signing seperti App Store. Tidak ada profil TestFlight terpisah. Anda cukup upload satu build dan tentukan di App Store Connect apakah akan dikirim ke tester, untuk review, atau keduanya.

Membuat certificate dan profile

Opsi 1: biarkan Xcode mengelola signing

Untuk development lokal, ini cara termudah. Buka ios/App/App.xcworkspace (atau .xcodeproj saat proyek Capacitor 8 Anda menggunakan Swift Package Manager), pilih App target, buka Signing & Capabilities, centang Kelola signing secara otomatis dan pilih team Anda. Xcode akan membuat development certificate, mendaftarkan perangkat yang terhubung, dan membuatkan profile untuk Anda.

Automatic signing akan menyulitkan di CI, karena build machine butuh akses ke akun team dan membuat certificate sendiri. Kebanyakan tim beralih ke manual signing, atau ke build service dengan API-key-based signing untuk release build.

Opsi 2: buat secara manual di Mac

1. Buka Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority. Masukkan email Anda, pilih Tersimpan di disk. Ini membuat private key di keychain Anda dan sebuah .certSigningRequest file.
2. Di portal Apple Developer, buka Sertifikat, Identifikasi & Profil > Sertifikat > +, pilih Distribusi Apple (atau Apple Development) dan upload CSR-nya.
3. Download the .cer dan klik dua kali. Keychain Access akan memasangkannya dengan private key.
4. Untuk ekspor ke CI: di Keychain Access, di bawah Sertifikat Saya, klik kanan pada sertifikat, lalu pilih Export, simpan sebagai .p12 dengan kata sandi yang kuat.

Opsi 3: buat tanpa menggunakan Mac

Anda bisa menjalankan seluruh alur menggunakan OpenSSL di Linux atau Windows:

# 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

Skill -legacy flag sangat penting pada OpenSSL 3: tanpanya, .p12 menggunakan algoritma enkripsi yang ditolak oleh tool macOS keychain dengan error “invalid password” meskipun kata sandinya benar.

Jika Anda tidak ingin menginstal OpenSSL, Generator sertifikat iOS membuatkan CSR dan private key untuk Anda. Keduanya berasal dari endpoint Capgo stateless yang tidak menyimpannya, dan hanya .cer ke .p12 converter berjalan sepenuhnya di browser Anda. Jika kebijakan Anda mewajibkan pembuatan key di mesin lokal, gunakan perintah OpenSSL di atas.

Membuat profile

1. Identifiers > +: daftarkan App ID dengan bundle ID yang tepat dan aktifkan capability yang Anda gunakan (Push Notifications, Sign in with Apple, Associated Domains…).
2. Perangkat > +: untuk profile development dan ad hoc, daftarkan UDID setiap tester. Tester bisa mendapatkannya langsung di ponsel menggunakan Pencari UDID iOS, tanpa perlu Mac atau kabel.
3. Profil > +: pilih tipe profile, App ID, certificate, dan device. Beri nama yang jelas, contohnya com.example.app AppStore 2026.
4. Download the .mobileprovision file.

Jika Anda menambahkan perangkat atau capability nanti, Anda harus membuat ulang dan mengunduh kembali profil tersebut. Profil yang sudah ada tidak diperbarui otomatis.

Memeriksa profil

A .mobileprovision file is a signed plist. On macOS you can read it:

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

Di Linux, openssl smime -inform der -verify -noverify -in App_Store.mobileprovision akan mencetak plist tersebut.

Untuk mengecek apa yang telah di-build .ipa ditandatangani dengan:

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

Masa berlaku dan perpanjangan

• Sertifikat berlaku selama satu tahun sejak dibuat.
• Profil provisioning kedaluwarsa setelah satu tahun, atau lebih cepat jika sertifikat di dalamnya kedaluwarsa atau dicabut.
• Aplikasi App Store tetap berfungsi setelah sertifikat distribusi kedaluwarsa. Apple melakukan re-sign pada unduhan App Store. Anda hanya butuh sertifikat baru untuk upload build baru.
• Build Ad Hoc dan development tidak bisa diluncurkan setelah profilnya kedaluwarsa. Tester akan melihat aplikasi crash saat dibuka.
• Build TestFlight kedaluwarsa 90 hari setelah upload, terlepas dari masa berlaku sertifikat.
• Aplikasi Enterprise berhenti berfungsi di setiap perangkat saat sertifikat enterprise kedaluwarsa atau dicabut. Perbarui sebelum masa berlaku habis.
• Slot perangkat di-reset sekali per tahun keanggotaan. Menghapus perangkat tidak akan mengosongkan slotnya sampai tahun keanggotaan berikutnya dimulai.

Masukkan tanggal kedaluwarsa sertifikat ke kalender bersama. Panduan manajemen sertifikat kami membahas pemantauan dan rotasi secara lebih mendalam.

Error umum dan solusinya

“Sertifikat penandatanganan ‘iOS Distribution’ tidak ditemukan” atau “Sertifikat penandatanganan tidak valid”: private key tidak ada di keychain ini. Impor .p12, atau buat sertifikat baru jika tidak ada yang punya key-nya.

“Provisioning profile tidak menyertakan sertifikat penandatanganan”: profil dibuat dengan sertifikat berbeda. Edit profil di portal, centang sertifikat saat ini, regenerasi, lalu download.

“Provisioning profile tidak menyertakan perangkat yang sedang dipilih”: daftarkan UDID, lalu buat ulang profile-nya. Tidak perlu untuk TestFlight atau App Store.

“Provisioning profile tidak mendukung capability Push Notifications”: aktifkan capability di App ID, lalu buat ulang profile-nya. Profile itu snapshot.

“Provisioning profile yang valid untuk executable ini tidak ditemukan” saat install: perangkat tidak terdaftar di ad hoc profile, atau profile sudah kedaluwarsa.

App terinstal lalu langsung tertutup: pada iOS 16 ke atas, build development dan ad hoc memerlukan Developer Mode di perangkat. Lihat cara mengaktifkan Developer Mode di iOS.

Extension gagal di-sign: setiap target extension butuh App ID dan profile sendiri. Cek setiap target di Signing & Capabilities, bukan cuma App.

“Invalid password” saat impor .p12 yang dibuat di Linux: build ulang dengan openssl pkcs12 -export ... -legacy.

Upload ditolak untuk versi SDK: sejak April 2026 App Store Connect mewajibkan build dengan Xcode 26 dan iOS 26 SDK. Update Xcode atau CI image Anda. Capacitor 8 sudah mewajibkan Xcode 26.

Best practice untuk tim

• Satu sertifikat Apple Distribution per tim, simpan sebagai .p12 di password manager atau secrets store, dengan password yang disimpan terpisah.
• Never email .p12 file atau commit ke git.
• Gunakan App Store Connect API keys (.p8) untuk upload daripada menggunakan password Apple ID.
• Beri nama profile dengan bundle ID, tipe, dan tahun.
• Revoke sertifikat anggota tim yang sudah keluar.
• Catat daftar setiap bundle ID, extension, dan capability yang digunakan app.

Cloud signing untuk aplikasi Capacitor

Anda tidak perlu menyediakan Mac di setiap meja developer untuk merilis build iOS. Capgo Build membangun Capacitor apps di mesin macOS Capgo menggunakan .p12 dan profil yang Anda berikan. Kredensial hanya digunakan untuk build dan tidak disimpan di server Capgo. Simpan sekali dari 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 .

Skill Dokumentasi Capgo Build iOS mencantumkan opsi kredensial yang tepat, termasuk kunci API App Store Connect untuk upload TestFlight dan ad_hoc mode untuk build tester.

Setelah build pertama Anda ada di TestFlight, Anda bisa mengirim perubahan JavaScript dan aset ke pengguna dengan Capgo live updates tanpa perlu re-signing binary baru untuk setiap perbaikan. Perubahan Native code dan kapabilitas baru tetap memerlukan build bertanda tangan melalui store.

Next steps

• Butuh akun terlebih dahulu? Cara membuat akun developer Apple dan Google Play.
• Siap kirim build ke tester? Cara distribusi aplikasi iOS dan Android ke tester.
• Mau submit? Baca panduan submit aplikasi iOS kami.