iOS Certificati e Profili di Provisioning Spiegati

IOS code di firma utilizza due pezzi. Un certificato prova chi ha costruito l'app, e un profilo di provisioning dice quale app è, quali dispositivi possono eseguirlo e quali funzionalità può utilizzare. Xcode rifiuta di costruire per un dispositivo, e App Store Connect rifiuta le upload, a meno che il certificato, la sua chiave privata e un profilo corrispondente non si allineino.

Questa guida spiega ogni pezzo, quale combinazione avete bisogno per lo sviluppo, ad hoc, TestFlight, App Store e build enterprise, come crearli con o senza un Mac, e come risolvere gli errori che incontrerete.

Perché Apple richiede code di firma

Apple consente solo agli iPhone di eseguire code che Apple può tracciare fino a un noto sviluppatore.

1. Identità: il binario è stato firmato da un membro di un team di sviluppatori Apple specifico.
2. Integrità: nessuno ha modificato il binario dopo la firma. Cambiare un solo byte rompe la firma.
3. Autorizzazione: l'app è consentita su questo dispositivo, con questi enti (push, iCloud, Accedi con Apple, Applicazioni Gruppo e così via).

Il certificato fornisce i primi due. I profili di provisioning forniscono il terzo.

Il materiale di costruzione

La confusione più comune: un .cer Un file è inutile da solo. La firma richiede la chiave privata che ha creato il CSR. Se perdi quella chiave, crea un nuovo certificato.

Tipi di certificato

Sviluppo Apple

Usato per eseguire build sulle proprie dispositivi da Xcode durante lo sviluppo. I certificati di sviluppo appartengono a un singolo sviluppatore e Apple li etichetta con il nome del computer. Ogni sviluppatore del team può avere il proprio.

Apple Distribution

Usato per firmare build per la distribuzione Ad Hoc, TestFlight e l'App Store. I certificati di distribuzione appartengono al team e solo i ruoli di Account Holder o Admin possono crearli. Apple limita il numero di certificati che un team può avere, quindi condividi uno in un archivio sicuro piuttosto che lasciare che ogni sviluppatore crei il proprio.

Potresti ancora vedere Sviluppo iOS E Distribuzione iOS in vecchi account. Sono i tipi pre-Xcode 11. Apple Development e Apple Distribution li sostituiscono e funzionano su iOS, iPadOS, macOS, tvOS, watchOS e visionOS.

Altri tipi di certificato che potresti incontrare

• ID sviluppatore di applicazione / di installazione: per le app Mac distribuite al di fuori dell'App Store Mac. Non utilizzato per iOS.
• Servizio di notifica Push di Apple SSL: certificati push legacy. Preferisci un APNs Auth Key (.p8), che non scade ogni anno e funziona per ogni app del team. Vedi il nostro guida ai certificati APNs.
• Identità del commerciante Apple Pay, ID del tipo di pass, ID di push del sito: servizi specifici.

Tipi di profilo di provisioning

Un profilo è legato a un ID AppSe il tuo app ha estensioni (un widget, un'estensione di servizio di notifica, un'estensione di condivisione), ogni destinazione ha il proprio ID bundle e richiede il proprio profilo.

Come si incastrano le parti

Quando Xcode o un servizio di costruzione firma il tuo Capacitor app verifica:

1. L'ID bundle nel tuo target (ad esempio com.example.app) corrisponde all'ID App nel profilo.
2. La chiave di firma utilizzata è una delle chiavi elencate nel profilo.
3. La chiave privata per quella chiave è disponibile nella chiave di accesso.
4. Per le costruzioni di sviluppo e ad hoc, l'ID dispositivo è presente nel profilo.
5. Il file di autorizzazioni (push, domini associati, gruppi di app) è un sottoinsieme di ciò che l'ID App e il profilo consentono.

Se un controllo fallisce, ottieni un errore di firma, non un crash di esecuzione, il che è positivo: scopri il problema prima di distribuire.

Quale combinazione ho bisogno?

