Certificati e provisioning profile iOS spiegati

La firma iOS code si basa su due elementi. Un certificato attesta chi ha creato l'app, mentre un profilo di provisioning specifica quale app è, su quali dispositivi può essere eseguita e quali funzionalità può utilizzare. Xcode rifiuta la build per un dispositivo e App Store Connect rifiuta gli upload se certificato, chiave privata e profilo corrispondente non sono allineati.

Questa guida spiega ogni componente, quali combinazioni servono per build di sviluppo, ad hoc, TestFlight, App Store ed enterprise, come crearle con o senza un Mac e come risolvere gli errori che incontrerai.

Perché Apple richiede la firma code

Apple consente agli iPhone di eseguire solo code che può tracciare fino a uno sviluppatore noto. La firma offre ad Apple tre garanzie:

1. Identità: il binario è stato firmato da un membro di un team Apple Developer specifico.
2. Integrità: nessuno ha modificato il binario dopo la firma. Cambiare anche un solo byte invalida la firma.
3. Autorizzazione: l'app è autorizzata su questo dispositivo, con questi entitlement (push, iCloud, Sign in with Apple, App Groups e così via).

I certificati forniscono i primi due. I profili di provisioning forniscono il terzo.

I mattoni fondamentali

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

Tipi di certificato

Sviluppo Apple

Servono per eseguire build sui tuoi dispositivi tramite Xcode durante lo sviluppo. I certificati Development appartengono a un singolo sviluppatore e Apple li etichetta con il nome del computer. Ogni sviluppatore del team può avere il proprio.

Distribuzione Apple

Usato per firmare i build per la distribuzione Ad Hoc, TestFlight e App Store. I certificati di distribuzione appartengono al team e solo i ruoli Account Holder o Admin possono crearli. Apple limita il numero di certificati che un team può detenere, quindi condividetene uno tramite un archivio sicuro anziché farne creare uno a ogni sviluppatore.

Potresti ancora vedere Sviluppo iOS e Distribuzione iOS nei vecchi account. Si tratta dei 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

• Developer ID Application / Installer: per le app Mac distribuite al di fuori del Mac App Store. Non viene utilizzato per iOS.
• SSL del servizio di notifica push di Apple: certificati push legacy. Preferisci un Chiave di autenticazione APNs (.p8), che non scade annualmente e funziona per tutte le app del team. Consulta la nostra guida ai certificati APNs.
• Merchant Identity di Apple Pay, Pass Type ID, Website Push ID: servizi specifici.

Tipi di provisioning profile

Un profilo è legato a un App ID. Se la tua app ha estensioni (un widget, un'estensione di servizio notifiche, un'estensione di condivisione), ogni target ha il proprio bundle ID e richiede il proprio profilo.

Come si incastrano i pezzi

Quando Xcode o un servizio di build firma la tua app Capacitor, verifica:

1. L'ID bundle nel tuo target (ad esempio com.example.app) corrisponde all'App ID nel profilo.
2. Il certificato utilizzato per la firma è uno di quelli elencati nel profilo.
3. La chiave privata per quel certificato è disponibile nel keychain.
4. Per build di sviluppo e ad hoc, l'UDID del dispositivo è presente nel profilo.
5. Il file entitlements (push, domini associati, App Groups) è un sottoinsieme di ciò che l'App ID e il profilo consentono.

Se un controllo fallisce, ricevi un errore di firma, non un crash a runtime: così lo scopri prima di rilasciare.

Quale combinazione mi serve?

TestFlight utilizza la stessa stesso firma dell'App Store. Non esiste un profilo TestFlight separato. Carichi un'unica build e decidi in App Store Connect se mandarla ai tester, in revisione o entrambe le cose.

Creazione di certificati e profili

Opzione 1: lasciare che Xcode gestisca la firma

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

Il signing automatico diventa un problema in CI, perché la macchina di build deve avere accesso all'account del team e crea certificati per conto proprio. La maggior parte dei team passa al signing manuale, oppure a un servizio di build con signing basato su API key, per le build di release.

Opzione 2: crearli manualmente su un Mac

1. Apri Accesso Portachiavi > Assistente Certificato > Richiedi un certificato a un'autorità di certificazione. Inserisci la tua email, scegli Salvato su disco. Questo crea la chiave privata nel keychain e un .certSigningRequest file.
2. Nel portale Apple Developer vai a Certificati, identificatori e profili > Certificati > +, scegli Distribuzione Apple (o Apple Development) e carica il CSR.
3. Scarica l'app .cer e fai doppio clic. Keychain Access lo associa alla chiave privata.
4. Per esportare per la CI: in Keychain Access, sotto I miei certificati, fai clic destro sul certificato, scegli Esporta, salva come .p12 con una password forte.

Opzione 3: crearli senza un Mac

Puoi eseguire l'intero flusso 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

Il -legacy il flag conta con OpenSSL 3: senza di esso, il .p12 usa algoritmi di crittografia che gli strumenti keychain di macOS rifiutano con un errore “password non valida”, anche se la password è corretta.

