Provisioning Profile: ce este, ce tipuri există și cum funcționează

Ce este Provisioning Profile

Provisioning Profile este un fișier digital de configurare în format .mobileprovision (pentru iOS) sau .provisionprofile (pentru macOS), pe care Apple îl folosește pentru a controla instalarea și lansarea aplicațiilor pe dispozitive. Profilul conține metadatele semnării codului, fără de care aplicația nu poate fi lansată pe un iPhone, iPad sau Apple Watch fizic — simulatorul nu necesită profil, deoarece codul nu este semnat pentru rularea pe un procesor real.

Profilul este emis prin Apple Developer Portal și are o perioadă de valabilitate — de obicei un an pentru profilele Development și Distribution. Conform politicii Apple, profilul este automat legat de certificatul Apple Developer Program sub care a fost semnat: dacă certificatul este revocat sau expirat, profilul încetează să funcționeze.

Fiecare profil conține un UUID unic pe care Xcode îl folosește pentru a identifica profilul în lanțul de chei. Xcode selectează automat profilul potrivit la compilare, dar dezvoltatorul poate modifica selecția în setările Signing & Capabilities. Pe un dispozitiv pot fi instalate un număr nelimitat de profiluri — sistemul de gestionare a dispozitivelor Apple (MDM) folosește acest lucru pentru distribuția corporativă a aplicațiilor.

Pentru ce este necesar Provisioning Profile

Semnarea codului este motivul principal pentru existența profilurilor. Apple cere ca fiecare aplicație lansată pe un dispozitiv cu iOS să fie semnată cu un certificat emis de Apple. Provisioning Profile acționează ca o verigă de legătură: confirmă că dezvoltatorul are dreptul de a rula aplicația pe acest dispozitiv. Potrivit Apple Security Guide (2025), mecanismul profilurilor previne instalarea software-ului malițios pe dispozitivele utilizatorilor chiar și în cazul compromiterii certificatului dezvoltatorului.

Profilul definește, de asemenea, ce servicii de sistem sunt disponibile aplicației. Dacă aplicația folosește notificări Push, Apple Push Notification service (APNs) necesită entitlements corecte în interiorul profilului. Fără acestea, notificările de server nu vor fi livrate pe dispozitiv. O regulă similară se aplică pentru iCloud, App Groups, Wallet, HealthKit și alte framework-uri Apple.

Diferența față de certificat

Dezvoltatorii confundă adesea Provisioning Profile cu Apple Certificate. Certificatul este un document digital care confirmă identitatea (cine semnează), iar profilul este o configurare (ce aplicație, pe ce dispozitive, cu ce drepturi). Un certificat poate fi folosit în mai multe profiluri, iar un profil este legat exact de un certificat. Apple recomandă crearea unui profil separat pentru fiecare aplicație și fiecare scenariu — Development, Ad Hoc, App Store.

Cum funcționează Provisioning Profile

Procesul de semnare a aplicației constă în mai mulți pași executați secvențial. Xcode preia fișierul binar al aplicației (App Bundle), îl semnează cu cheia privată a dezvoltatorului, încorporează Provisioning Profile în el și îl trimite pe dispozitiv. Dispozitivul verifică semnătura cu cheia publică a Apple, compară UUID-ul profilului cu lista profilurilor de încredere din sistem și lansează aplicația doar dacă toate verificările au succes.

Când utilizatorul descarcă aplicația din App Store, mecanismul este diferit. App Store Connect resemnează aplicația cu propriul certificat Distribution al Apple, înlocuind profilul dezvoltatorului cu un profil Store. Aceasta înseamnă că aplicația publicată prin App Store este tehnic semnată de Apple, nu de dezvoltator — deși semnătura inițială a dezvoltatorului este verificată la etapa de încărcare a build-ului în App Store Connect.

Pentru distribuția Ad Hoc, profilul înregistrează UDID-urile dispozitivelor specifice pe care este permisă lansarea. Contul gratuit Apple Developer Program limitează la 100 de dispozitive pe an pentru testare. Profilele Enterprise (pentru distribuția internă în organizație) nu au limită la numărul de dispozitive, dar necesită un abonament activ Apple Developer Enterprise Program cu un cost de $299 pe an.

Ciclul de viață al profilului

Perioada de valabilitate a Provisioning Profile este de un an de la momentul creării. Cu 30 de zile înainte de expirare, Apple începe să trimită notificări push dezvoltatorului prin Xcode și Developer Portal. Dacă profilul expiră, aplicația de pe dispozitiv continuă să funcționeze (dacă este deja instalată), dar un build nou cu acest profil nu va putea fi instalat. Xcode la încercarea de compilare cu un profil expirat returnează o eroare de semnare a codului cu codul -402620394. Apple recomandă configurarea reînnoirii automate a profilurilor prin Xcode Accounts Preferences — atunci Xcode actualizează profilul cu 24 de ore înainte de expirare.

Tipuri de Provisioning Profile

Apple oferă patru tipuri principale de Provisioning Profile, fiecare destinat unei etape specifice din ciclul de viață al aplicației. Profilul Development permite lansarea aplicației pe dispozitive fizice adăugate în Apple Developer Portal și este folosit în etapa de dezvoltare și testare QA. Pentru crearea profilului Development este suficient un cont gratuit de dezvoltator Apple.

Profilul Ad Hoc este destinat distribuirii aplicației către un cerc restrâns de testeri fără utilizarea App Store. Profilul înregistrează până la 100 de dispozitive după UDID, iar aplicația poate fi instalată direct prin iTunes, Apple Configurator sau soluții MDM. Build-urile Ad Hoc au o perioadă de valabilitate de 12 luni și nu necesită trecerea prin review-ul Apple.

