Profilo di Provisioning: cos’è, quali tipi esistono e come funziona

Cos’è un Profilo di Provisioning

Un Profilo di Provisioning è un file di configurazione digitale in formato .mobileprovision (per iOS) o .provisionprofile (per macOS) che Apple utilizza per controllare l’installazione e l’esecuzione delle app sui dispositivi. Il profilo contiene metadati di firma del codice, senza i quali un’app non può essere eseguita su un iPhone, iPad o Apple Watch fisico — il simulatore non richiede un profilo perché il codice non viene firmato per l’esecuzione su un processore reale.

Il profilo viene rilasciato tramite l’Apple Developer Portal e ha una data di scadenza — generalmente un anno per i profili Development e Distribution. Secondo la politica Apple, il profilo viene automaticamente collegato al certificato Apple Developer Program con cui è stato firmato: se il certificato viene revocato o scade, il profilo smette di funzionare.

Ogni profilo contiene un UUID univoco che Xcode utilizza per identificare il profilo nel portachiavi. Xcode seleziona automaticamente il profilo appropriato durante la compilazione, ma lo sviluppatore può sovrascrivere la scelta nelle impostazioni Signing & Capabilities. Sul singolo dispositivo può essere installato un numero illimitato di profili — il sistema di gestione dei dispositivi mobili (MDM) di Apple utilizza questo per la distribuzione aziendale delle app.

Perché è necessario un Profilo di Provisioning

La firma del codice è la ragione principale dell’esistenza dei profili. Apple richiede che ogni app eseguita su un dispositivo iOS sia firmata con un certificato emesso da Apple. Il Profilo di Provisioning funge da collegamento: conferma che lo sviluppatore ha il diritto di eseguire l’app su quel dispositivo. Secondo Apple Security Guide (2025), il meccanismo dei profili impedisce l’installazione di malware sui dispositivi degli utenti anche in caso di compromissione del certificato dello sviluppatore.

Il profilo determina anche quali servizi di sistema sono disponibili per l’app. Se l’app utilizza le notifiche Push, Apple Push Notification service (APNs) richiede entitlements corretti all’interno del profilo. Senza questi, le notifiche del server non verranno consegnate al dispositivo. La stessa regola vale per iCloud, App Groups, Wallet, HealthKit e altri framework Apple.

Differenza da un certificato

Gli sviluppatori spesso confondono il Profilo di Provisioning con un Certificato Apple. Un certificato è un documento digitale che conferma l’identità (chi firma), mentre un profilo è una configurazione (quale app, su quali dispositivi, con quali autorizzazioni). Un certificato può essere utilizzato in più profili e un profilo è legato esattamente a un certificato. Apple raccomanda di creare un profilo separato per ogni app e ogni scenario — Development, Ad Hoc, App Store.

Come funziona un Profilo di Provisioning

Il processo di firma dell’app consiste in diversi passaggi sequenziali. Xcode prende il binario dell’app (App Bundle), lo firma con la chiave privata dello sviluppatore, incorpora il Profilo di Provisioning e lo invia al dispositivo. Il dispositivo verifica la firma con la chiave pubblica di Apple, confronta l’UUID del profilo con l’elenco dei profili fidati nel sistema e avvia l’app solo se tutti i controlli hanno successo.

Quando un utente scarica un’app dall’App Store, il meccanismo è diverso. App Store Connect ri-firma l’app con il proprio certificato Distribution di Apple, sostituendo il profilo dello sviluppatore con un profilo Store. Ciò significa che un’app pubblicata tramite l’App Store è tecnicamente firmata da Apple, non dallo sviluppatore — sebbene la firma originale dello sviluppatore venga verificata durante il caricamento del build in App Store Connect.

Per la distribuzione Ad Hoc, il profilo registra UDID di dispositivi specifici su cui l’app può essere eseguita. Un account gratuito Apple Developer Program limita i test a 100 dispositivi all’anno. I profili Enterprise (per la distribuzione interna in un’organizzazione) non hanno limiti di dispositivi ma richiedono un abbonamento attivo Apple Developer Enterprise Program dal costo di $299 all’anno.

Ciclo di vita del profilo

Il periodo di validità di un Profilo di Provisioning è di un anno dalla creazione. 30 giorni prima della scadenza, Apple inizia a inviare notifiche push allo sviluppatore tramite Xcode e Developer Portal. Se il profilo scade, un’app già installata continua a funzionare, ma non è possibile installare un nuovo build con quel profilo. Xcode genera un errore di firma del codice con codice -402620394 quando si tenta di compilare con un profilo scaduto. Apple raccomanda di impostare il rinnovo automatico dei profili tramite Xcode Accounts Preferences — Xcode rinnoverà il profilo 24 ore prima della scadenza.

Tipi di Profili di Provisioning

Apple offre quattro tipi principali di Profili di Provisioning, ciascuno progettato per una fase specifica del ciclo di vita dell’app. Il profilo Development consente di eseguire l’app su dispositivi fisici aggiunti all’Apple Developer Portal e viene utilizzato durante lo sviluppo e i test QA. Un account sviluppatore Apple gratuito è sufficiente per creare un profilo Development.

Il profilo Ad Hoc è progettato per distribuire un’app a un gruppo limitato di tester senza utilizzare l’App Store. Il profilo registra fino a 100 dispositivi per UDID e l’app può essere installata direttamente tramite iTunes, Apple Configurator o soluzioni MDM. I build Ad Hoc hanno un periodo di validità di 12 mesi e non richiedono la revisione di Apple.