Se preferisci non installare OpenSSL, il Generatore di certificati iOS crea il CSR e la chiave privata per te. Provengono da un endpoint Capgo stateless che non li memorizza, e solo il suo .cer a .p12 converter gira interamente nel tuo browser. Se la tua policy richiede che la chiave venga generata sulla tua macchina, usa i comandi OpenSSL sopra.

Creazione del profilo

1. Identificatori > +: registra un App ID con il tuo bundle ID esatto e abilita le capability che usi (Push Notifications, Sign in with Apple, Associated Domains…).
2. Dispositivi > +: per i profili di sviluppo e ad hoc, registra l'UDID di ogni tester. I tester possono ottenerlo direttamente sul telefono con il Trova UDID iOS, senza bisogno di Mac o cavo.
3. Profili > +: scegli il tipo di profilo, l'App ID, il/i certificato/i e i dispositivi. Dagli un nome chiaro, ad esempio com.example.app AppStore 2026.
4. Scarica l'app .mobileprovision file.

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

Ispezionare 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

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

Per verificare con cosa è stato firmato un .ipa è stato 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 incluso scade o viene revocato.
• Le app su App Store continuano a funzionare dopo la scadenza del certificato di distribuzione. Apple firma nuovamente i download da App Store. Serve un nuovo certificato solo per caricare nuovi build.
• Le build Ad Hoc e di sviluppo smettono di avviarsi una volta scaduto il profilo. I tester vedono l'app crashare all'avvio.
• Le build su TestFlight scadono 90 giorni dopo il caricamento, indipendentemente dal certificato.
• Le app Enterprise smettono di funzionare su ogni dispositivo quando il certificato enterprise scade o viene revocato. Rinnova prima della scadenza.
• Slot dispositivo si azzera una volta all'anno di membership. La rimozione di un dispositivo non libera il suo slot fino all'inizio del nuovo anno di membership.

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

Errori comuni e soluzioni

“Certificato di firma ‘iOS Distribution’ non trovato” oppure “Certificato di firma non valido”: la chiave privata non è in questo keychain. Importa la .p12, oppure crea un nuovo certificato se nessuno ha la chiave.

“Provisioning profile doesn’t include signing certificate”: il profilo è stato creato con un certificato diverso. Modifica il profilo nel portale, seleziona il certificato attuale, rigenera e scarica.

“Il provisioning profile non include il dispositivo attualmente selezionato”: registra l'UDID, poi rigenera il profilo. Non necessario per TestFlight o App Store.

“Il provisioning profile non supporta la funzionalità Push Notifications”: abilita la capability sull'App ID, poi rigenera il profilo. I profili sono snapshot.

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

L'app si installa e poi si chiude immediatamente: su iOS 16 e versioni successive, le build di sviluppo e ad hoc richiedono il Developer Mode sul dispositivo. Vedi come attivare la Modalità sviluppatore su iOS.

Le estensioni non riescono a firmare: ogni target di estensione richiede il proprio App ID e profilo. Controlla tutti i target in Firma e capacità, non solo App.

“Password non valida” durante l’importazione di un .p12 creato su Linux: ricrealo con openssl pkcs12 -export ... -legacy.

Upload rifiutato per la versione SDK: da aprile 2026 App Store Connect richiede build create con Xcode 26 e il SDK iOS 26. Aggiorna Xcode o l’immagine CI. Capacitor 8 richiede già Xcode 26.

Buone pratiche per i team

• Un certificato Apple Distribution per team, salvato come .p12 in un password manager o secrets store, con la password salvata separatamente.
• Non via email .p12 file o commitarli su git.
• Usa le chiavi API di App Store Connect (.p8) per gli upload invece delle password Apple ID.
• Nominare i profili con bundle ID, tipo e anno.
• Revocare i certificati delle persone che lasciano il team.
• Mantenere un elenco scritto di ogni bundle ID, estensione e capacità utilizzata dall'app.

Firma in cloud per app Capacitor

Non serve un Mac sulla scrivania di ogni sviluppatore per rilasciare build iOS. Build Capgo esegue il build di app Capacitor sulle macchine macOS di Capgo usando un .p12 e il profilo che fornisci. Le credenziali servono solo per il build e non vengono salvate sui server Capgo. Salvale una volta da 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 .

Il Documentazione Build iOS di Capgo elenca le opzioni esatte per le credenziali, incluse le chiavi App Store Connect API per l'upload su TestFlight e ad_hoc la modalità per le build di test.

Una volta che la prima build è su TestFlight, puoi inviare modifiche a JavaScript e asset agli utenti con Live updates di Capgo senza dover rifirmare un nuovo binario per ogni fix. Le modifiche code Native e le nuove capacità richiedono comunque un build firmato tramite lo store.

Prossimi passi

• Servono prima gli account? Come creare account sviluppatore Apple e Google Play.
• Pronto a consegnare le build ai tester? Come distribuire app iOS e Android ai tester.
• Stai per inviare? Leggi la nostra guida all'invio di app iOS.