iOS Certificates dan Provisioning Profiles Dijelaskan

Signing iOS code menggunakan dua komponen. Sebuah sertifikat membuktikan siapa yang membuat aplikasi, dan profil provisioning 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 provisioning profile yang cocok semuanya selaras.

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

Mengapa Apple mewajibkan code signing

Apple hanya mengizinkan iPhone menjalankan code yang bisa dilacak Apple 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 di perangkat ini, dengan entitlements tertentu (push, iCloud, Sign in with Apple, App Groups, dan sebagainya).

Sertifikat menyediakan dua yang pertama. Profil provisioning menyediakan yang ketiga.

Komponen dasar

Kebingungan yang paling umum: sebuah .cer file tidak berguna sendiri. Signing butuh private key yang membuat CSR. Jika key itu hilang, buat sertifikat baru.

Tipe sertifikat

Pengembangan Apple

Digunakan untuk menjalankan build di perangkat Anda sendiri dari Xcode selama development. Sertifikat Development milik developer perorangan, dan Apple memberi label dengan nama komputer. Setiap developer di tim bisa punya sendiri.

Distribusi Apple

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

Anda mungkin masih melihat Pengembangan iOS dan Distribusi iOS pada akun lama. Itu adalah tipe sebelum Xcode 11. Apple Development dan Apple Distribution kini menggantikannya dan berfungsi untuk 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 di tim. Lihat panduan sertifikat APNs kami.
• Identitas Merchant Apple Pay, Pass Type ID, ID Push Website: layanan tertentu.

Tipe provisioning profile

Profil terikat ke 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 sama

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

1. Bundle ID di target Anda (misalnya com.example.app) cocok dengan App ID di profil.
2. Sertifikat yang dipakai untuk menandatangani 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 ada di dalam profile.
5. File entitlements (push, associated domains, App Groups) adalah subset dari yang diizinkan App ID dan profile.

Jika ada pengecekan yang gagal, Anda dapat error signing, bukan runtime crash — bagus, karena Anda tahu sebelum rilis.

Kombinasi mana yang saya butuhkan?

TestFlight menggunakan sama 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 sertifikat dan profile

Opsi 1: biarkan Xcode mengelola signing

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

Automatic signing jadi merepotkan di CI, karena mesin build 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 .certSigningRequest Anda.
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 mengekspor ke CI: di Keychain Access, di bawah Sertifikat Saya, klik kanan pada sertifikat, pilih Ekspor, simpan sebagai .p12 dengan kata sandi yang kuat.

Opsi 3: buat tanpa menggunakan Mac

Anda bisa melakukan seluruh alur dengan 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

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

Jika Anda tidak ingin menginstal OpenSSL, iOS certificate generator kami membuat 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 mengharuskan key dibuat di mesin Anda, gunakan perintah OpenSSL di atas.

Membuat provisioning 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 profil 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 profil, App ID, sertifikat, dan perangkat. Beri nama yang jelas, contohnya com.example.app AppStore 2026.
4. Download the .mobileprovision Anda.

Jika Anda menambahkan perangkat atau capability nanti, Anda harus membuat ulang dan mengunduh ulang profilnya. Profil yang sudah ada tidak diperbarui sendiri.

Memeriksa profil

Sebuah .mobileprovision file adalah plist yang ditandatangani. Di macOS, Anda bisa membacanya:

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 mencetak plist tersebut.

Untuk mengecek hasil build yang .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 awal jika sertifikat yang disertakan kedaluwarsa atau dicabut.
• Aplikasi App Store tetap berfungsi setelah sertifikat distribusi kedaluwarsa. Apple menandatangani ulang unduhan App Store. Anda hanya perlu sertifikat baru untuk mengunggah build baru.
• Build Ad Hoc dan development tidak bisa diluncurkan setelah profilnya kedaluwarsa. Penguji akan melihat aplikasi crash saat diluncurkan.
• Build TestFlight kedaluwarsa 90 hari setelah diunggah, tidak bergantung pada sertifikat.
• Aplikasi Enterprise berhenti berfungsi di setiap perangkat saat sertifikat enterprise kedaluwarsa atau dicabut. Perpanjang sebelum kedaluwarsa.
• Slot perangkat di-reset sekali per tahun keanggotaan. Menghapus perangkat tidak akan membebaskan slotnya hingga 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 memiliki key-nya.

“Provisioning profile tidak menyertakan signing certificate”: profil dibuat dengan sertifikat yang berbeda. Edit profil di portal, centang sertifikat saat ini, lalu regenerate dan download.

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

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

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

App ter-install lalu langsung tertutup: di iOS 16 ke atas, build development dan ad hoc butuh 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 mengimpor .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 yang dibuat dengan Xcode 26 dan SDK iOS 26. Perbarui Xcode atau image CI Anda. Capacitor 8 sudah mewajibkan Xcode 26.

Best practice untuk tim

• Satu sertifikat Apple Distribution per tim, disimpan sebagai .p12 di password manager atau secrets store, dengan kata sandi disimpan terpisah.
• Jangan pernah email .p12 file atau commit ke git.
• Gunakan API App Store Connect (.p8) untuk upload, bukan kata sandi Apple ID.
• Beri nama profil dengan bundle ID, tipe, dan tahun.
• Cabut sertifikat anggota tim yang keluar.
• Simpan daftar tertulis untuk setiap bundle ID, ekstensi, dan capability yang digunakan aplikasi.

Cloud signing untuk aplikasi Capacitor

Anda tidak perlu Mac di setiap meja developer untuk merilis build iOS. Build Capgo membangun aplikasi Capacitor 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 .

Panduan Dokumentasi Build iOS Capgo 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 Live updates Capgo tanpa perlu menandatangani ulang binary baru untuk setiap perbaikan. Perubahan code native dan kemampuan baru tetap membutuhkan build yang ditandatangani melalui store.

Langkah berikutnya

• Butuh akun dulu? 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 submission aplikasi iOS.