Il profilo App Store viene utilizzato esclusivamente per pubblicare l’app sull’App Store e non contiene un elenco di dispositivi — Apple stessa gestisce la distribuzione dopo l’approvazione del build. Durante il caricamento di un archivio in App Store Connect, Xcode utilizza automaticamente il profilo App Store se è installato nel sistema. Il profilo Enterprise è per le organizzazioni con Apple Developer Enterprise Program e consente la distribuzione interna delle app senza limiti di dispositivi o revisione Apple.

Struttura di un Profilo di Provisioning

Un Profilo di Provisioning è un file in formato DER firmato da Apple, il cui contenuto può essere visualizzato tramite la riga di comando. Security framework di macOS permette di decodificare .mobileprovision in un plist XML leggibile. All’interno del profilo si trovano: UUID del profilo, App ID (prefisso del team + Bundle Identifier), elenco dei certificati, elenco dei dispositivi consentiti (solo per Development e Ad Hoc), entitlements e data di scadenza.

App ID è un identificatore univoco dell’app composto da un Team ID (10 caratteri assegnati da Apple) e un Bundle Identifier (ad esempio, com.example.myapp). Un App ID può essere esplicito (corrispondenza esatta con Bundle Identifier) o wildcard (pattern *.example.com per più app). Apple sconsiglia l’uso del wildcard per le app che utilizzano notifiche Push o iCloud — questi servizi richiedono un App ID esplicito.

Entitlements è un blocco XML all’interno del profilo che definisce i diritti di accesso dell’app alle risorse di sistema. Gli entitlements tipici includono: aps-environment (notifiche Push), com.apple.developer.icloud-services (iCloud), com.apple.security.application-groups (App Groups per Widget e Share Extension). Apple aggiunge automaticamente entitlements al profilo in base alle Capabilities abilitate in Xcode. Qualsiasi discrepanza tra gli entitlements nel profilo e quelli richiesti nel codice causa un errore di firma.

Creazione di un Profilo di Provisioning in Apple Developer

La creazione di un profilo è possibile in due modi: tramite l’interfaccia web dell’Apple Developer Portal o automaticamente tramite Xcode. Per un progetto tipico, Xcode gestisce i profili automaticamente con l’opzione Automatically manage signing attivata. Xcode crea un certificato, un profilo e un App ID in pochi secondi, sincronizzandosi con l’Apple Developer Portal. Tuttavia, le pipeline CI/CD richiedono una gestione manuale.

Per creare manualmente un profilo nell’Apple Developer Portal: vai su Certificates, Identifiers & Profiles, seleziona Profiles e premi "+". Quindi seleziona il tipo di profilo (Development, Ad Hoc, App Store o Enterprise), seleziona un App ID dall’elenco registrato, seleziona un certificato sviluppatore e (per Development e Ad Hoc) seleziona i dispositivi. Dopo la creazione, il profilo viene scaricato in formato .mobileprovision e installato con un doppio clic in Xcode.

I server CI/CD richiedono un approccio speciale: il profilo e il certificato devono essere conservati in un repository protetto (ad esempio, nei segreti di GitHub Actions). Durante la compilazione, il profilo viene caricato sull’agente, inserito nella cartella ~/Library/MobileDevice/Provisioning Profiles e il certificato viene importato nel portachiavi. Fastlane — un popolare strumento per l’automazione della firma — fornisce il comando match, che sincronizza profili e certificati tra gli sviluppatori tramite un repository git crittografato.

Esempio: verifica di un profilo tramite riga di comando

Per diagnosticare problemi di firma del codice, è possibile decodificare il .mobileprovision e verificarne il contenuto. Il comando seguente estrae il plist XML dal profilo e lo salva in un formato leggibile:

# Decodifica di .mobileprovision in XML
security cms -D -i "path/to/embedded.mobileprovision" \
  -o "profile.plist"

# Verifica della data di scadenza del profilo
plist -convert xml1 profile.plist -o -
grep -A 1 "ExpirationDate" profile.plist

L’utilità Security di macOS Command Line Tools decodifica il file di profilo firmato CMS. Il flag -D indica la decodifica, -i specifica il file di input. Dopo la decodifica, l’utilità plist converte il plist binario in XML e grep estrae la data di scadenza. Questo metodo è utile in CI/CD per verificare che il profilo non sia scaduto prima di compilare una release.

Errori comuni con i Profili di Provisioning

L’errore più comune è "No matching provisioning profiles found" durante la compilazione in Xcode. Si verifica quando Xcode non trova un profilo corrispondente alla configurazione di build: il Bundle Identifier non corrisponde all’App ID nel profilo, il certificato non è installato nel portachiavi o il profilo è scaduto. La soluzione — verificare le impostazioni Signing & Capabilities nel target e, se necessario, passare a Automatically manage signing.

L’errore "Provisioning profile doesn't include the selected device" appare quando si tenta di eseguire un build Development o Ad Hoc su un dispositivo il cui UDID non è stato aggiunto al profilo. L’Apple Developer Portal consente di aggiungere un dispositivo a un profilo esistente — dopo di che il profilo deve essere scaricato e reinstallato. Xcode con la gestione automatica della firma aggiunge automaticamente il dispositivo collegato al profilo.

Un problema con gli entitlements si manifesta con l’errore "The executable was signed with invalid entitlements" durante il caricamento in App Store Connect. La causa è una discrepanza tra gli entitlements nel profilo e quelli nel file .entitlements del progetto. Apple richiede che l’insieme dei diritti nel profilo sia un superinsieme dei diritti richiesti dall’app. La soluzione — verificare le Capabilities nel target di Xcode e assicurarsi che tutti i servizi abilitati abbiano entitlements corrispondenti nel profilo. Fastlane include il comando produce, che sincronizza gli App ID e i profili con gli entitlements correnti.