TestFlight utilizza lo stesso stesso firmatario dell'App Store. Non esiste un profilo separato per TestFlight. Caricate un'unica build e decidete in App Store Connect se andrà ai tester, alla revisione o a entrambi.

Creazione di certificati e profili

Opzione 1: lascia che Xcode gestisca la firma

Per lo sviluppo locale è la soluzione più facile. Apri ios/App/App.xcworkspace (o il .xcodeproj quando il tuo progetto Capacitor 8 utilizza Swift Package Manager), seleziona il target target, open Signing & Capabilities, tick gestisci automaticamente la firma e scegli il tuo team. Xcode crea il certificato di sviluppo, registra il dispositivo collegato e genera i profili per te.

L'auto-sottoscrizione diventa dolorosa in CI, perché la macchina di costruzione ha bisogno di accesso al conto del team e crea i certificati da sola. La maggior parte dei team passa alla sottoscrizione manuale, o a un servizio di costruzione con la sottoscrizione basata sulla chiave API per le versioni di rilascio.

Opzione 2: crea manualmente su un Mac

1. Apre Accesso alla chiave > Assistente per certificati > Richiedi un certificato da un'autorità di certificazione. Inserisci la tua email, scegli Salvato su disco. Ciò crea la chiave privata nella tua chiave e un .certSigningRequest file.
2. In porta del developer Apple vai a Certificati, identificatori e profili > Certificati > +, scegli Apple Distribution (o Apple Development) e carica il CSR.
3. Scarica il .cer e doppio cliccandolo. Accesso alla chiave di sistema lo associa alla chiave privata.
4. Eseguire l'esportazione per CI: in Keychain Access, sotto I miei certificati, fai clic destro sul certificato, scegli EsportaSalva come .p12 con una password forte.

Opzione 3: crearli senza un Mac

Potete eseguire l'intera procedura con OpenSSL su Linux o 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

La -legacy flag matters con OpenSSL 3: senza di esso, il .p12 utilizza algoritmi di crittografia che gli strumenti di keychain di macOS rifiutano con un "errore di password non valida" anche quando la password è corretta.

Se preferisci non installare OpenSSL, il Generatore di certificati iOS Crea il CSR e la chiave privata per te. Vengono da un endpoint Capgo senza stato che non li memorizza, e solo il suo. .cer to .p12 Il convertitore esegue la sua funzione completamente nel browser. Se la tua politica richiede che la chiave sia generata sul tuo computer, utilizza i comandi OpenSSL sopra.

Identificatori > +

1. Identificatori > +Registrare un ID App con il proprio ID bundle esatto e abilitare le funzionalità utilizzate (Notifiche Push, Accesso con Apple, Domini associati…).
2. Dispositivi > +: per i profili di sviluppo e ad hoc, registrare l'ID UDID di ogni tester. I tester possono ottenerlo sul telefono stesso con il Finder di ID dispositivi iOS, non è necessario un Mac o un cavo.
3. Profili > +: scegliere il tipo di profilo, l'ID App, i certificato(i) e i dispositivi. Dà un nome chiaro, ad esempio com.example.app AppStore 2026.
4. Scarica il .mobileprovision file.

Se aggiungi un dispositivo o una capacità in seguito, devi rigenerare e riscaricare il profilo. I profili esistenti non si aggiornano da soli.

Esaminare un profilo

Un .mobileprovision file è un plist firmato. Su macOS puoi leggerlo:

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

In Linux openssl smime -inform der -verify -noverify -in App_Store.mobileprovision stampa il plist.

Per verificare con cosa è stato firmato un .ipa era firmato con:

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

Scadenza e rinnovo

• Certificati sono validi per un anno dalla creazione.
• Profili di provisioning scadono dopo un anno, o prima se il certificato che contengono scade o viene revocato.
• Le app di Store continuano a funzionare Dopo la scadenza del certificato di distribuzione. Apple riassegna i download dall'App Store. È necessario solo un nuovo certificato per caricare nuove build.
• Le build Ad Hoc e di sviluppo smettono di avviarsi una volta scaduto il loro profilo. I tester vedono l'app bloccarsi al lancio.
• Builds di TestFlight scadono 90 giorni dopo l'upload, indipendentemente dal certificato.
• Gli app di Enterprise smettono di funzionare su ogni dispositivo quando scade o viene revocato il certificato di enterprise. Rinnova prima della scadenza.
• Sedi di dispositivo Riavvio una volta all'anno di abbonamento. Rimuovere un dispositivo non libera la sua posizione fino all'inizio dell'anno di abbonamento successivo.