Profilul App Store este folosit exclusiv pentru publicarea aplicației în App Store și nu conține o listă de dispozitive — Apple însăși gestionează distribuția după aprobarea build-ului. La încărcarea arhivei în App Store Connect, Xcode folosește automat profilul App Store dacă acesta este instalat în sistem. Profilul Enterprise este destinat organizațiilor cu Apple Developer Enterprise Program și permite distribuirea aplicațiilor în interiorul companiei fără limitarea numărului de dispozitive și fără review Apple.

Structura Provisioning Profile

Provisioning Profile este un fișier în format DER semnat de Apple, al cărui conținut poate fi vizualizat prin linia de comandă. Security framework din macOS permite decodarea .mobileprovision într-un plist XML lizibil. În interiorul profilului se află: UUID-ul profilului, App ID (prefixul echipei + Bundle Identifier), lista certificatelor, lista dispozitivelor permise (doar pentru Development și Ad Hoc), entitlements și perioada de valabilitate.

App ID — identificatorul unic al aplicației, format din Team ID (10 caractere, atribuit de Apple) și Bundle Identifier (de exemplu, com.example.myapp). App ID poate fi explicit (potrivire exactă cu Bundle Identifier) sau wildcard (șablon *.example.com pentru mai multe aplicații). Apple nu recomandă utilizarea wildcard pentru aplicațiile care folosesc notificări Push sau iCloud — aceste servicii necesită un App ID explicit.

Entitlements — blocul XML din interiorul profilului care definește drepturile de acces ale aplicației la resursele de sistem. Entitlements tipice includ: aps-environment (notificări Push), com.apple.developer.icloud-services (iCloud), com.apple.security.application-groups (App Groups pentru Widget și Share Extension). Apple adaugă automat entitlements în profil pe baza Capabilities activat în Xcode. Orice nepotrivire între entitlements din profil și cele solicitate în cod duce la o eroare de semnare.

Crearea Provisioning Profile în Apple Developer

Crearea profilului este posibilă în două moduri: prin interfața web Apple Developer Portal sau automat prin Xcode. Pentru un proiect tipic, Xcode gestionează profilele automat când opțiunea Automatically manage signing este activată. Xcode creează certificatul, profilul și App ID în câteva secunde, sincronizându-se cu Apple Developer Portal. Cu toate acestea, pentru pipeline-urile CI/CD este necesară gestionarea manuală.

Pentru crearea manuală a profilului în Apple Developer Portal este necesar: să intri în secțiunea Certificates, Identifiers & Profiles, să selectezi Profiles și să apeși „+". Apoi să selectezi tipul de profil (Development, Ad Hoc, App Store sau Enterprise), să alegi App ID din lista înregistrată, să selectezi certificatul dezvoltatorului și (pentru Development și Ad Hoc) să selectezi dispozitivele. După creare, profilul se descarcă în format .mobileprovision și se instalează cu dublu clic în Xcode.

Serverele CI/CD necesită o abordare specială: profilul și certificatul trebuie stocate într-un depozit securizat (de exemplu, în secrets pentru GitHub Actions). La compilare, profilul este încărcat pe agent, plasat în folderul ~/Library/MobileDevice/Provisioning Profiles, iar certificatul este importat în lanțul de chei. Fastlane — instrumentul popular pentru automatizarea semnării — oferă comanda match, care sincronizează profilele și certificatele între dezvoltatori printr-un depozit git criptat.

Exemplu: verificarea profilului prin linia de comandă

Pentru diagnosticarea problemelor de semnare a codului, puteți decoda .mobileprovision și verifica conținutul acestuia. Comanda de mai jos extrage plist-ul XML din profil și îl salvează într-un format lizibil:

# Decodificarea .mobileprovision în XML
security cms -D -i "path/to/embedded.mobileprovision" \
  -o "profile.plist"

# Verificarea perioadei de valabilitate a profilului
plist -convert xml1 profile.plist -o -
grep -A 1 "ExpirationDate" profile.plist

Utilitarul Security din componența macOS Command Line Tools decodifică fișierul CMS semnat al profilului. Flag-ul -D înseamnă decodare, -i — fișierul de intrare. După decodare, utilitarul plist convertește plist-ul binar în XML, iar grep extrage data expirării. Această metodă este utilă în CI/CD pentru a verifica că profilul nu este expirat înainte de compilarea build-ului de release.

Erori tipice cu Provisioning Profile

Cea mai frecventă eroare este „No matching provisioning profiles found" la compilare în Xcode. Ea apare când Xcode nu poate găsi un profil corespunzător configurației de compilare: Bundle Identifier nu se potrivește cu App ID din profil, certificatul nu este instalat în lanțul de chei sau profilul este expirat. Soluția — verificați setările Signing & Capabilities din target și, dacă este necesar, comutați pe Automatically manage signing.

Eroarea „Provisioning profile doesn't include the selected device" apare la încercarea de a rula un build Development sau Ad Hoc pe un dispozitiv al cărui UDID nu a fost adăugat în profil. Apple Developer Portal permite adăugarea dispozitivului la un profil existent — după aceasta profilul trebuie descărcat și instalat din nou. Xcode la gestionarea automată a semnării adaugă dispozitivul conectat la profil automat.

Problema cu entitlements se manifestă prin eroarea „The executable was signed with invalid entitlements" la încărcarea în App Store Connect. Cauza — nepotrivirea entitlements din profil cu fișierul .entitlements al proiectului. Apple cere ca setul de drepturi din profil să fie o supra-mulțime a drepturilor solicitate de aplicație. Soluția — verificați Capabilities în target-ul Xcode și asigurați-vă că toate serviciile activate au entitlements corespunzătoare în profil. Fastlane include comanda produce care sincronizează App ID și profilele cu entitlements actualizate.