Inserisci la data di scadenza del certificato in un calendario condiviso. Il nostro guida alla gestione dei certificati copre la monitoristica e la rotazione in modo più approfondito.

Errori e soluzioni comuni

“Non trovato il certificato di firma ‘iOS Distribution’” o “Il certificato di firma è invalido”Il privato chiave non è presente in questa catena di chiavi. Importa la .p12o crea un nuovo certificato se nessuno ha la chiave.

Profilo di provisioning non include certificato di firmaIl profilo è stato creato con un diverso certificato. Modifica il profilo nel portale, seleziona il certificato corrente, rigenera e scarica.

“Il profilo di provisioning non include il dispositivo selezionato attualmente”Registrare l'ID UDID, quindi regenerare il profilo. Non necessario per TestFlight o App Store.

“Il profilo di provisioning non supporta la capacità di Push Notifications”Abilita la funzionalità sull'ID App, quindi rigenera il profilo. I profili sono snapshot.

“Non è stato trovato un profilo di provisioning valido per questo eseguibile” installazione: il dispositivo non è presente nel profilo ad hoc, o il profilo è scaduto.

App installs then closes immediately: sui dispositivi iOS 16 e successive, i build di sviluppo e ad hoc richiedono il Developer Mode. Vedi come abilitare il Developer Mode su iOS.

Le estensioni non riescono a firmare: ogni target di estensione richiede il proprio ID App e profilo. Controlla ogni target in Signing & Capabilities, non solo l'applicazione.

“Password non valida” quando si importa un .p12 creato su Linux: ricrea il file con openssl pkcs12 -export ... -legacy.

L'upload è stato rifiutato per la versione SDK: dal mese di aprile 2026 App Store Connect richiede build create con Xcode 26 e iOS 26 SDK. Aggiorna Xcode o il tuo immagine di CI. Capacitor 8 richiede già Xcode 26.

Buone pratiche per i team

• Una sola certificazione di distribuzione Apple per team, memorizzata come un .p12 in un gestore di password o un archivio di segreti, con la password memorizzata separatamente.
• Non inviare mai .p12 file o commettile su Git.
• Usa App Store Connect API chiavi (.p8Nomina i profili con ID bundle, tipo e anno.
• Rivoca i certificati delle persone che lasciano l'equipe.
• Revoca dei certificati per le persone che lasciano l'equipe.
• Mantieni una lista scritta di ogni ID bundle, estensione e capacità che l'app utilizza.

Firma cloud per le Capacitor app

Non è necessario avere un Mac sullo schermo di ogni sviluppatore per distribuire costruzioni iOS. Capgo Build costruisce Capacitor app sulle macchine macOS di Capgo utilizzando un .p12 e i dati del profilo che fornisci. I credenziali vengono utilizzate solo per la costruzione e non sono archiviate sui server Capgo. Salvali una volta dal 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 .

La Capgo Costruisci documentazione iOS elencare le opzioni di credenziali esatte, compresi i chiavi App Store Connect API per l'upload su TestFlight e ad_hoc modalità per le costruzioni di testatore.

Una volta che la tua prima costruzione è in TestFlight, puoi inviare modifiche JavaScript e asset agli utenti con Capgo aggiornamenti in tempo reale senza riassegna un nuovo binario per ogni correzione. Le modifiche native code e le nuove funzionalità richiedono ancora una costruzione firmata attraverso lo store.

Next steps

• Hai bisogno di account prima? Come creare account sviluppatori per Apple e Google Play.
• Come creare conti di sviluppatore Apple e Google Play Sei pronto a consegnare le costruzioni ai tester?.
• Invia? Leggi la nostra Guida alla sottomissione dell'app iOS.